How to write Plugins

How to write plugins for the News app

You've got this cool idea that you'd like the News app to have but the developers are pricks and don't want to implement it? Create a plugin!

General plugin infos

A plugin is in essence a seperate app. You should first read the intro and tutorial and create the basic files.

In addition to the basic structure you also want to make sure that the News app is enabled. To do that open mynewsplugin/appinfo/app.php and add the following if:

<?php   
namespace OCA\MyNewsPlugin\AppInfo;

if (\OCP\App::isEnabled('news')) {
    // your code here
}

If your plugin integrates with another ownCloud app, make sure to also require it be installed. If you depend on the bookmarks app for instance use:

<?php   
namespace OCA\MyNewsPlugin\AppInfo;

if (\OCP\App::isEnabled('news') && \OCP\App::isEnabled('bookmarks')) {
    // your code here
}

Serverside plugin

A serverside plugin is a plugin that uses the same infrastructure as the news app for its own purposes. An example would be a plugin that makes the starred entries of a user available via an interface or a bookmark app that that also shows starred articles as bookmarks.

Its very easy to interface with the News app. Because all Classes are registered in the news/app/application.php it takes almost no effort to use the same infrastructure.

Since you dont want to extend the app but use its resources, its advised that you dont inherit from the Application class but rather include it in your own container in mynewsplugin/appinfo/application.php:

<?php 
namespace OCA\MyNewsPlugin\AppInfo;

use OCP\AppFramework\App;
use OCA\News\AppInfo\Application as News;

class Application extends App {

    public function __construct (array $urlParams=[]) {
        parent::__construct('mynewsplugin', $urlParams);

        $container = $this->getContainer();

        $container->registerService('NewsContainer', function($c) {
            $app = new News();
            return $app->getContainer();
        });

        $container->registerService('OCA\News\Service\FeedService', function($c) {
            // use the feed service from the news app, you can use all 
            // defined classes but its recommended that you stick to the 
            // mapper and service classes since they are less likely to change
            return $c->query('NewsContainer')->query('OCA\News\Service\FeedService');
        });
    }
    
}

Using automatic container assembly you can then use it from your code by simply adding the type to your constructors.

An example for a serverside plugin that turns your feeds into a separate RSS feed can be found on GitHub

Clientside plugin

A client side plugin is a plugin that ships additional JavaScript and/or CSS. To register JavaScript or CSS for the News app, simply do the following inside your mynewsplugin/appinfo/app.php:

// check if the News app accepts client plugins
if (class_exists('OCA\News\Plugin\Client\Plugin')) {
    // include mynewsplugin/js/script.js
    \OCA\News\Plugin\Client\Plugin::registerScript('mynewsplugin', 'script');
    
    // include mynewsplugin/css/style.js
    \OCA\News\Plugin\Client\Plugin::registerStyle('mynewsplugin', 'style');
}

This will load your styles/scripts after the News app's styles and scripts are loaded.

Article action plugin

An article action is a button that is displayed above the article. This can be used for instance to add Twitter share buttons for each article. Built in and not overwritable actions include starring or keeping an article as unread.

Custom article action plugins are registered like normal client side plugins but need to register themselves as article action plugins:

mynewsplugin/js/script.js

(function (window, $, News, OC, undefined) {
    'use strict';

    News.addArticleAction(function(actionsElement, article) {
        var li = $('<li>')
            .addClass('article-plugin-epub');
        var button = $('<button>')
            .attr('title', t('newsplugin', 'Export as EPub'));
        button.click(function (event) {
            var url = 'http://fivefilters.org/kindle-it/send.php' +
                      '?context=download&format=epub&url=' + article.url;
            window.open(url);
            event.stopPropagation();  // prevent expanding in compact mode
        });

        li.append(button);
        actionsElement.append(li);
    });

})(window, jQuery, News, OC);

mynewsplugin/css/style.css

.article-plugin-epub button {
    background-image: url('../img/epub.svg');
}

The addArticleAction method expects an function with the following parameters:

• actionsElement: The DOM element wrapped in jQuery where your plugin should be appended to
• article: readonly article object of the current article. The article object has the following attributes:
  • id: the article id in the News database
  • url: the article url it points to
  • title: the article title
  • author: the article author
  • pubDate: the article published date, a unix timestamp
  • body: the html content
  • enclosureMime: if an enclosure is added, this is the mime type
  • enclosureLink: this is the source of the enclosure
  • feedId: the feed id it belongs to
  • unread: if the article is unread (bool)
  • starred: if the article is starred (bool)
  • lastModified: the last modified date

Examples

• Mail Share -- Client-side plugin to share articles by email.