6 * This plugin tries to completely cover Shaarli's plugin API.
7 * Can be used by plugin developers to make their own plugin.
11 * RENDER HEADER, INCLUDES, FOOTER
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_.
18 use Shaarli\Config\ConfigManager
;
19 use Shaarli\Plugin\PluginManager
;
20 use Shaarli\Render\TemplatePage
;
23 * In the footer hook, there is a working example of a translation extension for Shaarli.
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.
28 * See the documentation for more information.
30 const EXT_TRANSLATION_DOMAIN
= 'demo';
33 * This is not necessary, but it's easier if you don't want Poedit to mix up your translations.
35 function demo_plugin_t($text, $nText = '', $nb = 1)
37 return t($text, $nText, $nb, EXT_TRANSLATION_DOMAIN
);
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.
45 * @param $conf ConfigManager instance.
47 * @return array List of errors (optional).
49 function demo_plugin_init($conf)
51 $conf->get('toto', 'nope');
53 if (! $conf->exists('translation.extensions.demo')) {
54 // Custom translation with the domain 'demo'
55 $conf->set('translation.extensions.demo', 'plugins/demo_plugin/languages/');
59 $errors[] = 'This a demo init error.';
65 * Executed on every page render.
67 * Template placeholders:
71 * @param array $data data passed to plugin
73 * @return array altered $data.
75 function hook_demo_plugin_render_header($data)
77 // Only execute when linklist is rendered.
78 if ($data['_PAGE_'] == TemplatePage
::LINKLIST
) {
80 if ($data['_LOGGEDIN_'] === true) {
83 * A link is an array of its attributes (key="value"),
84 * and a mandatory `html` key, which contains its value.
89 'class' => 'mybutton',
90 'title' => 'hover me',
92 'html' => 'DEMO buttons toolbar',
94 $data['buttons_toolbar'][] = $button;
98 * Add additional input fields in the tools.
99 * A field is an array containing:
101 * 'form-attribute-1' => 'form attribute 1 value',
102 * 'form-attribute-2' => 'form attribute 2 value',
105 * 'input-1-attribute-1 => 'input 1 attribute 1 value',
106 * 'input-1-attribute-2 => 'input 1 attribute 2 value',
109 * 'input-2-attribute-1 => 'input 2 attribute 1 value',
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">
122 'action' => $data['_BASE_PATH_'] . '/',
123 'class' => 'addform',
129 'placeholder' => 'demo',
133 $data['fields_toolbar'][] = $form;
135 // Another button always displayed
142 $data['buttons_toolbar'][] = $button;
148 * Hook render_includes.
149 * Executed on every page render.
151 * Template placeholders:
155 * - _PAGE_: current page
156 * - _LOGGEDIN_: true/false
158 * @param array $data data passed to plugin
160 * @return array altered $data.
162 function hook_demo_plugin_render_includes($data)
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';
172 * Hook render_footer.
173 * Executed on every page render.
175 * Template placeholders:
181 * - _PAGE_: current page
182 * - _LOGGEDIN_: true/false
184 * @param array $data data passed to plugin
186 * @return array altered $data.
188 function hook_demo_plugin_render_footer($data)
191 $data['text'][] = '<br>' . demo_plugin_t('Shaarli is now enhanced by the awesome demo_plugin.');
193 // Free elements at the end of the page.
194 $data['endofpage'][] = '<marquee id="demo_marquee">' .
195 'DEMO: it\'s 1999 all over again!' .
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';
210 * Hook render_linklist.
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.
219 * - _LOGGEDIN_: true/false
221 * @param array $data data passed to plugin
223 * @return array altered $data.
225 function hook_demo_plugin_render_linklist($data)
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.
236 'title' => 'Uppercase!',
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']);
247 $action['on'] = true;
249 $action['off'] = true;
251 $data['action_plugin'][] = $action;
253 // link_plugin (for each link)
254 foreach ($data['links'] as &$value) {
255 $value['link_plugin'][] = ' DEMO \o/';
259 $data['plugin_start_zone'][] = '<center>BEFORE</center>';
261 $data['plugin_end_zone'][] = '<center>AFTER</center>';
267 * Hook render_editlink.
269 * Template placeholders:
270 * - field_plugin: add link fields after tags.
272 * @param array $data data passed to plugin
274 * @return array altered $data.
276 function hook_demo_plugin_render_editlink($data)
278 // Load HTML into a string
279 $html = file_get_contents(PluginManager
::$PLUGINS_PATH . '/demo_plugin/field.html');
281 // Replace value in HTML if it exists in $data
282 if (!empty($data['link']['stuff'])) {
283 $html = sprintf($html, $data['link']['stuff']);
285 $html = sprintf($html, '');
289 $data['edit_link_plugin'][] = $html;
297 * Template placeholders:
298 * - tools_plugin: after other tools.
300 * @param array $data data passed to plugin
302 * @return array altered $data.
304 function hook_demo_plugin_render_tools($data)
307 $data['tools_plugin'][] = 'tools_plugin';
313 * Hook render_picwall.
315 * Template placeholders:
316 * - plugin_start_zone: page start.
317 * - plugin_end_zone: page end.
320 * - _LOGGEDIN_: true/false
322 * @param array $data data passed to plugin
324 * @return array altered $data.
326 function hook_demo_plugin_render_picwall($data)
328 $data['plugin_start_zone'][] = '<center>BEFORE</center>';
329 $data['plugin_end_zone'][] = '<center>AFTER</center>';
335 * Hook render_tagcloud.
337 * Template placeholders:
338 * - plugin_start_zone: page start.
339 * - plugin_end_zone: page end.
342 * - _LOGGEDIN_: true/false
344 * @param array $data data passed to plugin
346 * @return array altered $data.
348 function hook_demo_plugin_render_tagcloud($data)
350 $data['plugin_start_zone'][] = '<center>BEFORE</center>';
351 $data['plugin_end_zone'][] = '<center>AFTER</center>';
359 * Template placeholders:
360 * - plugin_start_zone: page start.
361 * - plugin_end_zone: page end.
364 * - _LOGGEDIN_: true/false
366 * @param array $data data passed to plugin
368 * @return array altered $data.
370 function hook_demo_plugin_render_daily($data)
372 $data['plugin_start_zone'][] = '<center>BEFORE</center>';
373 $data['plugin_end_zone'][] = '<center>AFTER</center>';
376 // Manipulate columns data
377 foreach ($data['linksToDisplay'] as &$value) {
378 $value['formatedDescription'] .= ' ಠ_ಠ';
381 // Add plugin content at the end of each link
382 foreach ($data['linksToDisplay'] as &$value) {
383 $value['link_plugin'][] = 'DEMO';
396 * Triggered when a link is save (new or edit).
397 * All new links now contain a 'stuff' value.
399 * @param array $data contains the new link data.
401 * @return array altered $data.
403 function hook_demo_plugin_save_link($data)
406 // Save stuff added in editlink field
407 if (!empty($_POST['lf_stuff'])) {
408 $data['stuff'] = escape($_POST['lf_stuff']);
417 * Triggered when a link is deleted.
419 * @param array $data contains the link to be deleted.
421 * @return array altered data.
423 function hook_demo_plugin_delete_link($data)
425 if (strpos($data['url'], 'youtube.com') !== false) {
426 exit('You can not delete a YouTube link. Don\'t ask.');
431 * Execute render_feed hook.
432 * Called with ATOM and RSS feed.
435 * - _PAGE_: current page
436 * - _LOGGEDIN_: true/false
438 * @param array $data data passed to plugin
440 * @return array altered $data.
442 function hook_demo_plugin_render_feed($data)
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';
455 * When plugin parameters are saved.
457 * @param array $data $_POST array
459 * @return array Updated $_POST array
461 function hook_demo_plugin_save_plugin_parameters($data)
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';
473 * This function is never called, but contains translation calls for GNU gettext extraction.
475 function demo_dummy_translation()
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');