aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/Plugin-System.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/Plugin-System.md')
-rw-r--r--doc/Plugin-System.md130
1 files changed, 122 insertions, 8 deletions
diff --git a/doc/Plugin-System.md b/doc/Plugin-System.md
index 623627dd..addd792d 100644
--- a/doc/Plugin-System.md
+++ b/doc/Plugin-System.md
@@ -1,6 +1,4 @@
1#Plugin System 1#Plugin System
2> Note: Plugin current status - in development (not merged into master).
3
4[**I am a developer.** Developer API.](#developer-api)[](.html) 2[**I am a developer.** Developer API.](#developer-api)[](.html)
5 3
6[**I am a template designer.** Guide for template designer.](#guide-for-template-designer)[](.html) 4[**I am a template designer.** Guide for template designer.](#guide-for-template-designer)[](.html)
@@ -30,6 +28,14 @@ You should have the following tree view:
30| |---| demo_plugin.php 28| |---| demo_plugin.php
31``` 29```
32 30
31### Plugin initialization
32
33At 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.
34
35 <plugin_name>_init($conf)
36
37This 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
33### Understanding hooks 39### Understanding hooks
34 40
35A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution. 41A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.
@@ -37,12 +43,17 @@ A plugin is a set of functions. Each function will be triggered by the plugin sy
37These functions need to be named with this pattern: 43These functions need to be named with this pattern:
38 44
39``` 45```
40hook_<plugin_name>_<hook_name> 46hook_<plugin_name>_<hook_name>($data, $conf)
41``` 47```
42 48
49Parameters:
50
51 - data: see [$data section](https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data)[](.html)
52 - conf: the `ConfigManager` instance.
53
43For exemple, if my plugin want to add data to the header, this function is needed: 54For exemple, if my plugin want to add data to the header, this function is needed:
44 55
45 hook_demo_plugin_render_header() 56 hook_demo_plugin_render_header
46 57
47If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header. 58If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.
48 59
@@ -98,6 +109,7 @@ Each file contain two keys:
98 109
99 * `description`: plugin description 110 * `description`: plugin description
100 * `parameters`: user parameter names, separated by a `;`. 111 * `parameters`: user parameter names, separated by a `;`.
112 * `parameter.<PARAMETER_NAME>`: add a text description the specified parameter.
101 113
102> Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file. 114> Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file.
103 115
@@ -118,9 +130,13 @@ If it's still not working, please [open an issue](https://github.com/shaarli/Sha
118| [render_editlink](#render_editlink) | Allow to add fields in the form, or display elements. |[](.html) 130| [render_editlink](#render_editlink) | Allow to add fields in the form, or display elements. |[](.html)
119| [render_tools](#render_tools) | Allow to add content at the end of the page. |[](.html) 131| [render_tools](#render_tools) | Allow to add content at the end of the page. |[](.html)
120| [render_picwall](#render_picwall) | Allow to add content at the top and bottom of the page. |[](.html) 132| [render_picwall](#render_picwall) | Allow to add content at the top and bottom of the page. |[](.html)
121| [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page. |[](.html) 133| [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page, and after all tags. |[](.html)
134| [render_taglist](#render_taglist) | Allow to add content at the top and bottom of the page, and after all tags. |[](.html)
122| [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. |[](.html) 135| [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. |[](.html)
123| [savelink](#savelink) | Allow to alter the link being saved in the datastore. |[](.html) 136| [render_feed](#render_feed) | Allow to do add tags in RSS and ATOM feeds. |[](.html)
137| [save_link](#save_link) | Allow to alter the link being saved in the datastore. |[](.html)
138| [delete_link](#delete_link) | Allow to do an action before a link is deleted from the datastore. |[](.html)
139
124 140
125 141
126#### render_header 142#### render_header
@@ -330,8 +346,40 @@ List of placeholders:
330 346
331 * `plugin_end_zone`: after displaying the template content. 347 * `plugin_end_zone`: after displaying the template content.
332 348
349For each tag, the following placeholder can be used:
350
351 * `tag_plugin`: after each tag
352
333![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png)[](.html) 353![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png)[](.html)
334 354
355
356#### render_taglist
357
358Triggered when taglist is displayed.
359
360Allow to add content at the top and bottom of the page.
361
362##### Data
363
364`$data` is an array containing:
365
366 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
367 * All templates data.
368
369##### Template placeholders
370
371Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
372
373List of placeholders:
374
375 * `plugin_start_zone`: before displaying the template content.
376
377 * `plugin_end_zone`: after displaying the template content.
378
379For each tag, the following placeholder can be used:
380
381 * `tag_plugin`: after each tag
382
335#### render_daily 383#### render_daily
336 384
337Triggered when tagcloud is displayed. 385Triggered when tagcloud is displayed.
@@ -359,7 +407,33 @@ List of placeholders:
359 407
360 * `plugin_end_zone`: after displaying the template content. 408 * `plugin_end_zone`: after displaying the template content.
361 409
362#### savelink 410#### render_feed
411
412Triggered when the ATOM or RSS feed is displayed.
413
414Allow to add tags in the feed, either in the header or for each items. Items (links) can also be altered before being rendered.
415
416##### Data
417
418`$data` is an array containing:
419
420 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
421 * `_PAGE_`: containing either `rss` or `atom`.
422 * All templates data, including links.
423
424##### Template placeholders
425
426Tags can be added in feeds by adding an entry in `$data['<placeholder>']` array.[](.html)
427
428List of placeholders:
429
430 * `feed_plugins_header`: used as a header tag in the feed.
431
432For each links:
433
434 * `feed_plugins`: additional tag for every link entry.
435
436#### save_link
363 437
364Triggered when a link is save (new link or edit). 438Triggered when a link is save (new link or edit).
365 439
@@ -369,12 +443,36 @@ Allow to alter the link being saved in the datastore.
369 443
370`$data` is an array containing the link being saved: 444`$data` is an array containing the link being saved:
371 445
446 * id
447 * title
448 * url
449 * shorturl
450 * description
451 * private
452 * tags
453 * created
454 * updated
455
456
457#### delete_link
458
459Triggered when a link is deleted.
460
461Allow to execute any action before the link is actually removed from the datastore
462
463##### Data
464
465`$data` is an array containing the link being saved:
466
467 * id
372 * title 468 * title
373 * url 469 * url
470 * shorturl
374 * description 471 * description
375 * linkdate
376 * private 472 * private
377 * tags 473 * tags
474 * created
475 * updated
378 476
379## Guide for template designer 477## Guide for template designer
380 478
@@ -595,3 +693,19 @@ Bottom:
595 {/loop} 693 {/loop}
596</div> 694</div>
597``` 695```
696
697**feed.atom.xml** and **feed.rss.xml**:
698
699In headers tags section:
700```xml
701{loop="$feed_plugins_header"}
702 {$value}
703{/loop}
704```
705
706After each entry:
707```xml
708{loop="$value.feed_plugins"}
709 {$value}
710{/loop}
711```