X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=doc%2Fmd%2FPlugin-System.md;h=87a2638dbea73fc3ef9262ccf7bd208af3ea8d81;hb=6128ab6a55430a2b705be31ff417c0c552a0db1f;hp=d55ffe7e65d8b26f181a3f2f08ecc58e01c6ab2a;hpb=57ee53d6c6be4b641764b0a635b2998c6cdc8197;p=github%2Fshaarli%2FShaarli.git diff --git a/doc/md/Plugin-System.md b/doc/md/Plugin-System.md index d55ffe7e..87a2638d 100644 --- a/doc/md/Plugin-System.md +++ b/doc/md/Plugin-System.md @@ -1,6 +1,8 @@ -[**I am a developer.** Developer API.](#developer-api) +[**I am a developer: ** Developer API](#developer-api) -[**I am a template designer.** Guide for template designer.](#guide-for-template-designer) +[**I am a template designer: ** Guide for template designers](#guide-for-template-designer) + +--- ## Developer API @@ -8,15 +10,15 @@ The plugin system let you: - * insert content into specific places across templates. - * alter data before templates rendering. - * alter data before saving new links. +- 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. +Under `plugin` folder, create a folder named with your plugin name. Then create a .meta file and a .php file in that folder. You should have the following tree view: @@ -24,17 +26,22 @@ You should have the following tree view: | index.php | plugins/ |---| demo_plugin/ +| |---| demo_plugin.meta | |---| demo_plugin.php ``` ### Plugin initialization -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. +At the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an `init()` function in the .php to execute and run it if it exists. This function must be named this way, and takes the `ConfigManager` as parameter. _init($conf) 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. +The plugin system also looks for a `description` variable in the .meta file, to be displayed in the plugin administration page. + + description="The plugin does this and that." + ### Understanding hooks A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution. @@ -47,10 +54,10 @@ hook__($data, $conf) Parameters: - - data: see [$data section](https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data) - - conf: the `ConfigManager` instance. +- data: see [$data section](https://shaarli.readthedocs.io/en/master/Plugin-System/#plugins-data) +- conf: the `ConfigManager` instance. -For exemple, if my plugin want to add data to the header, this function is needed: +For example, if my plugin want to add data to the header, this function is needed: hook_demo_plugin_render_header @@ -66,6 +73,26 @@ Every hook function has a `$data` parameter. Its content differs for each hooks. return $data; +#### Special data + +Special additional data are passed to every hook through the +`$data` parameter to give you access to additional context, and services. + +Complete list: + + * `_PAGE_` (string): if the current hook is used to render a template, its name is passed through this additional parameter. + * `_LOGGEDIN_` (bool): whether the user is logged in or not. + * `_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/`). + * `_BOOKMARK_SERVICE_` (`BookmarkServiceInterface`): bookmark service instance, for advanced usage. + +Example: + +```php +if ($data['_PAGE_'] === TemplatePage::LINKLIST && $data['LOGGEDIN'] === true) { + // Do something for logged in users when the link list is rendered +} +``` + #### Filling templates placeholder Template placeholders are displayed in template in specific places. @@ -88,7 +115,7 @@ When a page is displayed, every variable send to the template engine is passed t The data contained by this array can be altered before template rendering. -For exemple, in linklist, it is possible to alter every title: +For example, in linklist, it is possible to alter every title: ```php // mind the reference if you want $data to be altered @@ -106,9 +133,9 @@ Every plugin needs a `.meta` file, which is in fact an `.ini` file Each file contain two keys: - * `description`: plugin description - * `parameters`: user parameter names, separated by a `;`. - * `parameter.`: add a text description the specified parameter. +- `description`: plugin description +- `parameters`: user parameter names, separated by a `;`. +- `parameter.`: add a text description the specified parameter. > Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file. @@ -124,7 +151,7 @@ If it's still not working, please [open an issue](https://github.com/shaarli/Sha | ------------- |:-------------:| | [render_header](#render_header) | Allow plugin to add content in page headers. | | [render_includes](#render_includes) | Allow plugin to include their own CSS files. | -| [render_footer](#render_footer) | Allow plugin to add content in page footer and include their own JS files. | +| [render_footer](#render_footer) | Allow plugin to add content in page footer and include their own JS files. | | [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. | | [render_editlink](#render_editlink) | Allow to add fields in the form, or display elements. | | [render_tools](#render_tools) | Allow to add content at the end of the page. | @@ -135,6 +162,7 @@ If it's still not working, please [open an issue](https://github.com/shaarli/Sha | [render_feed](#render_feed) | Allow to do add tags in RSS and ATOM feeds. | | [save_link](#save_link) | Allow to alter the link being saved in the datastore. | | [delete_link](#delete_link) | Allow to do an action before a link is deleted from the datastore. | +| [save_plugin_parameters](#save_plugin_parameters) | Allow to manipulate plugin parameters before they're saved. | @@ -148,8 +176,7 @@ Allow plugin to add content in page headers. `$data` is an array containing: - * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). - * `_LOGGEDIN_`: true if user is logged in, false otherwise. + - [Special data](#special-data) ##### Template placeholders @@ -157,11 +184,11 @@ Items can be displayed in templates by adding an entry in `$data['' List of placeholders: - * `buttons_toolbar`: after the list of buttons in the header. +- `buttons_toolbar`: after the list of buttons in the header. ![buttons_toolbar_example](http://i.imgur.com/ssJUOrt.png) - * `fields_toolbar`: after search fields in the header. +- `fields_toolbar`: after search fields in the header. > Note: This will only be called in linklist. @@ -177,8 +204,7 @@ Allow plugin to include their own CSS files. `$data` is an array containing: - * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). - * `_LOGGEDIN_`: true if user is logged in, false otherwise. + - [Special data](#special-data) ##### Template placeholders @@ -186,7 +212,7 @@ Items can be displayed in templates by adding an entry in `$data['' List of placeholders: - * `css_files`: called after loading default CSS. +- `css_files`: called after loading default CSS. > Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`. @@ -200,8 +226,7 @@ Allow plugin to add content in page footer and include their own JS files. `$data` is an array containing: - * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). - * `_LOGGEDIN_`: true if user is logged in, false otherwise. + - [Special data](#special-data) ##### Template placeholders @@ -209,12 +234,12 @@ Items can be displayed in templates by adding an entry in `$data['' List of placeholders: - * `text`: called after the end of the footer text. - * `endofpage`: called at the end of the page. +- `text`: called after the end of the footer text. +- `endofpage`: called at the end of the page. ![text_example](http://i.imgur.com/L5S2YEH.png) - * `js_files`: called at the end of the page, to include custom JS scripts. +- `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`. @@ -228,8 +253,8 @@ It allows to add content at the begining and end of the page, after every link d `$data` is an array containing: - * `_LOGGEDIN_`: true if user is logged in, false otherwise. - * All templates data, including links. + - All templates data, including links. + - [Special data](#special-data) ##### Template placeholders @@ -237,19 +262,19 @@ Items can be displayed in templates by adding an entry in `$data['' List of placeholders: - * `action_plugin`: next to the button "private only" at the top and bottom of the page. +- `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) - * `link_plugin`: for every link, between permalink and link URL. +- `link_plugin`: for every link, between permalink and link URL. ![link_plugin_example](http://i.imgur.com/3oDPhWx.png) - * `plugin_start_zone`: before displaying the template content. +- `plugin_start_zone`: before displaying the template content. ![plugin_start_zone_example](http://i.imgur.com/OVBkGy3.png) - * `plugin_end_zone`: after displaying the template content. +- `plugin_end_zone`: after displaying the template content. ![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png) @@ -263,7 +288,8 @@ Allow to add fields in the form, or display elements. `$data` is an array containing: - * All templates data. + - All templates data. + - [Special data](#special-data) ##### Template placeholders @@ -271,7 +297,7 @@ Items can be displayed in templates by adding an entry in `$data['' List of placeholders: - * `edit_link_plugin`: after tags field. +- `edit_link_plugin`: after tags field. ![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png) @@ -285,7 +311,8 @@ Allow to add content at the end of the page. `$data` is an array containing: - * All templates data. + - All templates data. + - [Special data](#special-data) ##### Template placeholders @@ -293,7 +320,7 @@ Items can be displayed in templates by adding an entry in `$data['' List of placeholders: - * `tools_plugin`: at the end of the page. +- `tools_plugin`: at the end of the page. ![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png) @@ -307,8 +334,8 @@ Allow to add content at the top and bottom of the page. `$data` is an array containing: - * `_LOGGEDIN_`: true if user is logged in, false otherwise. - * All templates data. + - All templates data. + - [Special data](#special-data) ##### Template placeholders @@ -316,9 +343,8 @@ Items can be displayed in templates by adding an entry in `$data['' List of placeholders: - * `plugin_start_zone`: before displaying the template content. - - * `plugin_end_zone`: after displaying the template content. +- `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) @@ -332,8 +358,8 @@ Allow to add content at the top and bottom of the page. `$data` is an array containing: - * `_LOGGEDIN_`: true if user is logged in, false otherwise. - * All templates data. + - All templates data. + - [Special data](#special-data) ##### Template placeholders @@ -341,13 +367,12 @@ Items can be displayed in templates by adding an entry in `$data['' List of placeholders: - * `plugin_start_zone`: before displaying the template content. - - * `plugin_end_zone`: after displaying the template content. +- `plugin_start_zone`: before displaying the template content. +- `plugin_end_zone`: after displaying the template content. For each tag, the following placeholder can be used: - * `tag_plugin`: after each tag +- `tag_plugin`: after each tag ![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png) @@ -362,8 +387,8 @@ Allow to add content at the top and bottom of the page. `$data` is an array containing: - * `_LOGGEDIN_`: true if user is logged in, false otherwise. - * All templates data. + - All templates data. + - [Special data](#special-data) ##### Template placeholders @@ -371,13 +396,12 @@ Items can be displayed in templates by adding an entry in `$data['' List of placeholders: - * `plugin_start_zone`: before displaying the template content. - - * `plugin_end_zone`: after displaying the template content. +- `plugin_start_zone`: before displaying the template content. +- `plugin_end_zone`: after displaying the template content. For each tag, the following placeholder can be used: - * `tag_plugin`: after each tag +- `tag_plugin`: after each tag #### render_daily @@ -389,8 +413,8 @@ Allow to add content at the top and bottom of the page, the bottom of each link `$data` is an array containing: - * `_LOGGEDIN_`: true if user is logged in, false otherwise. - * All templates data, including links. + - All templates data, including links. + - [Special data](#special-data) ##### Template placeholders @@ -398,13 +422,12 @@ Items can be displayed in templates by adding an entry in `$data['' List of placeholders: - * `link_plugin`: used at bottom of each link. +- `link_plugin`: used at bottom of each link. ![link_plugin_example](http://i.imgur.com/hzhMfSZ.png) - * `plugin_start_zone`: before displaying the template content. - - * `plugin_end_zone`: after displaying the template content. +- `plugin_start_zone`: before displaying the template content. +- `plugin_end_zone`: after displaying the template content. #### render_feed @@ -416,9 +439,8 @@ Allow to add tags in the feed, either in the header or for each items. Items (li `$data` is an array containing: - * `_LOGGEDIN_`: true if user is logged in, false otherwise. - * `_PAGE_`: containing either `rss` or `atom`. - * All templates data, including links. + - All templates data, including links. + - [Special data](#special-data) ##### Template placeholders @@ -426,11 +448,11 @@ Tags can be added in feeds by adding an entry in `$data['']` array. List of placeholders: - * `feed_plugins_header`: used as a header tag in the feed. +- `feed_plugins_header`: used as a header tag in the feed. For each links: - * `feed_plugins`: additional tag for every link entry. +- `feed_plugins`: additional tag for every link entry. #### save_link @@ -442,15 +464,17 @@ Allow to alter the link being saved in the datastore. `$data` is an array containing the link being saved: - * id - * title - * url - * shorturl - * description - * private - * tags - * created - * updated +- id +- title +- url +- shorturl +- description +- private +- tags +- created +- updated + +Also [special data](#special-data). #### delete_link @@ -461,17 +485,35 @@ Allow to execute any action before the link is actually removed from the datasto ##### Data -`$data` is an array containing the link being saved: +`$data` is an array containing the link being deleted: + +- id +- title +- url +- shorturl +- description +- private +- tags +- created +- updated + +Also [special data](#special-data). + +#### save_plugin_parameters + +Triggered when the plugin parameters are saved from the plugin administration page. + +Plugins can perform an action every times their settings are updated. +For example it is used to update the CSS file of the `default_colors` plugins. + +##### Data + +`$data` input contains the `$_POST` array. + +So if the plugin has a parameter called `MYPLUGIN_PARAMETER`, +the array will contain an entry with `MYPLUGIN_PARAMETER` as a key. - * id - * title - * url - * shorturl - * description - * private - * tags - * created - * updated +Also [special data](#special-data). ## Guide for template designer @@ -485,9 +527,9 @@ Use the default one as an example. Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if: - * you're using a table. - * you call orderUp() and orderUp() onclick on arrows. - * you add data-line and data-order to your rows. +- you're using a table. +- you call orderUp() and orderUp() onclick on arrows. +- you add data-line and data-order to your rows. Otherwise, you can use your own JS as long as this field is send by the form: @@ -495,7 +537,7 @@ Otherwise, you can use your own JS as long as this field is send by the form: ### Placeholder system -In order to make plugins work with every custom themes, you need to add variable placeholder in your templates. +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: @@ -517,7 +559,7 @@ At the end of the menu: At the end of file, before clearing floating blocks: - {if="!empty($plugin_errors) && isLoggedIn()"} + {if="!empty($plugin_errors) && $is_logged_in"}
    {loop="plugin_errors"}
  • {$value}