-[**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
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 <plugin_name>.php file in that folder.
+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.
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 <plugin_name>.php to execute and run it if it exists. This function must be named this way, and takes the `ConfigManager` as parameter.
<plugin_name>_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 <plugin_name>.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.
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
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.
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
Each file contain two keys:
- * `description`: plugin description
- * `parameters`: user parameter names, separated by a `;`.
-
* `parameter.<PARAMETER_NAME>`: add a text description the specified parameter.
+- `description`: plugin description
+- `parameters`: user parameter names, separated by a `;`.
+
- `parameter.<PARAMETER_NAME>`: 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.
| ------------- |:-------------:|
| [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. |
| [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. |
`$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
List of placeholders:
- * `buttons_toolbar`: after the list of buttons in the header.
+- `buttons_toolbar`: after the list of buttons in the header.
- * `fields_toolbar`: after search fields in the header.
+- `fields_toolbar`: after search fields in the header.
> Note: This will only be called in linklist.
`$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
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`.
`$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
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.
- * `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`.
`$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
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.
- * `link_plugin`: for every link, between permalink and link URL.
+- `link_plugin`: for every link, between permalink and link URL.
- * `plugin_start_zone`: before displaying the template content.
+- `plugin_start_zone`: before displaying the template content.
- * `plugin_end_zone`: after displaying the template content.
+- `plugin_end_zone`: after displaying the template content.
`$data` is an array containing:
- * All templates data.
+ - All templates data.
+ - [Special data](#special-data)
##### Template placeholders
List of placeholders:
- * `edit_link_plugin`: after tags field.
+- `edit_link_plugin`: after tags field.
`$data` is an array containing:
- * All templates data.
+ - All templates data.
+ - [Special data](#special-data)
##### Template placeholders
List of placeholders:
- * `tools_plugin`: at the end of the page.
+- `tools_plugin`: at the end 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
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.
`$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
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
`$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
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
`$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
List of placeholders:
- * `link_plugin`: used at bottom of each link.
+- `link_plugin`: used at bottom of each link.
- * `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
`$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
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
`$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
##### 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
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:
### 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:
At the end of file, before clearing floating blocks:
- {if="!empty($plugin_errors) && isLoggedIn()"}
+ {if="!empty($plugin_errors) && $is_logged_in"}
<ul class="errors">
{loop="plugin_errors"}
<li>{$value}</li>
projects / github / shaarli / Shaarli.git / blobdiff