5 * This plugin try to cover Shaarli's plugin API entirely.
6 * Can be used by plugin developper to make their own.
10 * RENDER HEADER, INCLUDES, FOOTER
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_.
17 use Shaarli\Config\ConfigManager
;
18 use Shaarli\Plugin\PluginManager
;
22 * In the footer hook, there is a working example of a translation extension for Shaarli.
24 * The extension must be attached to a new translation domain (i.e. NOT 'shaarli').
25 * Use case: any custom theme or non official plugin can use the translation system.
27 * See the documentation for more information.
29 const EXT_TRANSLATION_DOMAIN
= 'demo';
32 * This is not necessary, but it's easier if you don't want Poedit to mix up your translations.
34 function demo_plugin_t($text, $nText = '', $nb = 1)
36 return t($text, $nText, $nb, EXT_TRANSLATION_DOMAIN
);
40 * Initialization function.
41 * It will be called when the plugin is loaded.
42 * This function can be used to return a list of initialization errors.
44 * @param $conf ConfigManager instance.
46 * @return array List of errors (optional).
48 function demo_plugin_init($conf)
50 $conf->get('toto', 'nope');
52 if (! $conf->exists('translation.extensions.demo')) {
53 // Custom translation with the domain 'demo'
54 $conf->set('translation.extensions.demo', 'plugins/demo_plugin/languages/');
58 $errors[] = 'This a demo init error.';
64 * Executed on every page redering.
66 * Template placeholders:
70 * @param array $data data passed to plugin
72 * @return array altered $data.
74 function hook_demo_plugin_render_header($data)
76 // Only execute when linklist is rendered.
77 if ($data['_PAGE_'] == Router
::$PAGE_LINKLIST) {
79 if ($data['_LOGGEDIN_'] === true) {
82 * A link is an array of its attributes (key="value"),
83 * and a mandatory `html` key, which contains its value.
88 'class' => 'mybutton',
89 'title' => 'hover me',
91 'html' => 'DEMO buttons toolbar',
93 $data['buttons_toolbar'][] = $button;
97 * Add additional input fields in the tools.
98 * A field is an array containing:
100 * 'form-attribute-1' => 'form attribute 1 value',
101 * 'form-attribute-2' => 'form attribute 2 value',
104 * 'input-1-attribute-1 => 'input 1 attribute 1 value',
105 * 'input-1-attribute-2 => 'input 1 attribute 2 value',
108 * 'input-2-attribute-1 => 'input 2 attribute 1 value',
112 * This example renders as:
113 * <form form-attribute-1="form attribute 1 value" form-attribute-2="form attribute 2 value">
114 * <input input-1-attribute-1="input 1 attribute 1 value" input-1-attribute-2="input 1 attribute 2 value">
115 * <input input-2-attribute-1="input 2 attribute 1 value">
122 'class' => 'addform',
128 'placeholder' => 'demo',
132 $data['fields_toolbar'][] = $form;
134 // Another button always displayed
141 $data['buttons_toolbar'][] = $button;
147 * Hook render_includes.
148 * Executed on every page redering.
150 * Template placeholders:
154 * - _PAGE_: current page
155 * - _LOGGEDIN_: true/false
157 * @param array $data data passed to plugin
159 * @return array altered $data.
161 function hook_demo_plugin_render_includes($data)
163 // List of plugin's CSS files.
164 // Note that you just need to specify CSS path.
165 $data['css_files'][] = PluginManager
::$PLUGINS_PATH . '/demo_plugin/custom_demo.css';
171 * Hook render_footer.
172 * Executed on every page redering.
174 * Template placeholders:
180 * - _PAGE_: current page
181 * - _LOGGEDIN_: true/false
183 * @param array $data data passed to plugin
185 * @return array altered $data.
187 function hook_demo_plugin_render_footer($data)
190 $data['text'][] = '<br>'. demo_plugin_t('Shaarli is now enhanced by the awesome demo_plugin.');
192 // Free elements at the end of the page.
193 $data['endofpage'][] = '<marquee id="demo_marquee">' .
194 'DEMO: it\'s 1999 all over again!' .
197 // List of plugin's JS files.
198 // Note that you just need to specify CSS path.
199 $data['js_files'][] = PluginManager
::$PLUGINS_PATH . '/demo_plugin/demo_plugin.js';
209 * Hook render_linklist.
211 * Template placeholders:
212 * - action_plugin: next to 'private only' button.
213 * - plugin_start_zone: page start
214 * - plugin_end_zone: page end
215 * - link_plugin: icons below each links.
218 * - _LOGGEDIN_: true/false
220 * @param array $data data passed to plugin
222 * @return array altered $data.
224 function hook_demo_plugin_render_linklist($data)
227 * Action links (action_plugin):
228 * A link is an array of its attributes (key="value"),
229 * and a mandatory `html` key, which contains its value.
230 * It's also recommended to add key 'on' or 'off' for theme rendering.
235 'title' => 'Uppercase!',
240 if (isset($_GET['up'])) {
241 // Manipulate link data
242 foreach ($data['links'] as &$value) {
243 $value['description'] = strtoupper($value['description']);
244 $value['title'] = strtoupper($value['title']);
246 $action['on'] = true;
248 $action['off'] = true;
250 $data['action_plugin'][] = $action;
252 // link_plugin (for each link)
253 foreach ($data['links'] as &$value) {
254 $value['link_plugin'][] = ' DEMO \o/';
258 $data['plugin_start_zone'][] = '<center>BEFORE</center>';
260 $data['plugin_end_zone'][] = '<center>AFTER</center>';
266 * Hook render_editlink.
268 * Template placeholders:
269 * - field_plugin: add link fields after tags.
271 * @param array $data data passed to plugin
273 * @return array altered $data.
275 function hook_demo_plugin_render_editlink($data)
277 // Load HTML into a string
278 $html = file_get_contents(PluginManager
::$PLUGINS_PATH .'/demo_plugin/field.html');
280 // replace value in HTML if it exists in $data
281 if (!empty($data['link']['stuff'])) {
282 $html = sprintf($html, $data['link']['stuff']);
284 $html = sprintf($html, '');
288 $data['edit_link_plugin'][] = $html;
296 * Template placeholders:
297 * - tools_plugin: after other tools.
299 * @param array $data data passed to plugin
301 * @return array altered $data.
303 function hook_demo_plugin_render_tools($data)
306 $data['tools_plugin'][] = 'tools_plugin';
312 * Hook render_picwall.
314 * Template placeholders:
315 * - plugin_start_zone: page start.
316 * - plugin_end_zone: page end.
319 * - _LOGGEDIN_: true/false
321 * @param array $data data passed to plugin
323 * @return array altered $data.
325 function hook_demo_plugin_render_picwall($data)
328 $data['plugin_start_zone'][] = '<center>BEFORE</center>';
330 $data['plugin_end_zone'][] = '<center>AFTER</center>';
336 * Hook render_tagcloud.
338 * Template placeholders:
339 * - plugin_start_zone: page start.
340 * - plugin_end_zone: page end.
343 * - _LOGGEDIN_: true/false
345 * @param array $data data passed to plugin
347 * @return array altered $data.
349 function hook_demo_plugin_render_tagcloud($data)
352 $data['plugin_start_zone'][] = '<center>BEFORE</center>';
354 $data['plugin_end_zone'][] = '<center>AFTER</center>';
362 * Template placeholders:
363 * - plugin_start_zone: page start.
364 * - plugin_end_zone: page end.
367 * - _LOGGEDIN_: true/false
369 * @param array $data data passed to plugin
371 * @return array altered $data.
373 function hook_demo_plugin_render_daily($data)
376 $data['plugin_start_zone'][] = '<center>BEFORE</center>';
378 $data['plugin_end_zone'][] = '<center>AFTER</center>';
381 // Manipulate columns data
382 foreach ($data['linksToDisplay'] as &$value) {
383 $value['formatedDescription'] .= ' ಠ_ಠ';
386 // Add plugin content at the end of each link
387 foreach ($data['linksToDisplay'] as &$value) {
388 $value['link_plugin'][] = 'DEMO';
401 * Triggered when a link is save (new or edit).
402 * All new links now contain a 'stuff' value.
404 * @param array $data contains the new link data.
406 * @return array altered $data.
408 function hook_demo_plugin_save_link($data)
411 // Save stuff added in editlink field
412 if (!empty($_POST['lf_stuff'])) {
413 $data['stuff'] = escape($_POST['lf_stuff']);
422 * Triggered when a link is deleted.
424 * @param array $data contains the link to be deleted.
426 * @return array altered data.
428 function hook_demo_plugin_delete_link($data)
430 if (strpos($data['url'], 'youtube.com') !== false) {
431 exit('You can not delete a YouTube link. Don\'t ask.');
436 * Execute render_feed hook.
437 * Called with ATOM and RSS feed.
440 * - _PAGE_: current page
441 * - _LOGGEDIN_: true/false
443 * @param array $data data passed to plugin
445 * @return array altered $data.
447 function hook_demo_plugin_render_feed($data)
449 foreach ($data['links'] as &$link) {
450 if ($data['_PAGE_'] == Router
::$PAGE_FEED_ATOM) {
451 $link['description'] .= ' - ATOM Feed' ;
452 } elseif ($data['_PAGE_'] == Router
::$PAGE_FEED_RSS) {
453 $link['description'] .= ' - RSS Feed';
460 * When plugin parameters are saved.
462 * @param array $data $_POST array
464 * @return array Updated $_POST array
466 function hook_demo_plugin_save_plugin_parameters($data)
468 // Here we edit the provided value, but we can use this to generate config files, etc.
469 if (! empty($data['DEMO_PLUGIN_PARAMETER']) && ! endsWith($data['DEMO_PLUGIN_PARAMETER'], '_SUFFIX')) {
470 $data['DEMO_PLUGIN_PARAMETER'] .= '_SUFFIX';
477 * This function is never called, but contains translation calls for GNU gettext extraction.
479 function demo_dummy_translation()
482 t('A demo plugin covering all use cases for template designers and plugin developers.');
483 t('This is a parameter dedicated to the demo plugin. It\'ll be suffixed.');
484 t('Other demo parameter');