6 * This plugin tries to completely cover Shaarli's plugin API.
7 * Can be used by plugin developers to make their own plugin.
10 require_once __DIR__
. '/DemoPluginController.php';
13 * RENDER HEADER, INCLUDES, FOOTER
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_.
20 use Shaarli\Config\ConfigManager
;
21 use Shaarli\Plugin\PluginManager
;
22 use Shaarli\Render\TemplatePage
;
25 * In the footer hook, there is a working example of a translation extension for Shaarli.
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.
30 * See the documentation for more information.
32 const EXT_TRANSLATION_DOMAIN
= 'demo';
35 * This is not necessary, but it's easier if you don't want Poedit to mix up your translations.
37 function demo_plugin_t($text, $nText = '', $nb = 1)
39 return t($text, $nText, $nb, EXT_TRANSLATION_DOMAIN
);
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.
47 * @param $conf ConfigManager instance.
49 * @return array List of errors (optional).
51 function demo_plugin_init($conf)
53 $conf->get('toto', 'nope');
55 if (! $conf->exists('translation.extensions.demo')) {
56 // Custom translation with the domain 'demo'
57 $conf->set('translation.extensions.demo', 'plugins/demo_plugin/languages/');
61 $errors[] = 'This a demo init error.';
65 function demo_plugin_register_routes(): array
71 'callable' => 'Shaarli\DemoPlugin\DemoPluginController:index',
78 * Executed on every page render.
80 * Template placeholders:
84 * @param array $data data passed to plugin
86 * @return array altered $data.
88 function hook_demo_plugin_render_header($data)
90 // Only execute when linklist is rendered.
91 if ($data['_PAGE_'] == TemplatePage
::LINKLIST
) {
93 if ($data['_LOGGEDIN_'] === true) {
96 * A link is an array of its attributes (key="value"),
97 * and a mandatory `html` key, which contains its value.
102 'class' => 'mybutton',
103 'title' => 'hover me',
105 'html' => 'DEMO buttons toolbar',
107 $data['buttons_toolbar'][] = $button;
111 * Add additional input fields in the tools.
112 * A field is an array containing:
114 * 'form-attribute-1' => 'form attribute 1 value',
115 * 'form-attribute-2' => 'form attribute 2 value',
118 * 'input-1-attribute-1 => 'input 1 attribute 1 value',
119 * 'input-1-attribute-2 => 'input 1 attribute 2 value',
122 * 'input-2-attribute-1 => 'input 2 attribute 1 value',
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">
135 'action' => $data['_BASE_PATH_'] . '/',
136 'class' => 'addform',
142 'placeholder' => 'demo',
146 $data['fields_toolbar'][] = $form;
148 // Another button always displayed
155 $data['buttons_toolbar'][] = $button;
161 * Hook render_includes.
162 * Executed on every page render.
164 * Template placeholders:
168 * - _PAGE_: current page
169 * - _LOGGEDIN_: true/false
171 * @param array $data data passed to plugin
173 * @return array altered $data.
175 function hook_demo_plugin_render_includes($data)
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';
185 * Hook render_footer.
186 * Executed on every page render.
188 * Template placeholders:
194 * - _PAGE_: current page
195 * - _LOGGEDIN_: true/false
197 * @param array $data data passed to plugin
199 * @return array altered $data.
201 function hook_demo_plugin_render_footer($data)
204 $data['text'][] = '<br>' . demo_plugin_t('Shaarli is now enhanced by the awesome demo_plugin.');
206 // Free elements at the end of the page.
207 $data['endofpage'][] = '<marquee id="demo_marquee">' .
208 'DEMO: it\'s 1999 all over again!' .
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';
223 * Hook render_linklist.
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.
232 * - _LOGGEDIN_: true/false
234 * @param array $data data passed to plugin
236 * @return array altered $data.
238 function hook_demo_plugin_render_linklist($data)
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.
249 'title' => 'Uppercase!',
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']);
260 $action['on'] = true;
262 $action['off'] = true;
264 $data['action_plugin'][] = $action;
266 // link_plugin (for each link)
267 foreach ($data['links'] as &$value) {
268 $value['link_plugin'][] = ' DEMO \o/';
272 $data['plugin_start_zone'][] = '<center>BEFORE</center>';
274 $data['plugin_end_zone'][] = '<center>AFTER</center>';
280 * Hook render_editlink.
282 * Template placeholders:
283 * - field_plugin: add link fields after tags.
285 * @param array $data data passed to plugin
287 * @return array altered $data.
289 function hook_demo_plugin_render_editlink($data)
291 // Load HTML into a string
292 $html = file_get_contents(PluginManager
::$PLUGINS_PATH . '/demo_plugin/field.html');
294 // Replace value in HTML if it exists in $data
295 if (!empty($data['link']['stuff'])) {
296 $html = sprintf($html, $data['link']['stuff']);
298 $html = sprintf($html, '');
302 $data['edit_link_plugin'][] = $html;
310 * Template placeholders:
311 * - tools_plugin: after other tools.
313 * @param array $data data passed to plugin
315 * @return array altered $data.
317 function hook_demo_plugin_render_tools($data)
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>
330 * Hook render_picwall.
332 * Template placeholders:
333 * - plugin_start_zone: page start.
334 * - plugin_end_zone: page end.
337 * - _LOGGEDIN_: true/false
339 * @param array $data data passed to plugin
341 * @return array altered $data.
343 function hook_demo_plugin_render_picwall($data)
345 $data['plugin_start_zone'][] = '<center>BEFORE</center>';
346 $data['plugin_end_zone'][] = '<center>AFTER</center>';
352 * Hook render_tagcloud.
354 * Template placeholders:
355 * - plugin_start_zone: page start.
356 * - plugin_end_zone: page end.
359 * - _LOGGEDIN_: true/false
361 * @param array $data data passed to plugin
363 * @return array altered $data.
365 function hook_demo_plugin_render_tagcloud($data)
367 $data['plugin_start_zone'][] = '<center>BEFORE</center>';
368 $data['plugin_end_zone'][] = '<center>AFTER</center>';
376 * Template placeholders:
377 * - plugin_start_zone: page start.
378 * - plugin_end_zone: page end.
381 * - _LOGGEDIN_: true/false
383 * @param array $data data passed to plugin
385 * @return array altered $data.
387 function hook_demo_plugin_render_daily($data)
389 $data['plugin_start_zone'][] = '<center>BEFORE</center>';
390 $data['plugin_end_zone'][] = '<center>AFTER</center>';
393 // Manipulate columns data
394 foreach ($data['linksToDisplay'] as &$value) {
395 $value['formatedDescription'] .= ' ಠ_ಠ';
398 // Add plugin content at the end of each link
399 foreach ($data['linksToDisplay'] as &$value) {
400 $value['link_plugin'][] = 'DEMO';
413 * Triggered when a link is save (new or edit).
414 * All new links now contain a 'stuff' value.
416 * @param array $data contains the new link data.
418 * @return array altered $data.
420 function hook_demo_plugin_save_link($data)
423 // Save stuff added in editlink field
424 if (!empty($_POST['lf_stuff'])) {
425 $data['stuff'] = escape($_POST['lf_stuff']);
434 * Triggered when a link is deleted.
436 * @param array $data contains the link to be deleted.
438 * @return array altered data.
440 function hook_demo_plugin_delete_link($data)
442 if (strpos($data['url'], 'youtube.com') !== false) {
443 exit('You can not delete a YouTube link. Don\'t ask.');
448 * Execute render_feed hook.
449 * Called with ATOM and RSS feed.
452 * - _PAGE_: current page
453 * - _LOGGEDIN_: true/false
455 * @param array $data data passed to plugin
457 * @return array altered $data.
459 function hook_demo_plugin_render_feed($data)
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';
472 * When plugin parameters are saved.
474 * @param array $data $_POST array
476 * @return array Updated $_POST array
478 function hook_demo_plugin_save_plugin_parameters($data)
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';
490 * This function is never called, but contains translation calls for GNU gettext extraction.
492 function demo_dummy_translation()
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');