plugins/demo_plugin/demo_plugin.php

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