**General rewording, proof-reading, deduplication, shortening, reordering, simplifica...

[github/shaarli/Shaarli.git] / doc / md / dev / Plugin-system.md

diff --git a/doc/md/Plugin-System.md b/doc/md/dev/Plugin-system.md
similarity index 96%
rename from doc/md/Plugin-System.md
rename to doc/md/dev/Plugin-system.md
index 87a2638dbea73fc3ef9262ccf7bd208af3ea8d81..a87bd0cf7ae3b27c674331e82584e4411986473b 100644 (file)
--- a/doc/md/Plugin-System.md
+++ b/doc/md/dev/Plugin-system.md
@@ -1,19 +1,16 @@
-[**I am a developer: ** Developer API](#developer-api)
-
-[**I am a template designer: ** Guide for template designers](#guide-for-template-designer)
-
----
+# Plugin system
 
 ## Developer API
 
 ### What can I do with plugins?
 
-The plugin system let you:
+The plugin system lets you:
 
 - 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`.
@@ -30,6 +27,7 @@ You should have the following tree view:
 |   |---| 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 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.
@@ -63,6 +61,7 @@ For example, if my plugin want to add data to the header, this function is neede
 
 If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.
 
+
 ### Plugin's data
 
 #### Parameters
@@ -109,6 +108,7 @@ array_push($data['top_placeholder'], 'My', 'content');
 return $data;
 ```
 
+
 #### Data manipulation
 
 When a page is displayed, every variable send to the template engine is passed to plugins before that in `$data`.
@@ -139,12 +139,14 @@ Each file contain two keys:
 
 > Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file.
 
+
 ### It's not working!
 
 Use `demo_plugin` as a functional example. It covers most of the plugin system features.
 
 If it's still not working, please [open an issue](https://github.com/shaarli/Shaarli/issues/new).
 
+
 ### Hooks
 
 | Hooks         | Description   |
@@ -165,12 +167,10 @@ If it's still not working, please [open an issue](https://github.com/shaarli/Sha
 | [save_plugin_parameters](#save_plugin_parameters) | Allow to manipulate plugin parameters before they're saved. |
 
 
-
 #### render_header
 
-Triggered on every page.
+Triggered on every page - allows plugins to add content in page headers.
 
-Allow plugin to add content in page headers.
 
 ##### Data
 
@@ -194,13 +194,12 @@ List of placeholders:
 
 ![fields_toolbar_example](http://i.imgur.com/3GMifI2.png)
 
-#### render_includes
 
-Triggered on every page.
+#### render_includes
 
-Allow plugin to include their own CSS files.
+Triggered on every page - allows plugins to include their own CSS files.
 
-##### Data
+##### data
 
 `$data` is an array containing:
 
@@ -216,13 +215,14 @@ List of placeholders:
 
 > Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`.
 
+
 #### render_footer
 
 Triggered on every page.
 
 Allow plugin to add content in page footer and include their own JS files.
 
-##### Data
+##### data
 
 `$data` is an array containing:
 
@@ -243,20 +243,21 @@ List of placeholders:
 
 > Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`.
 
+
 #### render_linklist
 
 Triggered when `linklist` is displayed (list of links, permalink, search, tag filtered, etc.).
 
 It allows to add content at the begining and end of the page, after every link displayed and to alter link data.
 
-##### Data
+##### data
 
 `$data` is an array containing:
 
   - All templates data, including links.
   - [Special data](#special-data)
 
-##### Template placeholders
+##### template placeholders
 
 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
 
@@ -278,20 +279,21 @@ List of placeholders:
 
 ![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png)
 
+
 #### render_editlink
 
 Triggered when the link edition form is displayed.
 
 Allow to add fields in the form, or display elements.
 
-##### Data
+##### data
 
 `$data` is an array containing:
 
   - All templates data.
   - [Special data](#special-data)
 
-##### Template placeholders
+##### template placeholders
 
 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
 
@@ -301,20 +303,21 @@ List of placeholders:
 
 ![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png)
 
+
 #### render_tools
 
 Triggered when the "tools" page is displayed.
 
 Allow to add content at the end of the page.
 
-##### Data
+##### data
 
 `$data` is an array containing:
 
   - All templates data.
   - [Special data](#special-data)
 
-##### Template placeholders
+##### template placeholders
 
 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
 
@@ -324,20 +327,21 @@ List of placeholders:
 
 ![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png)
 
+
 #### render_picwall
 
 Triggered when picwall is displayed.
 
 Allow to add content at the top and bottom of the page.
 
-##### Data
+##### data
 
 `$data` is an array containing:
 
   - All templates data.
   - [Special data](#special-data)
 
-##### Template placeholders
+##### template placeholders
 
 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
 
@@ -348,13 +352,14 @@ List of placeholders:
 
 ![plugin_start_end_zone_example](http://i.imgur.com/tVTQFER.png)
 
+
 #### render_tagcloud
 
 Triggered when tagcloud is displayed.
 
 Allow to add content at the top and bottom of the page.
 
-##### Data
+##### data
 
 `$data` is an array containing:
 
@@ -379,11 +384,9 @@ For each tag, the following placeholder can be used:
 
 #### render_taglist
 
-Triggered when taglist is displayed.
-
-Allow to add content at the top and bottom of the page.
+Triggered when taglist is displayed - allows to add content at the top and bottom of the page.
 
-##### Data
+##### data
 
 `$data` is an array containing:
 
@@ -409,7 +412,8 @@ Triggered when tagcloud is displayed.
 
 Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.
 
-##### Data
+
+##### data
 
 `$data` is an array containing:
 
@@ -429,13 +433,14 @@ List of placeholders:
 - `plugin_start_zone`: before displaying the template content.
 - `plugin_end_zone`: after displaying the template content.
 
+
 #### render_feed
 
 Triggered when the ATOM or RSS feed is displayed.
 
 Allow to add tags in the feed, either in the header or for each items. Items (links) can also be altered before being rendered.
 
-##### Data
+##### data
 
 `$data` is an array containing:
 
@@ -454,13 +459,14 @@ For each links:
 
 - `feed_plugins`: additional tag for every link entry.
 
+
 #### save_link
 
 Triggered when a link is save (new link or edit).
 
 Allow to alter the link being saved in the datastore.
 
-##### Data
+##### data
 
 `$data` is an array containing the link being saved:
 
@@ -483,7 +489,7 @@ Triggered when a link is deleted.
 
 Allow to execute any action before the link is actually removed from the datastore
 
-##### Data
+##### data
 
 `$data` is an array containing the link being deleted:
 
@@ -506,7 +512,7 @@ Triggered when the plugin parameters are saved from the plugin administration pa
 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
 
 `$data` input contains the `$_POST` array.
 
@@ -515,7 +521,7 @@ the array will contain an entry with `MYPLUGIN_PARAMETER` as a key.
 
 Also [special data](#special-data).
 
-## Guide for template designer
+## Guide for template designers
 
 ### Plugin administration