1 [**I am a developer.** Developer API.](#developer-api)
3 [**I am a template designer.** Guide for template designer.](#guide-for-template-designer)
7 ### What can I do with plugins?
9 The plugin system let you:
11 * insert content into specific places across templates.
12 * alter data before templates rendering.
13 * alter data before saving new links.
15 ### How can I create a plugin for Shaarli?
17 First, chose a plugin name, such as `demo_plugin`.
19 Under `plugin` folder, create a folder named with your plugin name. Then create a <plugin_name>.php file in that folder.
21 You should have the following tree view:
27 | |---| demo_plugin.php
30 ### Plugin initialization
32 At the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an `init()` function to execute and run it if it exists. This function must be named this way, and takes the `ConfigManager` as parameter.
34 <plugin_name>_init($conf)
36 This function can be used to create initial data, load default settings, etc. But also to set *plugin errors*. If the initialization function returns an array of strings, they will be understand as errors, and displayed in the header to logged in users.
38 ### Understanding hooks
40 A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.
42 These functions need to be named with this pattern:
45 hook_<plugin_name>_<hook_name>($data, $conf)
50 - data: see [$data section](https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data)
51 - conf: the `ConfigManager` instance.
53 For exemple, if my plugin want to add data to the header, this function is needed:
55 hook_demo_plugin_render_header
57 If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.
63 Every hook function has a `$data` parameter. Its content differs for each hooks.
65 **This parameter needs to be returned every time**, otherwise data is lost.
69 #### Filling templates placeholder
71 Template placeholders are displayed in template in specific places.
73 RainTPL displays every element contained in the placeholder's array. These element can be added by plugins.
75 For example, let's add a value in the placeholder `top_placeholder` which is displayed at the top of my page:
78 $data['top_placeholder'][] = 'My content';
80 array_push($data['top_placeholder'], 'My', 'content');
85 #### Data manipulation
87 When a page is displayed, every variable send to the template engine is passed to plugins before that in `$data`.
89 The data contained by this array can be altered before template rendering.
91 For exemple, in linklist, it is possible to alter every title:
94 // mind the reference if you want $data to be altered
95 foreach ($data['links'] as &$value) {
96 // String reverse every title.
97 $value['title'] = strrev($value['title']);
105 Every plugin needs a `<plugin_name>.meta` file, which is in fact an `.ini` file (`KEY="VALUE"`), to be listed in plugin administration.
107 Each file contain two keys:
109 * `description`: plugin description
110 * `parameters`: user parameter names, separated by a `;`.
111 * `parameter.<PARAMETER_NAME>`: add a text description the specified parameter.
113 > Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file.
115 ### It's not working!
117 Use `demo_plugin` as a functional example. It covers most of the plugin system features.
119 If it's still not working, please [open an issue](https://github.com/shaarli/Shaarli/issues/new).
123 | Hooks | Description |
124 | ------------- |:-------------:|
125 | [render_header](#render_header) | Allow plugin to add content in page headers. |
126 | [render_includes](#render_includes) | Allow plugin to include their own CSS files. |
127 | [render_footer](#render_footer) | Allow plugin to add content in page footer and include their own JS files. |
128 | [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. |
129 | [render_editlink](#render_editlink) | Allow to add fields in the form, or display elements. |
130 | [render_tools](#render_tools) | Allow to add content at the end of the page. |
131 | [render_picwall](#render_picwall) | Allow to add content at the top and bottom of the page. |
132 | [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page, and after all tags. |
133 | [render_taglist](#render_taglist) | Allow to add content at the top and bottom of the page, and after all tags. |
134 | [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. |
135 | [render_feed](#render_feed) | Allow to do add tags in RSS and ATOM feeds. |
136 | [save_link](#save_link) | Allow to alter the link being saved in the datastore. |
137 | [delete_link](#delete_link) | Allow to do an action before a link is deleted from the datastore. |
143 Triggered on every page.
145 Allow plugin to add content in page headers.
149 `$data` is an array containing:
151 * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
152 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
154 ##### Template placeholders
156 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
158 List of placeholders:
160 * `buttons_toolbar`: after the list of buttons in the header.
162 ![buttons_toolbar_example](http://i.imgur.com/ssJUOrt.png)
164 * `fields_toolbar`: after search fields in the header.
166 > Note: This will only be called in linklist.
168 ![fields_toolbar_example](http://i.imgur.com/3GMifI2.png)
172 Triggered on every page.
174 Allow plugin to include their own CSS files.
178 `$data` is an array containing:
180 * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
181 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
183 ##### Template placeholders
185 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
187 List of placeholders:
189 * `css_files`: called after loading default CSS.
191 > Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`.
195 Triggered on every page.
197 Allow plugin to add content in page footer and include their own JS files.
201 `$data` is an array containing:
203 * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
204 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
206 ##### Template placeholders
208 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
210 List of placeholders:
212 * `text`: called after the end of the footer text.
213 * `endofpage`: called at the end of the page.
215 ![text_example](http://i.imgur.com/L5S2YEH.png)
217 * `js_files`: called at the end of the page, to include custom JS scripts.
219 > Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`.
223 Triggered when `linklist` is displayed (list of links, permalink, search, tag filtered, etc.).
225 It allows to add content at the begining and end of the page, after every link displayed and to alter link data.
229 `$data` is an array containing:
231 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
232 * All templates data, including links.
234 ##### Template placeholders
236 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
238 List of placeholders:
240 * `action_plugin`: next to the button "private only" at the top and bottom of the page.
242 ![action_plugin_example](http://i.imgur.com/Q12PWg0.png)
244 * `link_plugin`: for every link, between permalink and link URL.
246 ![link_plugin_example](http://i.imgur.com/3oDPhWx.png)
248 * `plugin_start_zone`: before displaying the template content.
250 ![plugin_start_zone_example](http://i.imgur.com/OVBkGy3.png)
252 * `plugin_end_zone`: after displaying the template content.
254 ![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png)
258 Triggered when the link edition form is displayed.
260 Allow to add fields in the form, or display elements.
264 `$data` is an array containing:
266 * All templates data.
268 ##### Template placeholders
270 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
272 List of placeholders:
274 * `edit_link_plugin`: after tags field.
276 ![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png)
280 Triggered when the "tools" page is displayed.
282 Allow to add content at the end of the page.
286 `$data` is an array containing:
288 * All templates data.
290 ##### Template placeholders
292 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
294 List of placeholders:
296 * `tools_plugin`: at the end of the page.
298 ![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png)
302 Triggered when picwall is displayed.
304 Allow to add content at the top and bottom of the page.
308 `$data` is an array containing:
310 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
311 * All templates data.
313 ##### Template placeholders
315 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
317 List of placeholders:
319 * `plugin_start_zone`: before displaying the template content.
321 * `plugin_end_zone`: after displaying the template content.
323 ![plugin_start_end_zone_example](http://i.imgur.com/tVTQFER.png)
327 Triggered when tagcloud is displayed.
329 Allow to add content at the top and bottom of the page.
333 `$data` is an array containing:
335 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
336 * All templates data.
338 ##### Template placeholders
340 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
342 List of placeholders:
344 * `plugin_start_zone`: before displaying the template content.
346 * `plugin_end_zone`: after displaying the template content.
348 For each tag, the following placeholder can be used:
350 * `tag_plugin`: after each tag
352 ![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png)
357 Triggered when taglist is displayed.
359 Allow to add content at the top and bottom of the page.
363 `$data` is an array containing:
365 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
366 * All templates data.
368 ##### Template placeholders
370 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
372 List of placeholders:
374 * `plugin_start_zone`: before displaying the template content.
376 * `plugin_end_zone`: after displaying the template content.
378 For each tag, the following placeholder can be used:
380 * `tag_plugin`: after each tag
384 Triggered when tagcloud is displayed.
386 Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.
390 `$data` is an array containing:
392 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
393 * All templates data, including links.
395 ##### Template placeholders
397 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
399 List of placeholders:
401 * `link_plugin`: used at bottom of each link.
403 ![link_plugin_example](http://i.imgur.com/hzhMfSZ.png)
405 * `plugin_start_zone`: before displaying the template content.
407 * `plugin_end_zone`: after displaying the template content.
411 Triggered when the ATOM or RSS feed is displayed.
413 Allow to add tags in the feed, either in the header or for each items. Items (links) can also be altered before being rendered.
417 `$data` is an array containing:
419 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
420 * `_PAGE_`: containing either `rss` or `atom`.
421 * All templates data, including links.
423 ##### Template placeholders
425 Tags can be added in feeds by adding an entry in `$data['<placeholder>']` array.
427 List of placeholders:
429 * `feed_plugins_header`: used as a header tag in the feed.
433 * `feed_plugins`: additional tag for every link entry.
437 Triggered when a link is save (new link or edit).
439 Allow to alter the link being saved in the datastore.
443 `$data` is an array containing the link being saved:
458 Triggered when a link is deleted.
460 Allow to execute any action before the link is actually removed from the datastore
464 `$data` is an array containing the link being saved:
476 ## Guide for template designer
478 ### Plugin administration
480 Your theme must include a plugin administration page: `pluginsadmin.html`.
482 > Note: repo's template link needs to be added when the PR is merged.
484 Use the default one as an example.
486 Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if:
488 * you're using a table.
489 * you call orderUp() and orderUp() onclick on arrows.
490 * you add data-line and data-order to your rows.
492 Otherwise, you can use your own JS as long as this field is send by the form:
494 <input type="hidden" name="order_{$key}" value="{$counter}">
496 ### Placeholder system
498 In order to make plugins work with every custom themes, you need to add variable placeholder in your templates.
500 It's a RainTPL loop like this:
502 {loop="$plugin_variable"}
506 You should enable `demo_plugin` for testing purpose, since it uses every placeholder available.
508 ### List of placeholders
512 At the end of the menu:
514 {loop="$plugins_header.buttons_toolbar"}
518 At the end of file, before clearing floating blocks:
520 {if="!empty($plugin_errors) && isLoggedIn()"}
522 {loop="plugin_errors"}
530 At the end of the file:
533 {loop="$plugins_includes.css_files"}
534 <link type="text/css" rel="stylesheet" href="{$value}#"/>
540 At the end of your footer notes:
543 {loop="$plugins_footer.text"}
551 {loop="$plugins_footer.js_files"}
552 <script src="{$value}#"></script>
561 {loop="$plugins_header.fields_toolbar"}
566 Before displaying the link list (after paging):
569 {loop="$plugin_start_zone"}
574 For every links (icons):
577 {loop="$value.link_plugin"}
578 <span>{$value}</span>
585 {loop="$plugin_end_zone"}
590 **linklist.paging.html**
592 After the "private only" icon:
595 {loop="$action_plugin"}
605 {loop="$edit_link_plugin"}
615 {loop="$tools_plugin"}
625 <div id="plugin_zone_start_picwall" class="plugin_zone">
626 {loop="$plugin_start_zone"}
635 <div id="plugin_zone_end_picwall" class="plugin_zone">
636 {loop="$plugin_end_zone"}
647 <div id="plugin_zone_start_tagcloud" class="plugin_zone">
648 {loop="$plugin_start_zone"}
657 <div id="plugin_zone_end_tagcloud" class="plugin_zone">
658 {loop="$plugin_end_zone"}
669 <div id="plugin_zone_start_picwall" class="plugin_zone">
670 {loop="$plugin_start_zone"}
679 <div class="dailyEntryFooter">
680 {loop="$link.link_plugin"}
689 <div id="plugin_zone_end_picwall" class="plugin_zone">
690 {loop="$plugin_end_zone"}
696 **feed.atom.xml** and **feed.rss.xml**:
698 In headers tags section:
700 {loop="$feed_plugins_header"}
707 {loop="$value.feed_plugins"}