5 ### What can I do with plugins?
7 The plugin system lets you:
9 - insert content into specific places across templates.
10 - alter data before templates rendering.
11 - alter data before saving new links.
14 ### How can I create a plugin for Shaarli?
16 First, chose a plugin name, such as `demo_plugin`.
18 Under `plugin` folder, create a folder named with your plugin name. Then create a <plugin_name>.meta file and a <plugin_name>.php file in that folder.
20 You should have the following tree view:
26 | |---| demo_plugin.meta
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 in the <plugin_name>.php 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 The plugin system also looks for a `description` variable in the <plugin_name>.meta file, to be displayed in the plugin administration page.
40 description="The plugin does this and that."
42 ### Understanding hooks
44 A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.
46 These functions need to be named with this pattern:
49 hook_<plugin_name>_<hook_name>($data, $conf)
54 - data: see [$data section](https://shaarli.readthedocs.io/en/master/Plugin-System/#plugins-data)
55 - conf: the `ConfigManager` instance.
57 For example, if my plugin want to add data to the header, this function is needed:
59 hook_demo_plugin_render_header
61 If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.
68 Every hook function has a `$data` parameter. Its content differs for each hooks.
70 **This parameter needs to be returned every time**, otherwise data is lost.
76 Special additional data are passed to every hook through the
77 `$data` parameter to give you access to additional context, and services.
81 * `_PAGE_` (string): if the current hook is used to render a template, its name is passed through this additional parameter.
82 * `_LOGGEDIN_` (bool): whether the user is logged in or not.
83 * `_BASE_PATH_` (string): if Shaarli instance is hosted under a subfolder, contains the subfolder path to `index.php` (e.g. `https://domain.tld/shaarli/` -> `/shaarli/`).
84 * `_BOOKMARK_SERVICE_` (`BookmarkServiceInterface`): bookmark service instance, for advanced usage.
89 if ($data['_PAGE_'] === TemplatePage::LINKLIST && $data['LOGGEDIN'] === true) {
90 // Do something for logged in users when the link list is rendered
94 #### Filling templates placeholder
96 Template placeholders are displayed in template in specific places.
98 RainTPL displays every element contained in the placeholder's array. These element can be added by plugins.
100 For example, let's add a value in the placeholder `top_placeholder` which is displayed at the top of my page:
103 $data['top_placeholder'][] = 'My content';
105 array_push($data['top_placeholder'], 'My', 'content');
111 #### Data manipulation
113 When a page is displayed, every variable send to the template engine is passed to plugins before that in `$data`.
115 The data contained by this array can be altered before template rendering.
117 For example, in linklist, it is possible to alter every title:
120 // mind the reference if you want $data to be altered
121 foreach ($data['links'] as &$value) {
122 // String reverse every title.
123 $value['title'] = strrev($value['title']);
131 Every plugin needs a `<plugin_name>.meta` file, which is in fact an `.ini` file (`KEY="VALUE"`), to be listed in plugin administration.
133 Each file contain two keys:
135 - `description`: plugin description
136 - `parameters`: user parameter names, separated by a `;`.
137 - `parameter.<PARAMETER_NAME>`: add a text description the specified parameter.
139 > Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file.
141 ### Register plugin's routes
143 Shaarli lets you register custom Slim routes for your plugin.
145 To register a route, the plugin must include a function called `function <plugin_name>_register_routes(): array`.
147 This method must return an array of routes, each entry must contain the following keys:
149 - `method`: HTTP method, `GET/POST/PUT/PATCH/DELETE`
150 - `route` (path): without prefix, e.g. `/up/{variable}`
151 It will be later prefixed by `/plugin/<plugin name>/`.
152 - `callable` string, function name or FQN class's method to execute, e.g. `demo_plugin_custom_controller`.
154 Callable functions or methods must have `Slim\Http\Request` and `Slim\Http\Response` parameters
155 and return a `Slim\Http\Response`. We recommend creating a dedicated class and extend either
156 `ShaarliVisitorController` or `ShaarliAdminController` to use helper functions they provide.
158 A dedicated plugin template is available for rendering content: `pluginscontent.html` using `content` placeholder.
160 > **Warning**: plugins are not able to use RainTPL template engine for their content due to technical restrictions.
161 > RainTPL does not allow to register multiple template folders, so all HTML rendering must be done within plugin
164 Check out the `demo_plugin` for a live example: `GET <shaarli_url>/plugin/demo_plugin/custom`.
166 ### Understanding relative paths
168 Because Shaarli is a self-hosted tool, an instance can either be installed at the root directory, or under a subfolder.
169 This means that you can *never* use absolute paths (eg `/plugins/mything/file.png`).
171 If a file needs to be included in server end, use simple relative path:
172 `PluginManager::$PLUGINS_PATH . '/mything/template.html'`.
174 If it needs to be included in front end side (e.g. an image),
175 the relative path must be prefixed with special data:
177 * if it's a link that will need to be processed by Shaarli, use `_BASE_PATH_`:
178 for e.g. `$data['_BASE_PATH_'] . '/admin/tools`.
179 * if you want to include an asset, you need to add the root URL (base path without `/index.php`, for people using Shaarli without URL rewriting), then use `_ROOT_PATH_`:
181 `$['_ROOT_PATH_'] . '/' . PluginManager::$PLUGINS_PATH . '/mything/picture.png`.
183 Note that special placeholders for CSS and JS files (respectively `css_files` and `js_files`) are already prefixed
184 with the root path in template files.
186 ### It's not working!
188 Use `demo_plugin` as a functional example. It covers most of the plugin system features.
190 If it's still not working, please [open an issue](https://github.com/shaarli/Shaarli/issues/new).
195 | Hooks | Description |
196 | ------------- |:-------------:|
197 | [render_header](#render_header) | Allow plugin to add content in page headers. |
198 | [render_includes](#render_includes) | Allow plugin to include their own CSS files. |
199 | [render_footer](#render_footer) | Allow plugin to add content in page footer and include their own JS files. |
200 | [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. |
201 | [render_editlink](#render_editlink) | Allow to add fields in the form, or display elements. |
202 | [render_tools](#render_tools) | Allow to add content at the end of the page. |
203 | [render_picwall](#render_picwall) | Allow to add content at the top and bottom of the page. |
204 | [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page, and after all tags. |
205 | [render_taglist](#render_taglist) | Allow to add content at the top and bottom of the page, and after all tags. |
206 | [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. |
207 | [render_feed](#render_feed) | Allow to do add tags in RSS and ATOM feeds. |
208 | [save_link](#save_link) | Allow to alter the link being saved in the datastore. |
209 | [delete_link](#delete_link) | Allow to do an action before a link is deleted from the datastore. |
210 | [save_plugin_parameters](#save_plugin_parameters) | Allow to manipulate plugin parameters before they're saved. |
211 | [filter_search_entry](#filter_search_entry) | Add custom filters to Shaarli search engine |
216 Triggered on every page - allows plugins to add content in page headers.
221 `$data` is an array containing:
223 - [Special data](#special-data)
225 ##### Template placeholders
227 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
229 List of placeholders:
231 - `buttons_toolbar`: after the list of buttons in the header.
233 ![buttons_toolbar_example](http://i.imgur.com/ssJUOrt.png)
235 - `fields_toolbar`: after search fields in the header.
237 > Note: This will only be called in linklist.
239 ![fields_toolbar_example](http://i.imgur.com/3GMifI2.png)
244 Triggered on every page - allows plugins to include their own CSS files.
248 `$data` is an array containing:
250 - [Special data](#special-data)
252 ##### Template placeholders
254 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
256 List of placeholders:
258 - `css_files`: called after loading default CSS.
260 > Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`.
265 Triggered on every page.
267 Allow plugin to add content in page footer and include their own JS files.
271 `$data` is an array containing:
273 - [Special data](#special-data)
275 ##### Template placeholders
277 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
279 List of placeholders:
281 - `text`: called after the end of the footer text.
282 - `endofpage`: called at the end of the page.
284 ![text_example](http://i.imgur.com/L5S2YEH.png)
286 - `js_files`: called at the end of the page, to include custom JS scripts.
288 > Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`.
293 Triggered when `linklist` is displayed (list of links, permalink, search, tag filtered, etc.).
295 It allows to add content at the begining and end of the page, after every link displayed and to alter link data.
299 `$data` is an array containing:
301 - All templates data, including links.
302 - [Special data](#special-data)
304 ##### template placeholders
306 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
308 List of placeholders:
310 - `action_plugin`: next to the button "private only" at the top and bottom of the page.
312 ![action_plugin_example](http://i.imgur.com/Q12PWg0.png)
314 - `link_plugin`: for every link, between permalink and link URL.
316 ![link_plugin_example](http://i.imgur.com/3oDPhWx.png)
318 - `plugin_start_zone`: before displaying the template content.
320 ![plugin_start_zone_example](http://i.imgur.com/OVBkGy3.png)
322 - `plugin_end_zone`: after displaying the template content.
324 ![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png)
329 Triggered when the link edition form is displayed.
331 Allow to add fields in the form, or display elements.
335 `$data` is an array containing:
337 - All templates data.
338 - [Special data](#special-data)
340 ##### template placeholders
342 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
344 List of placeholders:
346 - `edit_link_plugin`: after tags field.
348 ![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png)
353 Triggered when the "tools" page is displayed.
355 Allow to add content at the end of the page.
359 `$data` is an array containing:
361 - All templates data.
362 - [Special data](#special-data)
364 ##### template placeholders
366 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
368 List of placeholders:
370 - `tools_plugin`: at the end of the page.
372 ![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png)
377 Triggered when picwall is displayed.
379 Allow to add content at the top and bottom of the page.
383 `$data` is an array containing:
385 - All templates data.
386 - [Special data](#special-data)
388 ##### template placeholders
390 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
392 List of placeholders:
394 - `plugin_start_zone`: before displaying the template content.
395 - `plugin_end_zone`: after displaying the template content.
397 ![plugin_start_end_zone_example](http://i.imgur.com/tVTQFER.png)
402 Triggered when tagcloud is displayed.
404 Allow to add content at the top and bottom of the page.
408 `$data` is an array containing:
410 - All templates data.
411 - [Special data](#special-data)
413 ##### Template placeholders
415 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
417 List of placeholders:
419 - `plugin_start_zone`: before displaying the template content.
420 - `plugin_end_zone`: after displaying the template content.
422 For each tag, the following placeholder can be used:
424 - `tag_plugin`: after each tag
426 ![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png)
431 Triggered when taglist is displayed - allows to add content at the top and bottom of the page.
435 `$data` is an array containing:
437 - All templates data.
438 - [Special data](#special-data)
440 ##### Template placeholders
442 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
444 List of placeholders:
446 - `plugin_start_zone`: before displaying the template content.
447 - `plugin_end_zone`: after displaying the template content.
449 For each tag, the following placeholder can be used:
451 - `tag_plugin`: after each tag
455 Triggered when tagcloud is displayed.
457 Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.
462 `$data` is an array containing:
464 - All templates data, including links.
465 - [Special data](#special-data)
467 ##### Template placeholders
469 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
471 List of placeholders:
473 - `link_plugin`: used at bottom of each link.
475 ![link_plugin_example](http://i.imgur.com/hzhMfSZ.png)
477 - `plugin_start_zone`: before displaying the template content.
478 - `plugin_end_zone`: after displaying the template content.
483 Triggered when the ATOM or RSS feed is displayed.
485 Allow to add tags in the feed, either in the header or for each items. Items (links) can also be altered before being rendered.
489 `$data` is an array containing:
491 - All templates data, including links.
492 - [Special data](#special-data)
494 ##### Template placeholders
496 Tags can be added in feeds by adding an entry in `$data['<placeholder>']` array.
498 List of placeholders:
500 - `feed_plugins_header`: used as a header tag in the feed.
504 - `feed_plugins`: additional tag for every link entry.
509 Triggered when a link is save (new link or edit).
511 Allow to alter the link being saved in the datastore.
515 `$data` is an array containing the link being saved:
527 Also [special data](#special-data).
532 Triggered when a link is deleted.
534 Allow to execute any action before the link is actually removed from the datastore
538 `$data` is an array containing the link being deleted:
550 Also [special data](#special-data).
552 #### save_plugin_parameters
554 Triggered when the plugin parameters are saved from the plugin administration page.
556 Plugins can perform an action every times their settings are updated.
557 For example it is used to update the CSS file of the `default_colors` plugins.
561 `$data` input contains the `$_POST` array.
563 So if the plugin has a parameter called `MYPLUGIN_PARAMETER`,
564 the array will contain an entry with `MYPLUGIN_PARAMETER` as a key.
566 Also [special data](#special-data).
568 #### filter_search_entry
570 Triggered for *every* bookmark when Shaarli's BookmarkService method `search()` is used.
571 Any custom filter can be added to filter out bookmarks from search results.
573 The hook **must** return either:
574 - `true` to keep bookmark entry in search result set
575 - `false` to discard bookmark entry in result set
577 > Note: custom filters are called *before* default filters are applied.
581 - `Shaarli\Bookmark\Bookmark` object: entry to evaluate
582 - $context `array`: additional information provided depending on what search is currently used,
583 the user request, etc.
585 ## Guide for template designers
587 ### Plugin administration
589 Your theme must include a plugin administration page: `pluginsadmin.html`.
591 > Note: repo's template link needs to be added when the PR is merged.
593 Use the default one as an example.
595 Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if:
597 - you're using a table.
598 - you call orderUp() and orderUp() onclick on arrows.
599 - you add data-line and data-order to your rows.
601 Otherwise, you can use your own JS as long as this field is send by the form:
603 <input type="hidden" name="order_{$key}" value="{$counter}">
605 ### Placeholder system
607 In order to make plugins work with every custom themes, you need to add variable placeholder in your templates.
609 It's a RainTPL loop like this:
611 {loop="$plugin_variable"}
615 You should enable `demo_plugin` for testing purpose, since it uses every placeholder available.
617 ### List of placeholders
621 At the end of the menu:
623 {loop="$plugins_header.buttons_toolbar"}
627 At the end of file, before clearing floating blocks:
629 {if="!empty($plugin_errors) && $is_logged_in"}
631 {loop="plugin_errors"}
639 At the end of the file:
642 {loop="$plugins_includes.css_files"}
643 <link type="text/css" rel="stylesheet" href="{$value}#"/>
649 At the end of your footer notes:
652 {loop="$plugins_footer.text"}
660 {loop="$plugins_footer.js_files"}
661 <script src="{$value}#"></script>
670 {loop="$plugins_header.fields_toolbar"}
675 Before displaying the link list (after paging):
678 {loop="$plugin_start_zone"}
683 For every links (icons):
686 {loop="$value.link_plugin"}
687 <span>{$value}</span>
694 {loop="$plugin_end_zone"}
699 **linklist.paging.html**
701 After the "private only" icon:
704 {loop="$action_plugin"}
714 {loop="$edit_link_plugin"}
724 {loop="$tools_plugin"}
734 <div id="plugin_zone_start_picwall" class="plugin_zone">
735 {loop="$plugin_start_zone"}
744 <div id="plugin_zone_end_picwall" class="plugin_zone">
745 {loop="$plugin_end_zone"}
756 <div id="plugin_zone_start_tagcloud" class="plugin_zone">
757 {loop="$plugin_start_zone"}
766 <div id="plugin_zone_end_tagcloud" class="plugin_zone">
767 {loop="$plugin_end_zone"}
778 <div id="plugin_zone_start_picwall" class="plugin_zone">
779 {loop="$plugin_start_zone"}
788 <div class="dailyEntryFooter">
789 {loop="$link.link_plugin"}
798 <div id="plugin_zone_end_picwall" class="plugin_zone">
799 {loop="$plugin_end_zone"}
805 **feed.atom.xml** and **feed.rss.xml**:
807 In headers tags section:
809 {loop="$feed_plugins_header"}
816 {loop="$value.feed_plugins"}