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