plugins/demo_plugin/demo_plugin.php

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