I – Silex Plugins
a/Introduction
Plugins extends basics Silex functionnalities. All Silex Plugins are installed in the “plugins/” folder, each one having it’s own folder. For exemple, in Silex base distribution, the “wysiwyg” plugin can be found, allowing publications editing. The “snapshot” plugin can also be found, handling publication thumbs pictures creation. Those captures are then used by the manager to display the publication preview. You can find more plugins on the Silex exchange platform : www.silexlabs.org/plugins/ or in the manager using the exchange platform plugin. If you downloaded the plugin from the exxhnage platforme, just unzip the downloaded .zip in the plugins/ folder to install it, with the manager’s plugin, the installation is automatic. > see also the tutorial HelloSilex, creating a silex plugin
b/requirements
Creating a Silex Plugin implies a a basic knowledge of php5 (with classes) . Most Silex Plugin use a mix of PHP, to communicate with Silex Server, JavaScript to communicate with Silex Javascript API, Actrionscript 2 to communicate with Silex Core and ActionScript 3 for the AS3 plugins (mainly the ViewMenu plugin). All languages apart from PHP are optionnals.
related topics
II – Creating a Silex Plugin
a/ the index.php file
Silex server accesses each plugin by reading the index.php file located at the plugin’s folder root. ex: for the “snapshot” plugin, this file is located in the “plugins/snapshot/index.php” folder When you navigate to a silex publication, the Silex server will scan all plugins/ folders looking for all index.php files. The index.php file must be a class with the same name than the plugins folder and extending the “plugin_base” class located in “cgi/includes” folder of the server. To do so, the first line of the index.php file must include : require_once ROOTPATH.’cgi/includes/plugin_base.php’; where ROOTPATH is the root of the Silex server. You then need to override methods from the base plugin class to set the behaviour of your plugin.
b/ Silex hooks
Your plugins needs to add callbacks to the Silex hook manager. If you’re not familiar with Silex hook system, you can find an introduction here (TO DO). You can add both PHP and Javascript hooks in your class. To init your plugin you need to override the initHooks method, the plugin super-class will pass a reference to the hook manager as an argument. You use this reference to add PHP hooks to the hook manager.
PHP HOOKS
Silex server’s index.php file calls different hooks at start-up indicating the initialisation progress. Silex’ s hook that most plugins need to use is “index-body-end” which is called when Silex server ‘s index.php (and not the plugin’s one) has finished server initialisation. Then the plugin can be loaded, knowing that all Silex Core references will be existing. Look the “initHooks” method in the “toolTip” index.php for an exemple of how to add a PHP hook. Here is the list of all the hooks called at start-up:
- index-head – called just after the “<head>” tag.
- index-noembed -
- index-script – called before the initalisation of Silex JavaScript API
- index-body-end – called last in silex server’s index.php
Another useful hook is the “admin-body-end” PHP hook called when the user logs in, this hook must be used for tool plugins (see below) insted of “index-body-end” as some plugin must only be activated for an admin user and not a simple visitor. You can find an exemple of an “admin-end-hook in the index.php of the snapshot plugin. You can find the complete list of hooks here (TO DO).
USING JAVASCRIPT
In the PHP hooks callback you can also add Javascript hooks to the JavaScript hook manager by inserting a “<script>” tag in the callback body. You can look at the index.php of the snaphot plugin for an exemple. In this exemple, we see that the added JavaScript is used to add an item in the view menu, used to take a snapshot. The Silex JavaScript API has also it’s own hookManager used to call hook for instance when the browser is resized.
c/ The Tools Plugins
Tools Plugins are a sub-category of Silex Plugins. A Tool Plugin is a plugin only used in admin mode, and typically loaded after the “admin-body-end” hook has been called on the Silex PHP Hook Manager. It’s up to the developper to create a regular or tool plugin, based on usage. For instance, google analytics plugin, storing states on a publication usage when activated, only needs to work for end-user. On the other hand, the snapshot plugin, capturing a preview of a publication only makes sense when the user is a logged admin.
d/ Silex Plugins Parameters
You can add plugin’s parameters which can be set by user in the manager (see V – Silex Plugins and manager). These parameters are added using PHP. In the google analytics plugin, for instance, a specific parameter is added to allow the user to enter his google account number in the manager. To do so, you need to override in the plugin’s class the “initDefaultParamTable” method. This is where you set the “paramTable” variable of the “plugin_base” class, setting it to an array of associative arrays containing your params. Each associative array is a parameter, in which you define the name, the label (the name that will appear in the manager), the description (the description that will appear in the manager), the value (the default value), the restriction (allowed characters), the type of data (string,number, boolean) and the maximum number of characters. ex: see the “initDefaultParamTable” method in the snapshot index.php. You can then use those parameters anywhere in your class, or in another PHP method or by setting values in your JavaScript’s code . ex: in the “snapshot” plugin index.php, a param is used to set the location of the swf file loaded in the ViewMenu. We can see in the “set_view_menu_item” method that the PHP variable containing the url of the swf is used in the JavaScript method. special case of AS2 In AS2 you can get a direct reference to the parameters which are stored on the config object of Silex. ex: to get a “myPluginParam” where “myPluginParam” is one of the paramters you added in PHP, you can use the following ActionScript 2 code : _global.getSilex().config.myPluginParam;
III – Silex Plugins and Silex Core
Once initialised, the Silex Plugins can interact with Silex application core (coded in ActionScript 2) via JavaScript. JavaScript is used to call AS2 method defined in the Silex Core via ExternalInterface callbacks. ex: in the “snapshot” plugin index.php, we can see in the “init_snap_shot_tool” method that “SetVariable” Silex Core’s method is called. This method is used to add the snapshot_tool.swf to Silex publication. Those methods are either included in Silex Core or added by the plugins themselves. ex: the snapshot plugin, once added to Silex, add his own ExternalInterface callback to Silex which can then be called via JavaScript. We can see in “the snap_shot_tool_js_print” method that a “snap_shot_tool_silex_element_snapshot” method is called on Silex that was added by the snapshot plugin. You can see where the callback is added in the snapshot plugin AS2 source available here: https://silex.svn.sourceforge.net/svnroot/silex/apps/third-party/plugins/snapshot/source/snapshot.
IV – Silex Plugins and ViewMenu
The ViewMenu is the only permanent Silex Plugin. All the other plugins can add an icon on the ViewMenu that will be used by the user to interact with your plugin. When a plugin is initialised, he can add any number of items and groups of items in the View Menu via Javascript. You can look at the index.php of the snpshot plugin in which the “set_view_menu_item()” adds an item to the viewMenu. The added item is a swf that contain it’s own logic. ex: The “snap_shot_tool_view_menu_item.swf” file loaded in the ViewMenu when the snapshot plugin is loaded calls the JS “snap_shot_tool_js_print” method when clicked, launching the screen capture. Look-up the source of the AS3 icon at this adress: https://silex.svn.sourceforge.net/svnroot/silex/apps/third-party/plugins/snapshot/source/snapshot_view_menu_item.
V – Silex Plugins and Manager
When your plugin is set and installed in the plugins/ folder, go to the manager to activate it at server or publication level and to edit it’s parameters.
a/ activating a plugin at server level
When a plugin is actived at server level it is activated for all the server’s publications. ex: the “wysiwyg” and “snapshot” plugins are by default activated on all publications. To activate a plugin, you can either use the manager or do it by direct file editing.
Via the manager:
Go to the settings > plugins page and click “activate a plugin” if you want to add one or select a plugin in the list and click “Deactivate a plugin”.
Via file editing:
In silex server, go to the “conf” folder and open the plugins_server.php file. Add or remove plugins in the string list, separating them with a “@” character.
b/ activating a plugin at publication level
A plugin activated at publication level is only activated for this publication. Like server level plugin activation, you can do it either via the manager or via direct file editing.
Via the manager:
Go to manager, select the target publication in the list, then click on “plugins”. The activated plugins are listed. You can then deactivate one by selected it and clicking on the “deactivate a plugin” button or activate one by clicking the activate a plugin button and selecting it in the appearing list.
Via file editing:
In your silex server, go to contents, select the folder of the target publication then open the conf.txt file in this folder. Look for the “PLUGINS_LIST” parameter and fill it with the names of the plugins to activate separated by “@” symbols.
c/ Editing the Plugin’s parameters
When a plugin is activated, you can set the paramters described in it’s index.php file (see III – d/) by using the manager. By selecting the activated plugin in the manager (at server or publication level), you will see a list appearing displaying all plugin’s parameters. ex: by selecting “wysiwyg” plugin, “Wysiwyg style url” parameter appear, allowing you to edit the style swf file url. Then click on the parameter to edit its value.
lexa
dans la section “a/Introduction” je verrais bien un screen shot de ton répertoire silex_server avec les plugins
dans “b/requirements”, tu pourrais mettre insister sur le fait que le js, as2 et as3 sont optionnels. Et juste “a basic knowledge of php5 (with classes)” a la place de “good knowledge” ? je ne suis pas sur de moi la dessus
The index.php file must be a class with the same name as the plugins folder and extending the “plugin_base” class located in the “cgi/includes” folder of the server.
> index.php file must contain a class
> il faut parler du fait qu’un plugin doit etre activé pour le serveur ou pour le site afin d etre inclus
require_once ROOTPATH.’cgi/includes/plugin_base.php’;*
> il y a une “*” en trop
dans “JAVASCRIPT HOOKS”, tu pourrais mettre un screen shot du code d’un plugin, ou bien coller le code cash
“It is of course possible to make a plugin available in both mode, just be careful not to call API method not available in end-user mode.”
> je ne comprends pas cette phrase
yannick
c’est réglé
lexa
Here is an example of a plugin which loads a file when silex start. It is useful to load a library, i.e. a .swf file containing classes which you want to use in several components. Or to put something in the cache of the browser, like a preload for a jpg file…
< ?phprequire_once ROOTPATH.'cgi/includes/PluginComponentLibraryBase.php';
class MyPlugin extends plugin_base
{
/**
* override the initHooks method and add a callback
*/
public function initHooks(HookManager $hookManager)
{
parent::initHooks($hookManager);
$hookManager->addHook('pre-index-head', array($this, 'preload_oof_lib_index_head_hook'));
}
/**
* Adds MYFILE to the site's preload file list.
*/
public function preload_oof_lib_index_head_hook($templateContext)
{
if ($templateContext->websitePreloadFileList != '') $templateContext->websitePreloadFileList .= ',';
$templateContext->websitePreloadFileList .= "MYFILE";
}
}
?>