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