Javascript plugins

Javascript plugins are an easy way to provide some packaged javascript features. It’s especially helpful to keep a third party product separated and up to date.

Note that it’s not a specific kind of plugin, it’s just a feature a regular plugin can propose, so you can have your own “javascript plugins” and use them in your plugin (or site) or from another plugin or site.

We’ll study Pines Notification, a library shipped with and used by the default PHPDevShell distribution.

Set up

As noted above, a JS plugin is just a regular plugin, so we have in the plugins folder a PinesNotify folder, containing these folders:

• config: for the plugin.config.xml file
• images: just the icon in the plugin manager
• includes: for the GUI_notify.class.php class file
• public: containing the files provided by the library

The library files

As the library is javascript code and it’s related files, we’ll place the downloaded files just inside our public folder. We could only copy the files we’ll be actually using, but I like to keep the original distribution intact, we I usually put all their files together.

The config file

We will only provide a single class, so the declaration is simple:

<install version="1000">
	<classes>
		<class name="GUI_pnotify" alias="pnotify" plugin="PinesNotify" />
	</classes>
</install>

You can refer to TODO for a complete description of the config xml file.

The rest of the file is purely descriptive; you can read it here.

OK now the class is known to the system, let’s see what’s inside it.

The PHP class

The purpose of the PHP class is to give the framework the necessary entry points to add the JS code to our page. It must implement the iPHPDS_activableGUI interface and as you can see it’s really simple:

interface iPHPDS_activableGUI
{
    public function activate($path);
}

The only method is activate($path) which will be called with a path to the plugins files.

!Note that the $path is given without a trailing slash, you may want to add it depending on how you plan to use it later.

So:

public function activate($path)
    {
        $file = $this->configuration['development']
            ? 'jquery.pnotify.js'
            : 'jquery.pnotify.min.js';

        $template = $this->template;

        $template->addJsFileToBottom($path.'/public/'.$file);

        $template->addCssFileToHead($path.'/public/jquery.pnotify.default.css');
        $template->addCssFileToHead($path . '/public/jquery.pnotify.default.icons.css');
        $template->addCssFileToHead($path . '/public/oxygen/icons.css');

        $template->addJsToHead(
         '
            $(function(){
                $.pnotify.defaults.styling = "jqueryui";
            });
        '
        );
    }

the first part is a simple way to select a different library on the development and production systems; then we add the JS and CSS files. We are also given the opportunity to add some custom code, in this case defaults values.

You can read the whole file here.

Manual Usage

As you already figured out, using such a plugin is simple:

$this->template->activatePlugin('GUI_pnotify');

The activate() function will be called, hence adding all the required links/CSS/JS to be used at the proper time. Of course it requires that you use a compatible theme, since the theme code is responsible for adding the necessary lines
to the ouput (“cloud” and “emptyCloud” are compatible).

You usually use this call from your controller execute() method, but you can use it anywhere between the template initialization and the actual output.

Note that you can also pass additional parameters to activatePlugin() and they will be passed as such to the activate() method.

Automatic usage

If you want you GUI plugin to be automatically added to the page (provided the theme supports it, such as the default “Cloud” theme), just register your class with the magic alias GUI_JS_AUTOMATIC. For example:

<install version="1000">
	<classes>
		<class name="GUI_pnotify" alias="GUI_JS_AUTOMATIC" plugin="PinesNotify" />
	</classes>
</install>