aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md/Plugin-System.md
diff options
context:
space:
mode:
authorVirtualTam <virtualtam+github@flibidi.net>2017-08-06 16:15:32 +0200
committerGitHub <noreply@github.com>2017-08-06 16:15:32 +0200
commitc7fcea1347e81072c5b77c1b3c2c6fb13f02c16f (patch)
tree03e4d7bbdcfebdb704266caf4b5c0d87e90c02ce /doc/md/Plugin-System.md
parent4758c18164f8168be0b3e422c4af86827c913390 (diff)
parentf320efd689f17737ccbdef46cdc430d9e637b807 (diff)
downloadShaarli-c7fcea1347e81072c5b77c1b3c2c6fb13f02c16f.tar.gz
Shaarli-c7fcea1347e81072c5b77c1b3c2c6fb13f02c16f.tar.zst
Shaarli-c7fcea1347e81072c5b77c1b3c2c6fb13f02c16f.zip
Merge pull request #917 from virtualtam/documentation/fixes+improvements
Documentation fixes, improvements and additions
Diffstat (limited to 'doc/md/Plugin-System.md')
-rw-r--r--doc/md/Plugin-System.md160
1 files changed, 79 insertions, 81 deletions
diff --git a/doc/md/Plugin-System.md b/doc/md/Plugin-System.md
index d55ffe7e..30f0ae74 100644
--- a/doc/md/Plugin-System.md
+++ b/doc/md/Plugin-System.md
@@ -1,6 +1,8 @@
1[**I am a developer.** Developer API.](#developer-api) 1[**I am a developer: ** Developer API](#developer-api)
2 2
3[**I am a template designer.** Guide for template designer.](#guide-for-template-designer) 3[**I am a template designer: ** Guide for template designers](#guide-for-template-designer)
4
5---
4 6
5## Developer API 7## Developer API
6 8
@@ -8,9 +10,9 @@
8 10
9The plugin system let you: 11The plugin system let you:
10 12
11 * insert content into specific places across templates. 13- insert content into specific places across templates.
12 * alter data before templates rendering. 14- alter data before templates rendering.
13 * alter data before saving new links. 15- alter data before saving new links.
14 16
15### How can I create a plugin for Shaarli? 17### How can I create a plugin for Shaarli?
16 18
@@ -47,8 +49,8 @@ hook_<plugin_name>_<hook_name>($data, $conf)
47 49
48Parameters: 50Parameters:
49 51
50 - data: see [$data section](https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data) 52- data: see [$data section](https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data)
51 - conf: the `ConfigManager` instance. 53- conf: the `ConfigManager` instance.
52 54
53For exemple, if my plugin want to add data to the header, this function is needed: 55For exemple, if my plugin want to add data to the header, this function is needed:
54 56
@@ -106,9 +108,9 @@ Every plugin needs a `<plugin_name>.meta` file, which is in fact an `.ini` file
106 108
107Each file contain two keys: 109Each file contain two keys:
108 110
109 * `description`: plugin description 111- `description`: plugin description
110 * `parameters`: user parameter names, separated by a `;`. 112- `parameters`: user parameter names, separated by a `;`.
111 * `parameter.<PARAMETER_NAME>`: add a text description the specified parameter. 113- `parameter.<PARAMETER_NAME>`: add a text description the specified parameter.
112 114
113> Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file. 115> Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file.
114 116
@@ -148,8 +150,8 @@ Allow plugin to add content in page headers.
148 150
149`$data` is an array containing: 151`$data` is an array containing:
150 152
151 * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). 153- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
152 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 154- `_LOGGEDIN_`: true if user is logged in, false otherwise.
153 155
154##### Template placeholders 156##### Template placeholders
155 157
@@ -157,11 +159,11 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
157 159
158List of placeholders: 160List of placeholders:
159 161
160 * `buttons_toolbar`: after the list of buttons in the header. 162- `buttons_toolbar`: after the list of buttons in the header.
161 163
162![buttons_toolbar_example](http://i.imgur.com/ssJUOrt.png) 164![buttons_toolbar_example](http://i.imgur.com/ssJUOrt.png)
163 165
164 * `fields_toolbar`: after search fields in the header. 166- `fields_toolbar`: after search fields in the header.
165 167
166> Note: This will only be called in linklist. 168> Note: This will only be called in linklist.
167 169
@@ -177,8 +179,8 @@ Allow plugin to include their own CSS files.
177 179
178`$data` is an array containing: 180`$data` is an array containing:
179 181
180 * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). 182- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
181 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 183- `_LOGGEDIN_`: true if user is logged in, false otherwise.
182 184
183##### Template placeholders 185##### Template placeholders
184 186
@@ -186,7 +188,7 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
186 188
187List of placeholders: 189List of placeholders:
188 190
189 * `css_files`: called after loading default CSS. 191- `css_files`: called after loading default CSS.
190 192
191> Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`. 193> Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`.
192 194
@@ -200,8 +202,8 @@ Allow plugin to add content in page footer and include their own JS files.
200 202
201`$data` is an array containing: 203`$data` is an array containing:
202 204
203 * `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.). 205- `_PAGE_`: current target page (eg: `linklist`, `picwall`, etc.).
204 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 206- `_LOGGEDIN_`: true if user is logged in, false otherwise.
205 207
206##### Template placeholders 208##### Template placeholders
207 209
@@ -209,12 +211,12 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
209 211
210List of placeholders: 212List of placeholders:
211 213
212 * `text`: called after the end of the footer text. 214- `text`: called after the end of the footer text.
213 * `endofpage`: called at the end of the page. 215- `endofpage`: called at the end of the page.
214 216
215![text_example](http://i.imgur.com/L5S2YEH.png) 217![text_example](http://i.imgur.com/L5S2YEH.png)
216 218
217 * `js_files`: called at the end of the page, to include custom JS scripts. 219- `js_files`: called at the end of the page, to include custom JS scripts.
218 220
219> Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`. 221> Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`.
220 222
@@ -228,8 +230,8 @@ It allows to add content at the begining and end of the page, after every link d
228 230
229`$data` is an array containing: 231`$data` is an array containing:
230 232
231 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 233- `_LOGGEDIN_`: true if user is logged in, false otherwise.
232 * All templates data, including links. 234- All templates data, including links.
233 235
234##### Template placeholders 236##### Template placeholders
235 237
@@ -237,19 +239,19 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
237 239
238List of placeholders: 240List of placeholders:
239 241
240 * `action_plugin`: next to the button "private only" at the top and bottom of the page. 242- `action_plugin`: next to the button "private only" at the top and bottom of the page.
241 243
242![action_plugin_example](http://i.imgur.com/Q12PWg0.png) 244![action_plugin_example](http://i.imgur.com/Q12PWg0.png)
243 245
244 * `link_plugin`: for every link, between permalink and link URL. 246- `link_plugin`: for every link, between permalink and link URL.
245 247
246![link_plugin_example](http://i.imgur.com/3oDPhWx.png) 248![link_plugin_example](http://i.imgur.com/3oDPhWx.png)
247 249
248 * `plugin_start_zone`: before displaying the template content. 250- `plugin_start_zone`: before displaying the template content.
249 251
250![plugin_start_zone_example](http://i.imgur.com/OVBkGy3.png) 252![plugin_start_zone_example](http://i.imgur.com/OVBkGy3.png)
251 253
252 * `plugin_end_zone`: after displaying the template content. 254- `plugin_end_zone`: after displaying the template content.
253 255
254![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png) 256![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png)
255 257
@@ -263,7 +265,7 @@ Allow to add fields in the form, or display elements.
263 265
264`$data` is an array containing: 266`$data` is an array containing:
265 267
266 * All templates data. 268- All templates data.
267 269
268##### Template placeholders 270##### Template placeholders
269 271
@@ -271,7 +273,7 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
271 273
272List of placeholders: 274List of placeholders:
273 275
274 * `edit_link_plugin`: after tags field. 276- `edit_link_plugin`: after tags field.
275 277
276![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png) 278![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png)
277 279
@@ -285,7 +287,7 @@ Allow to add content at the end of the page.
285 287
286`$data` is an array containing: 288`$data` is an array containing:
287 289
288 * All templates data. 290- All templates data.
289 291
290##### Template placeholders 292##### Template placeholders
291 293
@@ -293,7 +295,7 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
293 295
294List of placeholders: 296List of placeholders:
295 297
296 * `tools_plugin`: at the end of the page. 298- `tools_plugin`: at the end of the page.
297 299
298![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png) 300![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png)
299 301
@@ -307,8 +309,8 @@ Allow to add content at the top and bottom of the page.
307 309
308`$data` is an array containing: 310`$data` is an array containing:
309 311
310 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 312- `_LOGGEDIN_`: true if user is logged in, false otherwise.
311 * All templates data. 313- All templates data.
312 314
313##### Template placeholders 315##### Template placeholders
314 316
@@ -316,9 +318,8 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
316 318
317List of placeholders: 319List of placeholders:
318 320
319 * `plugin_start_zone`: before displaying the template content. 321- `plugin_start_zone`: before displaying the template content.
320 322- `plugin_end_zone`: after displaying the template content.
321 * `plugin_end_zone`: after displaying the template content.
322 323
323![plugin_start_end_zone_example](http://i.imgur.com/tVTQFER.png) 324![plugin_start_end_zone_example](http://i.imgur.com/tVTQFER.png)
324 325
@@ -332,8 +333,8 @@ Allow to add content at the top and bottom of the page.
332 333
333`$data` is an array containing: 334`$data` is an array containing:
334 335
335 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 336- `_LOGGEDIN_`: true if user is logged in, false otherwise.
336 * All templates data. 337- All templates data.
337 338
338##### Template placeholders 339##### Template placeholders
339 340
@@ -341,13 +342,12 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
341 342
342List of placeholders: 343List of placeholders:
343 344
344 * `plugin_start_zone`: before displaying the template content. 345- `plugin_start_zone`: before displaying the template content.
345 346- `plugin_end_zone`: after displaying the template content.
346 * `plugin_end_zone`: after displaying the template content.
347 347
348For each tag, the following placeholder can be used: 348For each tag, the following placeholder can be used:
349 349
350 * `tag_plugin`: after each tag 350- `tag_plugin`: after each tag
351 351
352![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png) 352![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png)
353 353
@@ -362,8 +362,8 @@ Allow to add content at the top and bottom of the page.
362 362
363`$data` is an array containing: 363`$data` is an array containing:
364 364
365 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 365- `_LOGGEDIN_`: true if user is logged in, false otherwise.
366 * All templates data. 366- All templates data.
367 367
368##### Template placeholders 368##### Template placeholders
369 369
@@ -371,13 +371,12 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
371 371
372List of placeholders: 372List of placeholders:
373 373
374 * `plugin_start_zone`: before displaying the template content. 374- `plugin_start_zone`: before displaying the template content.
375 375- `plugin_end_zone`: after displaying the template content.
376 * `plugin_end_zone`: after displaying the template content.
377 376
378For each tag, the following placeholder can be used: 377For each tag, the following placeholder can be used:
379 378
380 * `tag_plugin`: after each tag 379- `tag_plugin`: after each tag
381 380
382#### render_daily 381#### render_daily
383 382
@@ -389,8 +388,8 @@ Allow to add content at the top and bottom of the page, the bottom of each link
389 388
390`$data` is an array containing: 389`$data` is an array containing:
391 390
392 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 391- `_LOGGEDIN_`: true if user is logged in, false otherwise.
393 * All templates data, including links. 392- All templates data, including links.
394 393
395##### Template placeholders 394##### Template placeholders
396 395
@@ -398,13 +397,12 @@ Items can be displayed in templates by adding an entry in `$data['<placeholder>'
398 397
399List of placeholders: 398List of placeholders:
400 399
401 * `link_plugin`: used at bottom of each link. 400- `link_plugin`: used at bottom of each link.
402 401
403![link_plugin_example](http://i.imgur.com/hzhMfSZ.png) 402![link_plugin_example](http://i.imgur.com/hzhMfSZ.png)
404 403
405 * `plugin_start_zone`: before displaying the template content. 404- `plugin_start_zone`: before displaying the template content.
406 405- `plugin_end_zone`: after displaying the template content.
407 * `plugin_end_zone`: after displaying the template content.
408 406
409#### render_feed 407#### render_feed
410 408
@@ -416,9 +414,9 @@ Allow to add tags in the feed, either in the header or for each items. Items (li
416 414
417`$data` is an array containing: 415`$data` is an array containing:
418 416
419 * `_LOGGEDIN_`: true if user is logged in, false otherwise. 417- `_LOGGEDIN_`: true if user is logged in, false otherwise.
420 * `_PAGE_`: containing either `rss` or `atom`. 418- `_PAGE_`: containing either `rss` or `atom`.
421 * All templates data, including links. 419- All templates data, including links.
422 420
423##### Template placeholders 421##### Template placeholders
424 422
@@ -426,11 +424,11 @@ Tags can be added in feeds by adding an entry in `$data['<placeholder>']` array.
426 424
427List of placeholders: 425List of placeholders:
428 426
429 * `feed_plugins_header`: used as a header tag in the feed. 427- `feed_plugins_header`: used as a header tag in the feed.
430 428
431For each links: 429For each links:
432 430
433 * `feed_plugins`: additional tag for every link entry. 431- `feed_plugins`: additional tag for every link entry.
434 432
435#### save_link 433#### save_link
436 434
@@ -442,15 +440,15 @@ Allow to alter the link being saved in the datastore.
442 440
443`$data` is an array containing the link being saved: 441`$data` is an array containing the link being saved:
444 442
445 * id 443- id
446 * title 444- title
447 * url 445- url
448 * shorturl 446- shorturl
449 * description 447- description
450 * private 448- private
451 * tags 449- tags
452 * created 450- created
453 * updated 451- updated
454 452
455 453
456#### delete_link 454#### delete_link
@@ -463,15 +461,15 @@ Allow to execute any action before the link is actually removed from the datasto
463 461
464`$data` is an array containing the link being saved: 462`$data` is an array containing the link being saved:
465 463
466 * id 464- id
467 * title 465- title
468 * url 466- url
469 * shorturl 467- shorturl
470 * description 468- description
471 * private 469- private
472 * tags 470- tags
473 * created 471- created
474 * updated 472- updated
475 473
476## Guide for template designer 474## Guide for template designer
477 475
@@ -485,9 +483,9 @@ Use the default one as an example.
485 483
486Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if: 484Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if:
487 485
488 * you're using a table. 486- you're using a table.
489 * you call orderUp() and orderUp() onclick on arrows. 487- you call orderUp() and orderUp() onclick on arrows.
490 * you add data-line and data-order to your rows. 488- you add data-line and data-order to your rows.
491 489
492Otherwise, you can use your own JS as long as this field is send by the form: 490Otherwise, you can use your own JS as long as this field is send by the form:
493 491