From 992af0b9d77cb4fbac2c37ef8d5896042d67a2a3 Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Wed, 22 Jul 2015 05:02:10 +0200 Subject: Doc: sync from Wiki, generate HTML Closes #291 Fixes #227 Modifications - HTML content: match the new Wiki structure - Makefile - generate a custom HTML sidebar - include the sidebar on all pages - infer and prepend page titles - handle relative links - add title metadata, e.g. Shaarli - Signed-off-by: VirtualTam --- doc/Plugin-System.md | 590 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 590 insertions(+) create mode 100644 doc/Plugin-System.md (limited to 'doc/Plugin-System.md') diff --git a/doc/Plugin-System.md b/doc/Plugin-System.md new file mode 100644 index 00000000..8cba6664 --- /dev/null +++ b/doc/Plugin-System.md @@ -0,0 +1,590 @@ +#Plugin System +> Note: Plugin current status - in developpement (not merged into master). + +[**I am a user.** Plugin User Guide.](#plugin-user-guide)[](.html) + +[**I am a developper.** Developper API.](#developper-api)[](.html) + +[**I am a template designer.** Guide for template designer.](#guide-for-template-designer)[](.html) + +## Plugin User Guide + +### Manage plugins + +In `config.php`, change $GLOBALS['config'['ENABLED_PLUGINS'] array:]('ENABLED_PLUGINS']-array:.html) + +```php +$GLOBALS['config'['ENABLED_PLUGINS']]('ENABLED_PLUGINS'].html) +``` + +Full list: + +```php +$GLOBALS['config'['ENABLED_PLUGINS'] = array(]('ENABLED_PLUGINS']-=-array(.html) + 'qrcode', 'archiveorg', 'readityourself', 'playvideos', + 'wallabag', 'markdown', 'addlink_toolbar', +); +``` + +### List of plugins + +Plugin maintained by the community: + + * Archive.org - add a clickable icon to every link to archive.org. + * Addlink in toolbar - add a field to paste new links URL in toolbar. + * Markdown - write and display Shaare in Markdown. + * Play videos - popup to play all videos displayed in linklist. + * QRCode - add a clickable icon generating a QRCode for every link. + * ReadItYourself - add a clickable icon for ReadItYourself. + * Wallabag - add a clickable icon for Wallabag. + +## Developper API + +### What can I do with plugins? + +The plugin system let you: + + * insert content into specific places across templates. + * alter data before templates rendering. + * alter data before saving new links. + +### How can I create a plugin for Shaarli? + +First, chose a plugin name, such as `demo_plugin`. + +Under `plugin` folder, create a folder named with your plugin name. Then create a .php file in that folder. + +You should have the following tree view: + +``` +| index.php +| plugins/ +|---| demo_plugin/ +| |---| demo_plugin.php +``` + +### Understanding hooks + +A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution. + +These functions need to be named with this pattern: + +``` +hook__ +``` + +For exemple, if my plugin want to add data to the header, this function is needed: + + hook_demo_plugin_render_header() + +If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header. + +### Plugin's data + +#### Parameters + +Every hook function has a `$data` parameter. Its content differs for each hooks. + +**This parameter needs to be returned every time**, otherwise data is lost. + + return $data; + +#### Filling templates placeholder + +Template placeholders are displayed in template in specific places. + +RainTPL displays every element contained in the placeholder's array. These element can be added by plugins. + +For example, let's add a value in the placeholder `top_placeholder` which is displayed at the top of my page: + +```php +$data['top_placeholder'[] = 'My content';](]-=-'My-content';.html) +# OR +array_push($data['top_placeholder'], 'My', 'content');[](.html) + +return $data; +``` + +#### Data manipulation + +When a page is displayed, every variable send to the template engine is passed to plugins before that in `$data`. + +The data contained by this array can be altered before template rendering. + +For exemple, in linklist, it is possible to alter every title: + +```php +// mind the reference if you want $data to be altered +foreach ($data['links'] as &$value) {[](.html) + // String reverse every title. + $value['title'] = strrev($value['title']);[](.html) +} + +return $data; +``` + +### It's not working! + +Use `demo_plugin` as a functional example. It covers most of the plugin system features. + +If it's still not working, please [open an issue](https://github.com/shaarli/Shaarli/issues/new).[](.html) + +### Hooks + +| Hooks | Description | +| ------------- |:-------------:| +| [render_header](#render_header) | Allow plugin to add content in page headers. |[](.html) +| [render_includes](#render_includes) | Allow plugin to include their own CSS files. |[](.html) +| [render_footer](#render_footer) | Allow plugin to add content in page footer and include their own JS files. | [](.html) +| [render_linklist](#render_linklist) | It allows to add content at the begining and end of the page, after every link displayed and to alter link data. |[](.html) +| [render_editlink](#render_editlink) | Allow to add fields in the form, or display elements. |[](.html) +| [render_tools](#render_tools) | Allow to add content at the end of the page. |[](.html) +| [render_picwall](#render_picwall) | Allow to add content at the top and bottom of the page. |[](.html) +| [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page. |[](.html) +| [render_daily](#render_daily) | Allow to add content at the top and bottom of the page, the bottom of each link and to alter data. |[](.html) +| [savelink](#savelink) | Allow to alter the link being saved in the datastore. |[](.html) + + +#### render_header + +Triggered on every page. + +Allow plugin to add content in page headers. + +##### Data + +`$data` is an array containing: + + * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). + * `_LOGGEDIN_`: true if user is logged in, false otherwise. + +##### Template placeholders + +Items can be displayed in templates by adding an entry in `$data['']` array.[](.html) + +List of placeholders: + + * `buttons_toolbar`: after the list of buttons in the header. + +![buttons_toolbar_example](http://i.imgur.com/ssJUOrt.png)[](.html) + + * `fields_toolbar`: after search fields in the header. + +> Note: This will only be called in linklist. + +![fields_toolbar_example](http://i.imgur.com/3GMifI2.png)[](.html) + +#### render_includes + +Triggered on every page. + +Allow plugin to include their own CSS files. + +##### Data + +`$data` is an array containing: + + * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). + * `_LOGGEDIN_`: true if user is logged in, false otherwise. + +##### Template placeholders + +Items can be displayed in templates by adding an entry in `$data['']` array.[](.html) + +List of placeholders: + + * `css_files`: called after loading default CSS. + +> Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`. + +#### render_footer + +Triggered on every page. + +Allow plugin to add content in page footer and include their own JS files. + +##### Data + +`$data` is an array containing: + + * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). + * `_LOGGEDIN_`: true if user is logged in, false otherwise. + +##### Template placeholders + +Items can be displayed in templates by adding an entry in `$data['']` array.[](.html) + +List of placeholders: + + * `text`: called after the end of the footer text. + +![text_example](http://i.imgur.com/L5S2YEH.png)[](.html) + + * `js_files`: called at the end of the page, to include custom JS scripts. + +> Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`. + +#### render_linklist + +Triggered when `linklist` is displayed (list of links, permalink, search, tag filtered, etc.). + +It allows to add content at the begining and end of the page, after every link displayed and to alter link data. + +##### Data + +`$data` is an array containing: + + * `_LOGGEDIN_`: true if user is logged in, false otherwise. + * All templates data, including links. + +##### Template placeholders + +Items can be displayed in templates by adding an entry in `$data['']` array.[](.html) + +List of placeholders: + + * `action_plugin`: next to the button "private only" at the top and bottom of the page. + +![action_plugin_example](http://i.imgur.com/Q12PWg0.png)[](.html) + + * `link_plugin`: for every link, between permalink and link URL. + +![link_plugin_example](http://i.imgur.com/3oDPhWx.png)[](.html) + + * `plugin_start_zone`: before displaying the template content. + +![plugin_start_zone_example](http://i.imgur.com/OVBkGy3.png)[](.html) + + * `plugin_end_zone`: after displaying the template content. + +![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png)[](.html) + +#### render_editlink + +Triggered when the link edition form is displayed. + +Allow to add fields in the form, or display elements. + +##### Data + +`$data` is an array containing: + + * All templates data. + +##### Template placeholders + +Items can be displayed in templates by adding an entry in `$data['']` array.[](.html) + +List of placeholders: + + * `edit_link_plugin`: after tags field. + +![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png)[](.html) + +#### render_tools + +Triggered when the "tools" page is displayed. + +Allow to add content at the end of the page. + +##### Data + +`$data` is an array containing: + + * All templates data. + +##### Template placeholders + +Items can be displayed in templates by adding an entry in `$data['']` array.[](.html) + +List of placeholders: + + * `tools_plugin`: at the end of the page. + +![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png)[](.html) + +#### render_picwall + +Triggered when picwall is displayed. + +Allow to add content at the top and bottom of the page. + +##### Data + +`$data` is an array containing: + + * `_LOGGEDIN_`: true if user is logged in, false otherwise. + * All templates data. + +##### Template placeholders + +Items can be displayed in templates by adding an entry in `$data['']` array.[](.html) + +List of placeholders: + + * `plugin_start_zone`: before displaying the template content. + + * `plugin_end_zone`: after displaying the template content. + +![plugin_start_end_zone_example](http://i.imgur.com/tVTQFER.png)[](.html) + +#### render_tagcloud + +Triggered when tagcloud is displayed. + +Allow to add content at the top and bottom of the page. + +##### Data + +`$data` is an array containing: + + * `_LOGGEDIN_`: true if user is logged in, false otherwise. + * All templates data. + +##### Template placeholders + +Items can be displayed in templates by adding an entry in `$data['']` array.[](.html) + +List of placeholders: + + * `plugin_start_zone`: before displaying the template content. + + * `plugin_end_zone`: after displaying the template content. + +![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png)[](.html) + +#### render_daily + +Triggered when tagcloud is displayed. + +Allow to add content at the top and bottom of the page, the bottom of each link and to alter data. + +##### Data + +`$data` is an array containing: + + * `_LOGGEDIN_`: true if user is logged in, false otherwise. + * All templates data, including links. + +##### Template placeholders + +Items can be displayed in templates by adding an entry in `$data['']` array.[](.html) + +List of placeholders: + + * `link_plugin`: used at bottom of each link. + +![link_plugin_example](http://i.imgur.com/hzhMfSZ.png)[](.html) + + * `plugin_start_zone`: before displaying the template content. + + * `plugin_end_zone`: after displaying the template content. + +#### savelink + +Triggered when a link is save (new link or edit). + +Allow to alter the link being saved in the datastore. + +##### Data + +`$data` is an array containing the link being saved: + + * title + * url + * description + * linkdate + * private + * tags + +## Guide for template designer + +### Placeholder system + +In order to make plugins work with every custom themes, you need to add variable placeholder in your templates. + +It's a RainTPL loop like this: + + {loop="$plugin_variable"} + {$value} + {/loop} + +You should enable `demo_plugin` for testing purpose, since it uses every placeholder available. + +### List of placeholders + +**page.header.html** + +At the end of the menu: + + {loop="$plugins_header.buttons_toolbar"} + {$value} + {/loop} + +**includes.html** + +At the end of the file: + +```html +{loop="$plugins_includes.css_files"} + +{/loop} +``` + +**page.footer.html** + +At the end of your footer notes: + +```html +{loop="$plugins_footer.text"} + {$value} +{/loop} +``` + +At the end of file: + +```html +{loop="$plugins_footer.js_files"} + +{/loop} +``` + +**linklist.html** + +After search fields: + +```html +{loop="$plugins_header.fields_toolbar"} + {$value} +{/loop} +``` + +Before displaying the link list (after paging): + +```html +{loop="$plugin_start_zone"} + {$value} +{/loop} +``` + +For every links (icons): + +```html +{loop="$value.link_plugin"} + {$value} +{/loop} +``` + +Before end paging: + +```html +{loop="$plugin_end_zone"} + {$value} +{/loop} +``` + +**linklist.paging.html** + +After the "private only" icon: + +```html +{loop="$action_plugin"} + {$value} +{/loop} +``` + +**editlink.html** + +After tags field: + +```html +{loop="$edit_link_plugin"} + {$value} +{/loop} +``` + +**tools.html** + +After the last tool: + +```html +{loop="$tools_plugin"} + {$value} +{/loop} +``` + +**picwall.html** + +Top: + +```html +
+ {loop="$plugin_start_zone"} + {$value} + {/loop} +
+``` + +Bottom: + +```html +
+ {loop="$plugin_end_zone"} + {$value} + {/loop} +
+``` + +**tagcloud.html** + +Top: + +```html +
+ {loop="$plugin_start_zone"} + {$value} + {/loop} +
+``` + +Bottom: + +```html +
+ {loop="$plugin_end_zone"} + {$value} + {/loop} +
+``` + +**daily.html** + +Top: + +```html +
+ {loop="$plugin_start_zone"} + {$value} + {/loop} +
+``` + +After every link: + +```html +
+ {loop="$link.link_plugin"} + {$value} + {/loop} +
+``` + +Bottom: + +```html +
+ {loop="$plugin_end_zone"} + {$value} + {/loop} +
+``` -- cgit v1.2.3