aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/Plugin-System.md
diff options
context:
space:
mode:
authorVirtualTam <virtualtam@flibidi.net>2015-08-04 16:07:13 +0200
committerVirtualTam <virtualtam@flibidi.net>2015-08-04 16:07:13 +0200
commit27cf2e671d1f35bd8c9383d008cd3733fc1c6e0d (patch)
tree4726baf18e7057eac3f9b6bdb5991fe6117814fc /doc/Plugin-System.md
parent96db105e4c0833324f7168edb5673278de8ccd54 (diff)
parent992af0b9d77cb4fbac2c37ef8d5896042d67a2a3 (diff)
downloadShaarli-27cf2e671d1f35bd8c9383d008cd3733fc1c6e0d.tar.gz
Shaarli-27cf2e671d1f35bd8c9383d008cd3733fc1c6e0d.tar.zst
Shaarli-27cf2e671d1f35bd8c9383d008cd3733fc1c6e0d.zip
Merge pull request #294 from virtualtam/doc/update
Doc: sync from Wiki, generate HTML
Diffstat (limited to 'doc/Plugin-System.md')
-rw-r--r--doc/Plugin-System.md590
1 files changed, 590 insertions, 0 deletions
diff --git a/doc/Plugin-System.md b/doc/Plugin-System.md
new file mode 100644
index 00000000..8cba6664
--- /dev/null
+++ b/doc/Plugin-System.md
@@ -0,0 +1,590 @@
1#Plugin System
2> Note: Plugin current status - in developpement (not merged into master).
3
4[**I am a user.** Plugin User Guide.](#plugin-user-guide)[](.html)
5
6[**I am a developper.** Developper API.](#developper-api)[](.html)
7
8[**I am a template designer.** Guide for template designer.](#guide-for-template-designer)[](.html)
9
10## Plugin User Guide
11
12### Manage plugins
13
14In `config.php`, change $GLOBALS['config'['ENABLED_PLUGINS'] array:]('ENABLED_PLUGINS']-array:.html)
15
16```php
17$GLOBALS['config'['ENABLED_PLUGINS']]('ENABLED_PLUGINS'].html)
18```
19
20Full list:
21
22```php
23$GLOBALS['config'['ENABLED_PLUGINS'] = array(]('ENABLED_PLUGINS']-=-array(.html)
24 'qrcode', 'archiveorg', 'readityourself', 'playvideos',
25 'wallabag', 'markdown', 'addlink_toolbar',
26);
27```
28
29### List of plugins
30
31Plugin maintained by the community:
32
33 * Archive.org - add a clickable icon to every link to archive.org.
34 * Addlink in toolbar - add a field to paste new links URL in toolbar.
35 * Markdown - write and display Shaare in Markdown.
36 * Play videos - popup to play all videos displayed in linklist.
37 * QRCode - add a clickable icon generating a QRCode for every link.
38 * ReadItYourself - add a clickable icon for ReadItYourself.
39 * Wallabag - add a clickable icon for Wallabag.
40
41## Developper API
42
43### What can I do with plugins?
44
45The plugin system let you:
46
47 * insert content into specific places across templates.
48 * alter data before templates rendering.
49 * alter data before saving new links.
50
51### How can I create a plugin for Shaarli?
52
53First, chose a plugin name, such as `demo_plugin`.
54
55Under `plugin` folder, create a folder named with your plugin name. Then create a <plugin_name>.php file in that folder.
56
57You should have the following tree view:
58
59```
60| index.php
61| plugins/
62|---| demo_plugin/
63| |---| demo_plugin.php
64```
65
66### Understanding hooks
67
68A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.
69
70These functions need to be named with this pattern:
71
72```
73hook_<plugin_name>_<hook_name>
74```
75
76For exemple, if my plugin want to add data to the header, this function is needed:
77
78 hook_demo_plugin_render_header()
79
80If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.
81
82### Plugin's data
83
84#### Parameters
85
86Every hook function has a `$data` parameter. Its content differs for each hooks.
87
88**This parameter needs to be returned every time**, otherwise data is lost.
89
90 return $data;
91
92#### Filling templates placeholder
93
94Template placeholders are displayed in template in specific places.
95
96RainTPL displays every element contained in the placeholder's array. These element can be added by plugins.
97
98For example, let's add a value in the placeholder `top_placeholder` which is displayed at the top of my page:
99
100```php
101$data['top_placeholder'[] = 'My content';](]-=-'My-content';.html)
102# OR
103array_push($data['top_placeholder'], 'My', 'content');[](.html)
104
105return $data;
106```
107
108#### Data manipulation
109
110When a page is displayed, every variable send to the template engine is passed to plugins before that in `$data`.
111
112The data contained by this array can be altered before template rendering.
113
114For exemple, in linklist, it is possible to alter every title:
115
116```php
117// mind the reference if you want $data to be altered
118foreach ($data['links'] as &$value) {[](.html)
119 // String reverse every title.
120 $value['title'] = strrev($value['title']);[](.html)
121}
122
123return $data;
124```
125
126### It's not working!
127
128Use `demo_plugin` as a functional example. It covers most of the plugin system features.
129
130If it's still not working, please [open an issue](https://github.com/shaarli/Shaarli/issues/new).[](.html)
131
132### Hooks
133
134| Hooks | Description |
135| ------------- |:-------------:|
136| [render_header](#render_header) | Allow plugin to add content in page headers. |[](.html)
137| [render_includes](#render_includes) | Allow plugin to include their own CSS files. |[](.html)
138| [render_footer](#render_footer) | Allow plugin to add content in page footer and include their own JS files. | [](.html)
139| [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. |[](.html)
140| [render_editlink](#render_editlink) | Allow to add fields in the form, or display elements. |[](.html)
141| [render_tools](#render_tools) | Allow to add content at the end of the page. |[](.html)
142| [render_picwall](#render_picwall) | Allow to add content at the top and bottom of the page. |[](.html)
143| [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page. |[](.html)
144| [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)
145| [savelink](#savelink) | Allow to alter the link being saved in the datastore. |[](.html)
146
147
148#### render_header
149
150Triggered on every page.
151
152Allow plugin to add content in page headers.
153
154##### Data
155
156`$data` is an array containing:
157
158 * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
159 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
160
161##### Template placeholders
162
163Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
164
165List of placeholders:
166
167 * `buttons_toolbar`: after the list of buttons in the header.
168
169![buttons_toolbar_example](http://i.imgur.com/ssJUOrt.png)[](.html)
170
171 * `fields_toolbar`: after search fields in the header.
172
173> Note: This will only be called in linklist.
174
175![fields_toolbar_example](http://i.imgur.com/3GMifI2.png)[](.html)
176
177#### render_includes
178
179Triggered on every page.
180
181Allow plugin to include their own CSS files.
182
183##### Data
184
185`$data` is an array containing:
186
187 * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
188 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
189
190##### Template placeholders
191
192Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
193
194List of placeholders:
195
196 * `css_files`: called after loading default CSS.
197
198> Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`.
199
200#### render_footer
201
202Triggered on every page.
203
204Allow plugin to add content in page footer and include their own JS files.
205
206##### Data
207
208`$data` is an array containing:
209
210 * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
211 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
212
213##### Template placeholders
214
215Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
216
217List of placeholders:
218
219 * `text`: called after the end of the footer text.
220
221![text_example](http://i.imgur.com/L5S2YEH.png)[](.html)
222
223 * `js_files`: called at the end of the page, to include custom JS scripts.
224
225> Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`.
226
227#### render_linklist
228
229Triggered when `linklist` is displayed (list of links, permalink, search, tag filtered, etc.).
230
231It allows to add content at the begining and end of the page, after every link displayed and to alter link data.
232
233##### Data
234
235`$data` is an array containing:
236
237 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
238 * All templates data, including links.
239
240##### Template placeholders
241
242Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
243
244List of placeholders:
245
246 * `action_plugin`: next to the button "private only" at the top and bottom of the page.
247
248![action_plugin_example](http://i.imgur.com/Q12PWg0.png)[](.html)
249
250 * `link_plugin`: for every link, between permalink and link URL.
251
252![link_plugin_example](http://i.imgur.com/3oDPhWx.png)[](.html)
253
254 * `plugin_start_zone`: before displaying the template content.
255
256![plugin_start_zone_example](http://i.imgur.com/OVBkGy3.png)[](.html)
257
258 * `plugin_end_zone`: after displaying the template content.
259
260![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png)[](.html)
261
262#### render_editlink
263
264Triggered when the link edition form is displayed.
265
266Allow to add fields in the form, or display elements.
267
268##### Data
269
270`$data` is an array containing:
271
272 * All templates data.
273
274##### Template placeholders
275
276Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
277
278List of placeholders:
279
280 * `edit_link_plugin`: after tags field.
281
282![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png)[](.html)
283
284#### render_tools
285
286Triggered when the "tools" page is displayed.
287
288Allow to add content at the end of the page.
289
290##### Data
291
292`$data` is an array containing:
293
294 * All templates data.
295
296##### Template placeholders
297
298Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
299
300List of placeholders:
301
302 * `tools_plugin`: at the end of the page.
303
304![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png)[](.html)
305
306#### render_picwall
307
308Triggered when picwall is displayed.
309
310Allow to add content at the top and bottom of the page.
311
312##### Data
313
314`$data` is an array containing:
315
316 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
317 * All templates data.
318
319##### Template placeholders
320
321Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
322
323List of placeholders:
324
325 * `plugin_start_zone`: before displaying the template content.
326
327 * `plugin_end_zone`: after displaying the template content.
328
329![plugin_start_end_zone_example](http://i.imgur.com/tVTQFER.png)[](.html)
330
331#### render_tagcloud
332
333Triggered when tagcloud is displayed.
334
335Allow to add content at the top and bottom of the page.
336
337##### Data
338
339`$data` is an array containing:
340
341 * `_LOGGEDIN_`: true if user is logged in, false otherwise.
342 * All templates data.
343
344##### Template placeholders
345
346Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
347
348List of placeholders:
349
350 * `plugin_start_zone`: before displaying the template content.
351
352 * `plugin_end_zone`: after displaying the template content.
353
354![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png)[](.html)
355
356#### render_daily
357
358Triggered when tagcloud is displayed.
359
360Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.
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, including links.
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 * `link_plugin`: used at bottom of each link.
376
377![link_plugin_example](http://i.imgur.com/hzhMfSZ.png)[](.html)
378
379 * `plugin_start_zone`: before displaying the template content.
380
381 * `plugin_end_zone`: after displaying the template content.
382
383#### savelink
384
385Triggered when a link is save (new link or edit).
386
387Allow to alter the link being saved in the datastore.
388
389##### Data
390
391`$data` is an array containing the link being saved:
392
393 * title
394 * url
395 * description
396 * linkdate
397 * private
398 * tags
399
400## Guide for template designer
401
402### Placeholder system
403
404In order to make plugins work with every custom themes, you need to add variable placeholder in your templates.
405
406It's a RainTPL loop like this:
407
408 {loop="$plugin_variable"}
409 {$value}
410 {/loop}
411
412You should enable `demo_plugin` for testing purpose, since it uses every placeholder available.
413
414### List of placeholders
415
416**page.header.html**
417
418At the end of the menu:
419
420 {loop="$plugins_header.buttons_toolbar"}
421 {$value}
422 {/loop}
423
424**includes.html**
425
426At the end of the file:
427
428```html
429{loop="$plugins_includes.css_files"}
430<link type="text/css" rel="stylesheet" href="{$value}#"/>
431{/loop}
432```
433
434**page.footer.html**
435
436At the end of your footer notes:
437
438```html
439{loop="$plugins_footer.text"}
440 {$value}
441{/loop}
442```
443
444At the end of file:
445
446```html
447{loop="$plugins_footer.js_files"}
448 <script src="{$value}#"></script>
449{/loop}
450```
451
452**linklist.html**
453
454After search fields:
455
456```html
457{loop="$plugins_header.fields_toolbar"}
458 {$value}
459{/loop}
460```
461
462Before displaying the link list (after paging):
463
464```html
465{loop="$plugin_start_zone"}
466 {$value}
467{/loop}
468```
469
470For every links (icons):
471
472```html
473{loop="$value.link_plugin"}
474 <span>{$value}</span>
475{/loop}
476```
477
478Before end paging:
479
480```html
481{loop="$plugin_end_zone"}
482 {$value}
483{/loop}
484```
485
486**linklist.paging.html**
487
488After the "private only" icon:
489
490```html
491{loop="$action_plugin"}
492 {$value}
493{/loop}
494```
495
496**editlink.html**
497
498After tags field:
499
500```html
501{loop="$edit_link_plugin"}
502 {$value}
503{/loop}
504```
505
506**tools.html**
507
508After the last tool:
509
510```html
511{loop="$tools_plugin"}
512 {$value}
513{/loop}
514```
515
516**picwall.html**
517
518Top:
519
520```html
521<div id="plugin_zone_start_picwall" class="plugin_zone">
522 {loop="$plugin_start_zone"}
523 {$value}
524 {/loop}
525</div>
526```
527
528Bottom:
529
530```html
531<div id="plugin_zone_end_picwall" class="plugin_zone">
532 {loop="$plugin_end_zone"}
533 {$value}
534 {/loop}
535</div>
536```
537
538**tagcloud.html**
539
540Top:
541
542```html
543 <div id="plugin_zone_start_tagcloud" class="plugin_zone">
544 {loop="$plugin_start_zone"}
545 {$value}
546 {/loop}
547 </div>
548```
549
550Bottom:
551
552```html
553 <div id="plugin_zone_end_tagcloud" class="plugin_zone">
554 {loop="$plugin_end_zone"}
555 {$value}
556 {/loop}
557 </div>
558```
559
560**daily.html**
561
562Top:
563
564```html
565<div id="plugin_zone_start_picwall" class="plugin_zone">
566 {loop="$plugin_start_zone"}
567 {$value}
568 {/loop}
569</div>
570```
571
572After every link:
573
574```html
575<div class="dailyEntryFooter">
576 {loop="$link.link_plugin"}
577 {$value}
578 {/loop}
579</div>
580```
581
582Bottom:
583
584```html
585<div id="plugin_zone_end_picwall" class="plugin_zone">
586 {loop="$plugin_end_zone"}
587 {$value}
588 {/loop}
589</div>
590```