X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=doc%2Fmd%2FPlugin-System.md;h=87a2638dbea73fc3ef9262ccf7bd208af3ea8d81;hb=6128ab6a55430a2b705be31ff417c0c552a0db1f;hp=cbec04c0fa0bf12ad87f2b33824c64f7c2700c0b;hpb=96a1c79456b27892b9221707803f29585565b9dc;p=github%2Fshaarli%2FShaarli.git diff --git a/doc/md/Plugin-System.md b/doc/md/Plugin-System.md index cbec04c0..87a2638d 100644 --- a/doc/md/Plugin-System.md +++ b/doc/md/Plugin-System.md @@ -18,7 +18,7 @@ The plugin system let you: 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: @@ -26,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. @@ -68,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. @@ -90,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 @@ -126,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. | @@ -137,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. | @@ -150,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 @@ -179,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 @@ -202,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 @@ -230,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 @@ -265,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 @@ -287,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 @@ -309,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 @@ -333,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 @@ -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 @@ -388,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 @@ -414,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 @@ -450,6 +474,8 @@ Allow to alter the link being saved in the datastore. - created - updated +Also [special data](#special-data). + #### delete_link @@ -459,7 +485,7 @@ 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 @@ -471,6 +497,24 @@ Allow to execute any action before the link is actually removed from the datasto - 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. + +Also [special data](#special-data). + ## Guide for template designer ### Plugin administration @@ -493,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: @@ -515,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}