plugins/demo_plugin/demo_plugin.php

   1 <?php
   2 /**
   3  * Demo Plugin.
   4  *
   5  * This plugin tries to completely cover Shaarli's plugin API.
   6  * Can be used by plugin developers to make their own plugin.
   7  */
   8
   9 /*
  10  * RENDER HEADER, INCLUDES, FOOTER
  11  *
  12  * Those hooks are called at every page rendering.
  13  * You can filter its execution by checking _PAGE_ value
  14  * and check user status with _LOGGEDIN_.
  15  */
  16
  17 use Shaarli\Config\ConfigManager;
  18 use Shaarli\Plugin\PluginManager;
  19 use Shaarli\Render\TemplatePage;
  20
  21 /**
  22  * In the footer hook, there is a working example of a translation extension for Shaarli.
  23  *
  24  * The extension must be attached to a new translation domain (i.e. NOT 'shaarli').
  25  * Use case: any custom theme or non official plugin can use the translation system.
  26  *
  27  * See the documentation for more information.
  28  */
  29 const EXT_TRANSLATION_DOMAIN = 'demo';
  30
  31 /*
  32  * This is not necessary, but it's easier if you don't want Poedit to mix up your translations.
  33  */
  34 function demo_plugin_t($text, $nText = '', $nb = 1)
  35 {
  36     return t($text, $nText, $nb, EXT_TRANSLATION_DOMAIN);
  37 }
  38
  39 /**
  40  * Initialization function.
  41  * It will be called when the plugin is loaded.
  42  * This function can be used to return a list of initialization errors.
  43  *
  44  * @param $conf ConfigManager instance.
  45  *
  46  * @return array List of errors (optional).
  47  */
  48 function demo_plugin_init($conf)
  49 {
  50     $conf->get('toto', 'nope');
  51
  52     if (! $conf->exists('translation.extensions.demo')) {
  53         // Custom translation with the domain 'demo'
  54         $conf->set('translation.extensions.demo', 'plugins/demo_plugin/languages/');
  55         $conf->write(true);
  56     }
  57
  58     $errors[] = 'This a demo init error.';
  59     return $errors;
  60 }
  61
  62 /**
  63  * Hook render_header.
  64  * Executed on every page render.
  65  *
  66  * Template placeholders:
  67  *   - buttons_toolbar
  68  *   - fields_toolbar
  69  *
  70  * @param array $data data passed to plugin
  71  *
  72  * @return array altered $data.
  73  */
  74 function hook_demo_plugin_render_header($data)
  75 {
  76     // Only execute when linklist is rendered.
  77     if ($data['_PAGE_'] == TemplatePage::LINKLIST) {
  78         // If loggedin
  79         if ($data['_LOGGEDIN_'] === true) {
  80             /*
  81              * Links in toolbar:
  82              * A link is an array of its attributes (key="value"),
  83              * and a mandatory `html` key, which contains its value.
  84              */
  85             $button = array(
  86                 'attr' => array (
  87                     'href' => '#',
  88                     'class' => 'mybutton',
  89                     'title' => 'hover me',
  90                 ),
  91                 'html' => 'DEMO buttons toolbar',
  92             );
  93             $data['buttons_toolbar'][] = $button;
  94         }
  95
  96         /*
  97          * Add additional input fields in the tools.
  98          * A field is an array containing:
  99          *  [
 100          *      'form-attribute-1' => 'form attribute 1 value',
 101          *      'form-attribute-2' => 'form attribute 2 value',
 102          *      'inputs' => [
 103          *          [
 104          *              'input-1-attribute-1 => 'input 1 attribute 1 value',
 105          *              'input-1-attribute-2 => 'input 1 attribute 2 value',
 106          *          ],
 107          *          [
 108          *              'input-2-attribute-1 => 'input 2 attribute 1 value',
 109          *          ],
 110          *      ],
 111          *  ]
 112          * This example renders as:
 113          * <form form-attribute-1="form attribute 1 value" form-attribute-2="form attribute 2 value">
 114          *   <input input-1-attribute-1="input 1 attribute 1 value" input-1-attribute-2="input 1 attribute 2 value">
 115          *   <input input-2-attribute-1="input 2 attribute 1 value">
 116          * </form>
 117          */
 118         $form = array(
 119             'attr' => array(
 120                 'method' => 'GET',
 121                 'action' => $data['_BASE_PATH_'] . '/',
 122                 'class' => 'addform',
 123             ),
 124             'inputs' => array(
 125                 array(
 126                     'type' => 'text',
 127                     'name' => 'demo',
 128                     'placeholder' => 'demo',
 129                 )
 130             )
 131         );
 132         $data['fields_toolbar'][] = $form;
 133     }
 134     // Another button always displayed
 135     $button = array(
 136         'attr' => array(
 137             'href' => '#',
 138         ),
 139         'html' => 'Demo',
 140     );
 141     $data['buttons_toolbar'][] = $button;
 142
 143     return $data;
 144 }
 145
 146 /**
 147  * Hook render_includes.
 148  * Executed on every page render.
 149  *
 150  * Template placeholders:
 151  *   - css_files
 152  *
 153  * Data:
 154  *   - _PAGE_: current page
 155  *   - _LOGGEDIN_: true/false
 156  *
 157  * @param array $data data passed to plugin
 158  *
 159  * @return array altered $data.
 160  */
 161 function hook_demo_plugin_render_includes($data)
 162 {
 163     // List of plugin's CSS files.
 164     // Note that you just need to specify CSS path.
 165     $data['css_files'][] = PluginManager::$PLUGINS_PATH . '/demo_plugin/custom_demo.css';
 166
 167     return $data;
 168 }
 169
 170 /**
 171  * Hook render_footer.
 172  * Executed on every page render.
 173  *
 174  * Template placeholders:
 175  *   - text
 176  *   - endofpage
 177  *   - js_files
 178  *
 179  * Data:
 180  *   - _PAGE_: current page
 181  *   - _LOGGEDIN_: true/false
 182  *
 183  * @param array $data data passed to plugin
 184  *
 185  * @return array altered $data.
 186  */
 187 function hook_demo_plugin_render_footer($data)
 188 {
 189     // Footer text
 190     $data['text'][] = '<br>'. demo_plugin_t('Shaarli is now enhanced by the awesome demo_plugin.');
 191
 192     // Free elements at the end of the page.
 193     $data['endofpage'][] = '<marquee id="demo_marquee">' .
 194             'DEMO: it\'s 1999 all over again!' .
 195         '</marquee>';
 196
 197     // List of plugin's JS files.
 198     // Note that you just need to specify CSS path.
 199     $data['js_files'][] = PluginManager::$PLUGINS_PATH . '/demo_plugin/demo_plugin.js';
 200
 201     return $data;
 202 }
 203
 204 /*
 205  * SPECIFIC PAGES
 206  */
 207
 208 /**
 209  * Hook render_linklist.
 210  *
 211  * Template placeholders:
 212  *   - action_plugin: next to 'private only' button.
 213  *   - plugin_start_zone: page start
 214  *   - plugin_end_zone: page end
 215  *   - link_plugin: icons below each links.
 216  *
 217  * Data:
 218  *   - _LOGGEDIN_: true/false
 219  *
 220  * @param array $data data passed to plugin
 221  *
 222  * @return array altered $data.
 223  */
 224 function hook_demo_plugin_render_linklist($data)
 225 {
 226     /*
 227      * Action links (action_plugin):
 228      * A link is an array of its attributes (key="value"),
 229      * and a mandatory `html` key, which contains its value.
 230      * It's also recommended to add key 'on' or 'off' for theme rendering.
 231      */
 232     $action = array(
 233         'attr' => array(
 234             'href' => '?up',
 235             'title' => 'Uppercase!',
 236         ),
 237         'html' => '←',
 238     );
 239
 240     if (isset($_GET['up'])) {
 241         // Manipulate link data
 242         foreach ($data['links'] as &$value) {
 243             $value['description'] = strtoupper($value['description']);
 244             $value['title'] = strtoupper($value['title']);
 245         }
 246         $action['on'] = true;
 247     } else {
 248         $action['off'] = true;
 249     }
 250     $data['action_plugin'][] = $action;
 251
 252     // link_plugin (for each link)
 253     foreach ($data['links'] as &$value) {
 254         $value['link_plugin'][] = ' DEMO \o/';
 255     }
 256
 257     // plugin_start_zone
 258     $data['plugin_start_zone'][] = '<center>BEFORE</center>';
 259     // plugin_start_zone
 260     $data['plugin_end_zone'][] = '<center>AFTER</center>';
 261
 262     return $data;
 263 }
 264
 265 /**
 266  * Hook render_editlink.
 267  *
 268  * Template placeholders:
 269  *   - field_plugin: add link fields after tags.
 270  *
 271  * @param array $data data passed to plugin
 272  *
 273  * @return array altered $data.
 274  */
 275 function hook_demo_plugin_render_editlink($data)
 276 {
 277     // Load HTML into a string
 278     $html = file_get_contents(PluginManager::$PLUGINS_PATH .'/demo_plugin/field.html');
 279
 280     // Replace value in HTML if it exists in $data
 281     if (!empty($data['link']['stuff'])) {
 282         $html = sprintf($html, $data['link']['stuff']);
 283     } else {
 284         $html = sprintf($html, '');
 285     }
 286
 287     // field_plugin
 288     $data['edit_link_plugin'][] = $html;
 289
 290     return $data;
 291 }
 292
 293 /**
 294  * Hook render_tools.
 295  *
 296  * Template placeholders:
 297  *   - tools_plugin: after other tools.
 298  *
 299  * @param array $data data passed to plugin
 300  *
 301  * @return array altered $data.
 302  */
 303 function hook_demo_plugin_render_tools($data)
 304 {
 305     // field_plugin
 306     $data['tools_plugin'][] = 'tools_plugin';
 307
 308     return $data;
 309 }
 310
 311 /**
 312  * Hook render_picwall.
 313  *
 314  * Template placeholders:
 315  *   - plugin_start_zone: page start.
 316  *   - plugin_end_zone: page end.
 317  *
 318  * Data:
 319  *   - _LOGGEDIN_: true/false
 320  *
 321  * @param array $data data passed to plugin
 322  *
 323  * @return array altered $data.
 324  */
 325 function hook_demo_plugin_render_picwall($data)
 326 {
 327     $data['plugin_start_zone'][] = '<center>BEFORE</center>';
 328     $data['plugin_end_zone'][] = '<center>AFTER</center>';
 329
 330     return $data;
 331 }
 332
 333 /**
 334  * Hook render_tagcloud.
 335  *
 336  * Template placeholders:
 337  *   - plugin_start_zone: page start.
 338  *   - plugin_end_zone: page end.
 339  *
 340  * Data:
 341  *   - _LOGGEDIN_: true/false
 342  *
 343  * @param array $data data passed to plugin
 344  *
 345  * @return array altered $data.
 346  */
 347 function hook_demo_plugin_render_tagcloud($data)
 348 {
 349     $data['plugin_start_zone'][] = '<center>BEFORE</center>';
 350     $data['plugin_end_zone'][] = '<center>AFTER</center>';
 351
 352     return $data;
 353 }
 354
 355 /**
 356  * Hook render_daily.
 357  *
 358  * Template placeholders:
 359  *   - plugin_start_zone: page start.
 360  *   - plugin_end_zone: page end.
 361  *
 362  * Data:
 363  *   - _LOGGEDIN_: true/false
 364  *
 365  * @param array $data data passed to plugin
 366  *
 367  * @return array altered $data.
 368  */
 369 function hook_demo_plugin_render_daily($data)
 370 {
 371     $data['plugin_start_zone'][] = '<center>BEFORE</center>';
 372     $data['plugin_end_zone'][] = '<center>AFTER</center>';
 373
 374
 375     // Manipulate columns data
 376     foreach ($data['linksToDisplay'] as &$value) {
 377         $value['formatedDescription'] .= ' ಠ_ಠ';
 378     }
 379
 380     // Add plugin content at the end of each link
 381     foreach ($data['linksToDisplay'] as &$value) {
 382         $value['link_plugin'][] = 'DEMO';
 383     }
 384
 385     return $data;
 386 }
 387
 388 /*
 389  * DATA SAVING HOOK.
 390  */
 391
 392 /**
 393  * Hook savelink.
 394  *
 395  * Triggered when a link is save (new or edit).
 396  * All new links now contain a 'stuff' value.
 397  *
 398  * @param array $data contains the new link data.
 399  *
 400  * @return array altered $data.
 401  */
 402 function hook_demo_plugin_save_link($data)
 403 {
 404
 405     // Save stuff added in editlink field
 406     if (!empty($_POST['lf_stuff'])) {
 407         $data['stuff'] = escape($_POST['lf_stuff']);
 408     }
 409
 410     return $data;
 411 }
 412
 413 /**
 414  * Hook delete_link.
 415  *
 416  * Triggered when a link is deleted.
 417  *
 418  * @param array $data contains the link to be deleted.
 419  *
 420  * @return array altered data.
 421  */
 422 function hook_demo_plugin_delete_link($data)
 423 {
 424     if (strpos($data['url'], 'youtube.com') !== false) {
 425         exit('You can not delete a YouTube link. Don\'t ask.');
 426     }
 427 }
 428
 429 /**
 430  * Execute render_feed hook.
 431  * Called with ATOM and RSS feed.
 432  *
 433  * Special data keys:
 434  *   - _PAGE_: current page
 435  *   - _LOGGEDIN_: true/false
 436  *
 437  * @param array $data data passed to plugin
 438  *
 439  * @return array altered $data.
 440  */
 441 function hook_demo_plugin_render_feed($data)
 442 {
 443     foreach ($data['links'] as &$link) {
 444         if ($data['_PAGE_'] == TemplatePage::FEED_ATOM) {
 445             $link['description'] .= ' - ATOM Feed' ;
 446         } elseif ($data['_PAGE_'] == TemplatePage::FEED_RSS) {
 447             $link['description'] .= ' - RSS Feed';
 448         }
 449     }
 450     return $data;
 451 }
 452
 453 /**
 454  * When plugin parameters are saved.
 455  *
 456  * @param array $data $_POST array
 457  *
 458  * @return array Updated $_POST array
 459  */
 460 function hook_demo_plugin_save_plugin_parameters($data)
 461 {
 462     // Here we edit the provided value.
 463     // This hook can also be used to generate config files, etc.
 464     if (! empty($data['DEMO_PLUGIN_PARAMETER']) && ! endsWith($data['DEMO_PLUGIN_PARAMETER'], '_SUFFIX')) {
 465         $data['DEMO_PLUGIN_PARAMETER'] .= '_SUFFIX';
 466     }
 467
 468     return $data;
 469 }
 470
 471 /**
 472  * This function is never called, but contains translation calls for GNU gettext extraction.
 473  */
 474 function demo_dummy_translation()
 475 {
 476     // meta
 477     t('A demo plugin covering all use cases for template designers and plugin developers.');
 478     t('This is a parameter dedicated to the demo plugin. It\'ll be suffixed.');
 479     t('Other demo parameter');
 480 }