2 > Note: Plugin current status - in development (not merged into master).
4 [**I am a developer.** Developer API.](#developer-api)[](.html)
6 [**I am a template designer.** Guide for template designer.](#guide-for-template-designer)[](.html)
10 ### What can I do with plugins?
12 The plugin system let you:
14 * insert content into specific places across templates.
15 * alter data before templates rendering.
16 * alter data before saving new links.
18 ### How can I create a plugin for Shaarli?
20 First, chose a plugin name, such as `demo_plugin`.
22 Under `plugin` folder, create a folder named with your plugin name. Then create a <plugin_name>.php file in that folder.
24 You should have the following tree view:
30 | |---| demo_plugin.php
33 ### Understanding hooks
35 A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.
37 These functions need to be named with this pattern:
40 hook_<plugin_name>_<hook_name>
43 For exemple, if my plugin want to add data to the header, this function is needed:
45 hook_demo_plugin_render_header()
47 If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.
53 Every hook function has a `$data` parameter. Its content differs for each hooks.
55 **This parameter needs to be returned every time**, otherwise data is lost.
59 #### Filling templates placeholder
61 Template placeholders are displayed in template in specific places.
63 RainTPL displays every element contained in the placeholder's array. These element can be added by plugins.
65 For example, let's add a value in the placeholder `top_placeholder` which is displayed at the top of my page:
68 $data['top_placeholder'[] = 'My content';](]-=-'My-content';.html)
70 array_push($data['top_placeholder'], 'My', 'content');[](.html)
75 #### Data manipulation
77 When a page is displayed, every variable send to the template engine is passed to plugins before that in `$data`.
79 The data contained by this array can be altered before template rendering.
81 For exemple, in linklist, it is possible to alter every title:
84 // mind the reference if you want $data to be altered
85 foreach ($data['links'] as &$value) {[](.html)
86 // String reverse every title.
87 $value['title'] = strrev($value['title']);[](.html)
95 Every plugin needs a `<plugin_name>.meta` file, which is in fact an `.ini` file (`KEY="VALUE"`), to be listed in plugin administration.
97 Each file contain two keys:
99 * `description`: plugin description
100 * `parameters`: user parameter names, separated by a `;`.
102 > Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file.
104 ### It's not working!
106 Use `demo_plugin` as a functional example. It covers most of the plugin system features.
108 If it's still not working, please [open an issue](https://github.com/shaarli/Shaarli/issues/new).[](.html)
112 | Hooks | Description |
113 | ------------- |:-------------:|
114 | [render_header](#render_header) | Allow plugin to add content in page headers. |[](.html)
115 | [render_includes](#render_includes) | Allow plugin to include their own CSS files. |[](.html)
116 | [render_footer](#render_footer) | Allow plugin to add content in page footer and include their own JS files. | [](.html)
117 | [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)
118 | [render_editlink](#render_editlink) | Allow to add fields in the form, or display elements. |[](.html)
119 | [render_tools](#render_tools) | Allow to add content at the end of the page. |[](.html)
120 | [render_picwall](#render_picwall) | Allow to add content at the top and bottom of the page. |[](.html)
121 | [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page. |[](.html)
122 | [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)
123 | [savelink](#savelink) | Allow to alter the link being saved in the datastore. |[](.html)
128 Triggered on every page.
130 Allow plugin to add content in page headers.
134 `$data` is an array containing:
136 * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
137 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
139 ##### Template placeholders
141 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
143 List of placeholders:
145 * `buttons_toolbar`: after the list of buttons in the header.
147 ![buttons_toolbar_example](http://i.imgur.com/ssJUOrt.png)[](.html)
149 * `fields_toolbar`: after search fields in the header.
151 > Note: This will only be called in linklist.
153 ![fields_toolbar_example](http://i.imgur.com/3GMifI2.png)[](.html)
157 Triggered on every page.
159 Allow plugin to include their own CSS files.
163 `$data` is an array containing:
165 * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
166 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
168 ##### Template placeholders
170 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
172 List of placeholders:
174 * `css_files`: called after loading default CSS.
176 > Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`.
180 Triggered on every page.
182 Allow plugin to add content in page footer and include their own JS files.
186 `$data` is an array containing:
188 * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
189 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
191 ##### Template placeholders
193 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
195 List of placeholders:
197 * `text`: called after the end of the footer text.
199 ![text_example](http://i.imgur.com/L5S2YEH.png)[](.html)
201 * `js_files`: called at the end of the page, to include custom JS scripts.
203 > Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`.
207 Triggered when `linklist` is displayed (list of links, permalink, search, tag filtered, etc.).
209 It allows to add content at the begining and end of the page, after every link displayed and to alter link data.
213 `$data` is an array containing:
215 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
216 * All templates data, including links.
218 ##### Template placeholders
220 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
222 List of placeholders:
224 * `action_plugin`: next to the button "private only" at the top and bottom of the page.
226 ![action_plugin_example](http://i.imgur.com/Q12PWg0.png)[](.html)
228 * `link_plugin`: for every link, between permalink and link URL.
230 ![link_plugin_example](http://i.imgur.com/3oDPhWx.png)[](.html)
232 * `plugin_start_zone`: before displaying the template content.
234 ![plugin_start_zone_example](http://i.imgur.com/OVBkGy3.png)[](.html)
236 * `plugin_end_zone`: after displaying the template content.
238 ![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png)[](.html)
242 Triggered when the link edition form is displayed.
244 Allow to add fields in the form, or display elements.
248 `$data` is an array containing:
250 * All templates data.
252 ##### Template placeholders
254 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
256 List of placeholders:
258 * `edit_link_plugin`: after tags field.
260 ![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png)[](.html)
264 Triggered when the "tools" page is displayed.
266 Allow to add content at the end of the page.
270 `$data` is an array containing:
272 * All templates data.
274 ##### Template placeholders
276 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
278 List of placeholders:
280 * `tools_plugin`: at the end of the page.
282 ![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png)[](.html)
286 Triggered when picwall is displayed.
288 Allow to add content at the top and bottom of the page.
292 `$data` is an array containing:
294 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
295 * All templates data.
297 ##### Template placeholders
299 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
301 List of placeholders:
303 * `plugin_start_zone`: before displaying the template content.
305 * `plugin_end_zone`: after displaying the template content.
307 ![plugin_start_end_zone_example](http://i.imgur.com/tVTQFER.png)[](.html)
311 Triggered when tagcloud is displayed.
313 Allow to add content at the top and bottom of the page.
317 `$data` is an array containing:
319 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
320 * All templates data.
322 ##### Template placeholders
324 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
326 List of placeholders:
328 * `plugin_start_zone`: before displaying the template content.
330 * `plugin_end_zone`: after displaying the template content.
332 ![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png)[](.html)
336 Triggered when tagcloud is displayed.
338 Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.
342 `$data` is an array containing:
344 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
345 * All templates data, including links.
347 ##### Template placeholders
349 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
351 List of placeholders:
353 * `link_plugin`: used at bottom of each link.
355 ![link_plugin_example](http://i.imgur.com/hzhMfSZ.png)[](.html)
357 * `plugin_start_zone`: before displaying the template content.
359 * `plugin_end_zone`: after displaying the template content.
363 Triggered when a link is save (new link or edit).
365 Allow to alter the link being saved in the datastore.
369 `$data` is an array containing the link being saved:
378 ## Guide for template designer
380 ### Plugin administration
382 Your theme must include a plugin administration page: `pluginsadmin.html`.
384 > Note: repo's template link needs to be added when the PR is merged.
386 Use the default one as an example.
388 Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if:
390 * you're using a table.
391 * you call orderUp() and orderUp() onclick on arrows.
392 * you add data-line and data-order to your rows.
394 Otherwise, you can use your own JS as long as this field is send by the form:
396 <input type="hidden" name="order_{$key}" value="{$counter}">
398 ### Placeholder system
400 In order to make plugins work with every custom themes, you need to add variable placeholder in your templates.
402 It's a RainTPL loop like this:
404 {loop="$plugin_variable"}
408 You should enable `demo_plugin` for testing purpose, since it uses every placeholder available.
410 ### List of placeholders
414 At the end of the menu:
416 {loop="$plugins_header.buttons_toolbar"}
420 At the end of file, before clearing floating blocks:
422 {if="!empty($plugin_errors) && isLoggedIn()"}
424 {loop="plugin_errors"}
432 At the end of the file:
435 {loop="$plugins_includes.css_files"}
436 <link type="text/css" rel="stylesheet" href="{$value}#"/>
442 At the end of your footer notes:
445 {loop="$plugins_footer.text"}
453 {loop="$plugins_footer.js_files"}
454 <script src="{$value}#"></script>
463 {loop="$plugins_header.fields_toolbar"}
468 Before displaying the link list (after paging):
471 {loop="$plugin_start_zone"}
476 For every links (icons):
479 {loop="$value.link_plugin"}
480 <span>{$value}</span>
487 {loop="$plugin_end_zone"}
492 **linklist.paging.html**
494 After the "private only" icon:
497 {loop="$action_plugin"}
507 {loop="$edit_link_plugin"}
517 {loop="$tools_plugin"}
527 <div id="plugin_zone_start_picwall" class="plugin_zone">
528 {loop="$plugin_start_zone"}
537 <div id="plugin_zone_end_picwall" class="plugin_zone">
538 {loop="$plugin_end_zone"}
549 <div id="plugin_zone_start_tagcloud" class="plugin_zone">
550 {loop="$plugin_start_zone"}
559 <div id="plugin_zone_end_tagcloud" class="plugin_zone">
560 {loop="$plugin_end_zone"}
571 <div id="plugin_zone_start_picwall" class="plugin_zone">
572 {loop="$plugin_start_zone"}
581 <div class="dailyEntryFooter">
582 {loop="$link.link_plugin"}
591 <div id="plugin_zone_end_picwall" class="plugin_zone">
592 {loop="$plugin_end_zone"}