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