doc/Plugin-System.md

   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
  14 In `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
  20 Full 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
  31 Plugin 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
  45 The 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
  53 First, chose a plugin name, such as `demo_plugin`.
  54
  55 Under `plugin` folder, create a folder named with your plugin name. Then create a <plugin_name>.php file in that folder.
  56
  57 You 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
  68 A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.
  69
  70 These functions need to be named with this pattern:
  71
  72 ```
  73 hook_<plugin_name>_<hook_name>
  74 ```
  75
  76 For exemple, if my plugin want to add data to the header, this function is needed:
  77
  78     hook_demo_plugin_render_header()
  79
  80 If 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
  86 Every 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
  94 Template placeholders are displayed in template in specific places.
  95
  96 RainTPL displays every element contained in the placeholder's array. These element can be added by plugins.
  97
  98 For 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
 103 array_push($data['top_placeholder'], 'My', 'content');[](.html)
 104
 105 return $data;
 106 ```
 107
 108 #### Data manipulation
 109
 110 When a page is displayed, every variable send to the template engine is passed to plugins before that in `$data`.
 111
 112 The data contained by this array can be altered before template rendering.
 113
 114 For exemple, in linklist, it is possible to alter every title:
 115
 116 ```php
 117 // mind the reference if you want $data to be altered
 118 foreach ($data['links'] as &$value) {[](.html)
 119     // String reverse every title.
 120     $value['title'] = strrev($value['title']);[](.html)
 121 }
 122
 123 return $data;
 124 ```
 125
 126 ### It's not working!
 127
 128 Use `demo_plugin` as a functional example. It covers most of the plugin system features.
 129
 130 If 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
 150 Triggered on every page.
 151
 152 Allow 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
 163 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
 164
 165 List 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
 179 Triggered on every page.
 180
 181 Allow 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
 192 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
 193
 194 List 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
 202 Triggered on every page.
 203
 204 Allow 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
 215 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
 216
 217 List 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
 229 Triggered when `linklist` is displayed (list of links, permalink, search, tag filtered, etc.).
 230
 231 It 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
 242 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
 243
 244 List 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
 264 Triggered when the link edition form is displayed.
 265
 266 Allow 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
 276 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
 277
 278 List 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
 286 Triggered when the "tools" page is displayed.
 287
 288 Allow 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
 298 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
 299
 300 List 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
 308 Triggered when picwall is displayed.
 309
 310 Allow 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
 321 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
 322
 323 List 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
 333 Triggered when tagcloud is displayed.
 334
 335 Allow 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
 346 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
 347
 348 List 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
 358 Triggered when tagcloud is displayed.
 359
 360 Allow 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
 371 Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.[](.html)
 372
 373 List 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
 385 Triggered when a link is save (new link or edit).
 386
 387 Allow 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
 404 In order to make plugins work with every custom themes, you need to add variable placeholder in your templates.
 405
 406 It's a RainTPL loop like this:
 407
 408     {loop="$plugin_variable"}
 409         {$value}
 410     {/loop}
 411
 412 You should enable `demo_plugin` for testing purpose, since it uses every placeholder available.
 413
 414 ### List of placeholders
 415
 416 **page.header.html**
 417
 418 At the end of the menu:
 419
 420     {loop="$plugins_header.buttons_toolbar"}
 421         {$value}
 422     {/loop}
 423
 424 **includes.html**
 425
 426 At 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
 436 At the end of your footer notes:
 437
 438 ```html
 439 {loop="$plugins_footer.text"}
 440      {$value}
 441 {/loop}
 442 ```
 443
 444 At 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
 454 After search fields:
 455
 456 ```html
 457 {loop="$plugins_header.fields_toolbar"}
 458      {$value}
 459 {/loop}
 460 ```
 461
 462 Before displaying the link list (after paging):
 463
 464 ```html
 465 {loop="$plugin_start_zone"}
 466      {$value}
 467 {/loop}
 468 ```
 469
 470 For every links (icons):
 471
 472 ```html
 473 {loop="$value.link_plugin"}
 474     <span>{$value}</span>
 475 {/loop}
 476 ```
 477
 478 Before end paging:
 479
 480 ```html
 481 {loop="$plugin_end_zone"}
 482      {$value}
 483 {/loop}
 484 ```
 485
 486 **linklist.paging.html**
 487
 488 After the "private only" icon:
 489
 490 ```html
 491 {loop="$action_plugin"}
 492      {$value}
 493 {/loop}
 494 ```
 495
 496 **editlink.html**
 497
 498 After tags field:
 499
 500 ```html
 501 {loop="$edit_link_plugin"}
 502      {$value}
 503 {/loop}
 504 ```
 505
 506 **tools.html**
 507
 508 After the last tool:
 509
 510 ```html
 511 {loop="$tools_plugin"}
 512      {$value}
 513 {/loop}
 514 ```
 515
 516 **picwall.html**
 517
 518 Top:
 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
 528 Bottom:
 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
 540 Top:
 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
 550 Bottom:
 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
 562 Top:
 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
 572 After every link:
 573
 574 ```html
 575 <div class="dailyEntryFooter">
 576      {loop="$link.link_plugin"}
 577           {$value}
 578      {/loop}
 579 </div>
 580 ```
 581
 582 Bottom:
 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 ```