]>
Commit | Line | Data |
---|---|---|
53ed6d7d | 1 | <!DOCTYPE html> |
2 | <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]--> | |
3 | <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]--> | |
4 | <head> | |
5 | <meta charset="utf-8"> | |
6 | <meta http-equiv="X-UA-Compatible" content="IE=edge"> | |
7 | <meta name="viewport" content="width=device-width, initial-scale=1.0"> | |
8 | ||
9 | ||
10 | <link rel="shortcut icon" href="../img/favicon.ico"> | |
11 | <title>Plugin System - Shaarli Documentation</title> | |
12 | <link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'> | |
13 | ||
14 | <link rel="stylesheet" href="../css/theme.css" type="text/css" /> | |
15 | <link rel="stylesheet" href="../css/theme_extra.css" type="text/css" /> | |
16 | <link rel="stylesheet" href="../css/highlight.css"> | |
17 | <link href="../github-markdown.css" rel="stylesheet"> | |
18 | ||
19 | <script> | |
20 | // Current page data | |
21 | var mkdocs_page_name = "Plugin System"; | |
22 | var mkdocs_page_input_path = "Plugin-System.md"; | |
23 | var mkdocs_page_url = "/Plugin-System/"; | |
24 | </script> | |
25 | ||
26 | <script src="../js/jquery-2.1.1.min.js"></script> | |
27 | <script src="../js/modernizr-2.8.3.min.js"></script> | |
28 | <script type="text/javascript" src="../js/highlight.pack.js"></script> | |
29 | ||
30 | </head> | |
31 | ||
32 | <body class="wy-body-for-nav" role="document"> | |
33 | ||
34 | <div class="wy-grid-for-nav"> | |
35 | ||
36 | ||
37 | <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav"> | |
38 | <div class="wy-side-nav-search"> | |
39 | <a href=".." class="icon icon-home"> Shaarli Documentation</a> | |
40 | <div role="search"> | |
41 | <form id ="rtd-search-form" class="wy-form" action="../search.html" method="get"> | |
42 | <input type="text" name="q" placeholder="Search docs" /> | |
43 | </form> | |
44 | </div> | |
45 | </div> | |
46 | ||
47 | <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation"> | |
48 | <ul class="current"> | |
49 | ||
50 | ||
51 | <li class="toctree-l1"> | |
52 | ||
53 | <a class="" href="..">Home</a> | |
54 | </li> | |
55 | ||
56 | <li class="toctree-l1"> | |
57 | ||
58 | <span class="caption-text">Setup</span> | |
59 | <ul class="subnav"> | |
60 | <li class=""> | |
61 | ||
62 | <a class="" href="../Download-and-Installation/">Download and Installation</a> | |
63 | </li> | |
64 | <li class=""> | |
65 | ||
66 | <a class="" href="../Upgrade-and-migration/">Upgrade and migration</a> | |
67 | </li> | |
68 | <li class=""> | |
69 | ||
70 | <a class="" href="../Server-requirements/">Server requirements</a> | |
71 | </li> | |
72 | <li class=""> | |
73 | ||
74 | <a class="" href="../Server-configuration/">Server configuration</a> | |
75 | </li> | |
76 | <li class=""> | |
77 | ||
78 | <a class="" href="../Server-security/">Server security</a> | |
79 | </li> | |
80 | <li class=""> | |
81 | ||
82 | <a class="" href="../Shaarli-configuration/">Shaarli configuration</a> | |
83 | </li> | |
84 | <li class=""> | |
85 | ||
86 | <a class="" href="../Plugins/">Plugins</a> | |
87 | </li> | |
88 | </ul> | |
89 | </li> | |
90 | ||
91 | <li class="toctree-l1"> | |
92 | ||
93 | <span class="caption-text">Docker</span> | |
94 | <ul class="subnav"> | |
95 | <li class=""> | |
96 | ||
97 | <a class="" href="../Docker-101/">Docker 101</a> | |
98 | </li> | |
99 | <li class=""> | |
100 | ||
101 | <a class="" href="../Shaarli-images/">Shaarli images</a> | |
102 | </li> | |
103 | <li class=""> | |
104 | ||
105 | <a class="" href="../Reverse-proxy-configuration/">Reverse proxy configuration</a> | |
106 | </li> | |
107 | <li class=""> | |
108 | ||
109 | <a class="" href="../Docker-resources/">Docker resources</a> | |
110 | </li> | |
111 | </ul> | |
112 | </li> | |
113 | ||
114 | <li class="toctree-l1"> | |
115 | ||
116 | <span class="caption-text">Usage</span> | |
117 | <ul class="subnav"> | |
118 | <li class=""> | |
119 | ||
120 | <a class="" href="../Features/">Features</a> | |
121 | </li> | |
122 | <li class=""> | |
123 | ||
124 | <a class="" href="../Bookmarklet/">Bookmarklet</a> | |
125 | </li> | |
126 | <li class=""> | |
127 | ||
128 | <a class="" href="../Browsing-and-searching/">Browsing and searching</a> | |
129 | </li> | |
130 | <li class=""> | |
131 | ||
132 | <a class="" href="../Firefox-share/">Firefox share</a> | |
133 | </li> | |
134 | <li class=""> | |
135 | ||
136 | <a class="" href="../RSS-feeds/">RSS feeds</a> | |
137 | </li> | |
138 | <li class=""> | |
139 | ||
140 | <a class="" href="../REST-API/">REST API</a> | |
141 | </li> | |
142 | </ul> | |
143 | </li> | |
144 | ||
145 | <li class="toctree-l1"> | |
146 | ||
147 | <span class="caption-text">How To</span> | |
148 | <ul class="subnav"> | |
149 | <li class=""> | |
150 | ||
151 | <a class="" href="../Backup,-restore,-import-and-export/">Backup, restore, import and export</a> | |
152 | </li> | |
153 | <li class=""> | |
154 | ||
0433c688 | 155 | <a class="" href="../Various-hacks/">Various hacks</a> |
53ed6d7d | 156 | </li> |
157 | </ul> | |
158 | </li> | |
159 | ||
160 | <li class="toctree-l1"> | |
161 | ||
162 | <a class="" href="../Troubleshooting/">Troubleshooting</a> | |
163 | </li> | |
164 | ||
165 | <li class="toctree-l1"> | |
166 | ||
167 | <span class="caption-text">Development</span> | |
168 | <ul class="subnav"> | |
169 | <li class=""> | |
170 | ||
171 | <a class="" href="../Development-guidelines/">Development guidelines</a> | |
172 | </li> | |
173 | <li class=""> | |
174 | ||
175 | <a class="" href="../Continuous-integration-tools/">Continuous integration tools</a> | |
176 | </li> | |
177 | <li class=""> | |
178 | ||
179 | <a class="" href="../GnuPG-signature/">GnuPG signature</a> | |
180 | </li> | |
181 | <li class=""> | |
182 | ||
183 | <a class="" href="../Coding-guidelines/">Coding guidelines</a> | |
184 | </li> | |
185 | <li class=""> | |
186 | ||
187 | <a class="" href="../Directory-structure/">Directory structure</a> | |
188 | </li> | |
189 | <li class=""> | |
190 | ||
191 | <a class="" href="../3rd-party-libraries/">3rd party libraries</a> | |
192 | </li> | |
193 | <li class=" current"> | |
194 | ||
195 | <a class="current" href="./">Plugin System</a> | |
196 | <ul class="subnav"> | |
197 | ||
198 | <li class="toctree-l3"><a href="#developer-api">Developer API</a></li> | |
199 | ||
200 | <ul> | |
201 | ||
202 | <li><a class="toctree-l4" href="#what-can-i-do-with-plugins">What can I do with plugins?</a></li> | |
203 | ||
204 | <li><a class="toctree-l4" href="#how-can-i-create-a-plugin-for-shaarli">How can I create a plugin for Shaarli?</a></li> | |
205 | ||
206 | <li><a class="toctree-l4" href="#plugin-initialization">Plugin initialization</a></li> | |
207 | ||
208 | <li><a class="toctree-l4" href="#understanding-hooks">Understanding hooks</a></li> | |
209 | ||
210 | <li><a class="toctree-l4" href="#plugins-data">Plugin's data</a></li> | |
211 | ||
212 | <li><a class="toctree-l4" href="#metadata">Metadata</a></li> | |
213 | ||
214 | <li><a class="toctree-l4" href="#its-not-working">It's not working!</a></li> | |
215 | ||
216 | <li><a class="toctree-l4" href="#hooks">Hooks</a></li> | |
217 | ||
218 | </ul> | |
219 | ||
220 | ||
221 | <li class="toctree-l3"><a href="#guide-for-template-designer">Guide for template designer</a></li> | |
222 | ||
223 | <ul> | |
224 | ||
225 | <li><a class="toctree-l4" href="#plugin-administration">Plugin administration</a></li> | |
226 | ||
227 | <li><a class="toctree-l4" href="#placeholder-system">Placeholder system</a></li> | |
228 | ||
229 | <li><a class="toctree-l4" href="#list-of-placeholders">List of placeholders</a></li> | |
230 | ||
231 | </ul> | |
232 | ||
233 | ||
234 | </ul> | |
235 | </li> | |
236 | <li class=""> | |
237 | ||
238 | <a class="" href="../Release-Shaarli/">Release Shaarli</a> | |
239 | </li> | |
240 | <li class=""> | |
241 | ||
242 | <a class="" href="../Versioning-and-Branches/">Versioning and Branches</a> | |
243 | </li> | |
244 | <li class=""> | |
245 | ||
246 | <a class="" href="../Security/">Security</a> | |
247 | </li> | |
248 | <li class=""> | |
249 | ||
250 | <a class="" href="../Static-analysis/">Static analysis</a> | |
251 | </li> | |
252 | <li class=""> | |
253 | ||
254 | <a class="" href="../Theming/">Theming</a> | |
255 | </li> | |
256 | <li class=""> | |
257 | ||
258 | <a class="" href="../Unit-tests/">Unit tests</a> | |
259 | </li> | |
260 | </ul> | |
261 | </li> | |
262 | ||
263 | <li class="toctree-l1"> | |
264 | ||
265 | <span class="caption-text">About</span> | |
266 | <ul class="subnav"> | |
267 | <li class=""> | |
268 | ||
269 | <a class="" href="../FAQ/">FAQ</a> | |
270 | </li> | |
271 | <li class=""> | |
272 | ||
273 | <a class="" href="../Community-&-Related-software/">Community & Related software</a> | |
274 | </li> | |
275 | </ul> | |
276 | </li> | |
277 | ||
278 | </ul> | |
279 | </div> | |
280 | | |
281 | </nav> | |
282 | ||
283 | <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> | |
284 | ||
285 | ||
286 | <nav class="wy-nav-top" role="navigation" aria-label="top navigation"> | |
287 | <i data-toggle="wy-nav-top" class="fa fa-bars"></i> | |
288 | <a href="..">Shaarli Documentation</a> | |
289 | </nav> | |
290 | ||
291 | ||
292 | <div class="wy-nav-content"> | |
293 | <div class="rst-content"> | |
294 | <div role="navigation" aria-label="breadcrumbs navigation"> | |
295 | <ul class="wy-breadcrumbs"> | |
296 | <li><a href="..">Docs</a> »</li> | |
297 | ||
298 | ||
299 | ||
300 | <li>Development »</li> | |
301 | ||
302 | ||
303 | ||
304 | <li>Plugin System</li> | |
305 | <li class="wy-breadcrumbs-aside"> | |
306 | ||
307 | <a href="https://github.com/shaarli/Shaarli/edit/master/docs/Plugin-System.md" | |
308 | class="icon icon-github"> Edit on GitHub</a> | |
309 | ||
310 | </li> | |
311 | </ul> | |
312 | <hr/> | |
313 | </div> | |
314 | <div role="main"> | |
315 | <div class="section"> | |
316 | ||
317 | <p><a href="#developer-api"><strong>I am a developer.</strong> Developer API.</a></p> | |
318 | <p><a href="#guide-for-template-designer"><strong>I am a template designer.</strong> Guide for template designer.</a></p> | |
319 | <h2 id="developer-api">Developer API</h2> | |
320 | <h3 id="what-can-i-do-with-plugins">What can I do with plugins?</h3> | |
321 | <p>The plugin system let you:</p> | |
322 | <ul> | |
323 | <li>insert content into specific places across templates.</li> | |
324 | <li>alter data before templates rendering.</li> | |
325 | <li>alter data before saving new links.</li> | |
326 | </ul> | |
327 | <h3 id="how-can-i-create-a-plugin-for-shaarli">How can I create a plugin for Shaarli?</h3> | |
328 | <p>First, chose a plugin name, such as <code>demo_plugin</code>.</p> | |
329 | <p>Under <code>plugin</code> folder, create a folder named with your plugin name. Then create a <plugin_name>.php file in that folder.</p> | |
330 | <p>You should have the following tree view:</p> | |
331 | <pre><code>| index.php | |
332 | | plugins/ | |
333 | |---| demo_plugin/ | |
334 | | |---| demo_plugin.php | |
335 | </code></pre> | |
336 | ||
337 | <h3 id="plugin-initialization">Plugin initialization</h3> | |
338 | <p>At the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an <code>init()</code> function to execute and run it if it exists. This function must be named this way, and takes the <code>ConfigManager</code> as parameter.</p> | |
339 | <pre><code><plugin_name>_init($conf) | |
340 | </code></pre> | |
341 | <p>This function can be used to create initial data, load default settings, etc. But also to set <em>plugin errors</em>. If the initialization function returns an array of strings, they will be understand as errors, and displayed in the header to logged in users.</p> | |
342 | <h3 id="understanding-hooks">Understanding hooks</h3> | |
343 | <p>A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.</p> | |
344 | <p>These functions need to be named with this pattern:</p> | |
345 | <pre><code>hook_<plugin_name>_<hook_name>($data, $conf) | |
346 | </code></pre> | |
347 | ||
348 | <p>Parameters:</p> | |
349 | <ul> | |
350 | <li>data: see <a href="https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data">$data section</a></li> | |
351 | <li>conf: the <code>ConfigManager</code> instance.</li> | |
352 | </ul> | |
353 | <p>For exemple, if my plugin want to add data to the header, this function is needed:</p> | |
354 | <pre><code>hook_demo_plugin_render_header | |
355 | </code></pre> | |
356 | <p>If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.</p> | |
357 | <h3 id="plugins-data">Plugin's data</h3> | |
358 | <h4 id="parameters">Parameters</h4> | |
359 | <p>Every hook function has a <code>$data</code> parameter. Its content differs for each hooks.</p> | |
360 | <p><strong>This parameter needs to be returned every time</strong>, otherwise data is lost.</p> | |
361 | <pre><code>return $data; | |
362 | </code></pre> | |
363 | <h4 id="filling-templates-placeholder">Filling templates placeholder</h4> | |
364 | <p>Template placeholders are displayed in template in specific places.</p> | |
365 | <p>RainTPL displays every element contained in the placeholder's array. These element can be added by plugins.</p> | |
366 | <p>For example, let's add a value in the placeholder <code>top_placeholder</code> which is displayed at the top of my page:</p> | |
367 | <pre><code class="php">$data['top_placeholder'][] = 'My content'; | |
368 | # OR | |
369 | array_push($data['top_placeholder'], 'My', 'content'); | |
370 | ||
371 | return $data; | |
372 | </code></pre> | |
373 | ||
374 | <h4 id="data-manipulation">Data manipulation</h4> | |
375 | <p>When a page is displayed, every variable send to the template engine is passed to plugins before that in <code>$data</code>.</p> | |
376 | <p>The data contained by this array can be altered before template rendering.</p> | |
377 | <p>For exemple, in linklist, it is possible to alter every title:</p> | |
378 | <pre><code class="php">// mind the reference if you want $data to be altered | |
379 | foreach ($data['links'] as &$value) { | |
380 | // String reverse every title. | |
381 | $value['title'] = strrev($value['title']); | |
382 | } | |
383 | ||
384 | return $data; | |
385 | </code></pre> | |
386 | ||
387 | <h3 id="metadata">Metadata</h3> | |
388 | <p>Every plugin needs a <code><plugin_name>.meta</code> file, which is in fact an <code>.ini</code> file (<code>KEY="VALUE"</code>), to be listed in plugin administration.</p> | |
389 | <p>Each file contain two keys:</p> | |
390 | <ul> | |
391 | <li><code>description</code>: plugin description</li> | |
392 | <li><code>parameters</code>: user parameter names, separated by a <code>;</code>.</li> | |
393 | <li><code>parameter.<PARAMETER_NAME></code>: add a text description the specified parameter.</li> | |
394 | </ul> | |
395 | <blockquote> | |
396 | <p>Note: In PHP, <code>parse_ini_file()</code> seems to want strings to be between by quotes <code>"</code> in the ini file.</p> | |
397 | </blockquote> | |
398 | <h3 id="its-not-working">It's not working!</h3> | |
399 | <p>Use <code>demo_plugin</code> as a functional example. It covers most of the plugin system features.</p> | |
400 | <p>If it's still not working, please <a href="https://github.com/shaarli/Shaarli/issues/new">open an issue</a>.</p> | |
401 | <h3 id="hooks">Hooks</h3> | |
402 | <table> | |
403 | <thead> | |
404 | <tr> | |
405 | <th>Hooks</th> | |
406 | <th align="center">Description</th> | |
407 | </tr> | |
408 | </thead> | |
409 | <tbody> | |
410 | <tr> | |
411 | <td><a href="#render_header">render_header</a></td> | |
412 | <td align="center">Allow plugin to add content in page headers.</td> | |
413 | </tr> | |
414 | <tr> | |
415 | <td><a href="#render_includes">render_includes</a></td> | |
416 | <td align="center">Allow plugin to include their own CSS files.</td> | |
417 | </tr> | |
418 | <tr> | |
419 | <td><a href="#render_footer">render_footer</a></td> | |
420 | <td align="center">Allow plugin to add content in page footer and include their own JS files.</td> | |
421 | </tr> | |
422 | <tr> | |
423 | <td><a href="#render_linklist">render_linklist</a></td> | |
424 | <td align="center">It allows to add content at the begining and end of the page, after every link displayed and to alter link data.</td> | |
425 | </tr> | |
426 | <tr> | |
427 | <td><a href="#render_editlink">render_editlink</a></td> | |
428 | <td align="center">Allow to add fields in the form, or display elements.</td> | |
429 | </tr> | |
430 | <tr> | |
431 | <td><a href="#render_tools">render_tools</a></td> | |
432 | <td align="center">Allow to add content at the end of the page.</td> | |
433 | </tr> | |
434 | <tr> | |
435 | <td><a href="#render_picwall">render_picwall</a></td> | |
436 | <td align="center">Allow to add content at the top and bottom of the page.</td> | |
437 | </tr> | |
438 | <tr> | |
439 | <td><a href="#render_tagcloud">render_tagcloud</a></td> | |
440 | <td align="center">Allow to add content at the top and bottom of the page, and after all tags.</td> | |
441 | </tr> | |
442 | <tr> | |
443 | <td><a href="#render_taglist">render_taglist</a></td> | |
444 | <td align="center">Allow to add content at the top and bottom of the page, and after all tags.</td> | |
445 | </tr> | |
446 | <tr> | |
447 | <td><a href="#render_daily">render_daily</a></td> | |
448 | <td align="center">Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.</td> | |
449 | </tr> | |
450 | <tr> | |
451 | <td><a href="#render_feed">render_feed</a></td> | |
452 | <td align="center">Allow to do add tags in RSS and ATOM feeds.</td> | |
453 | </tr> | |
454 | <tr> | |
455 | <td><a href="#save_link">save_link</a></td> | |
456 | <td align="center">Allow to alter the link being saved in the datastore.</td> | |
457 | </tr> | |
458 | <tr> | |
459 | <td><a href="#delete_link">delete_link</a></td> | |
460 | <td align="center">Allow to do an action before a link is deleted from the datastore.</td> | |
461 | </tr> | |
462 | </tbody> | |
463 | </table> | |
464 | <h4 id="render_header">render_header</h4> | |
465 | <p>Triggered on every page.</p> | |
466 | <p>Allow plugin to add content in page headers.</p> | |
467 | <h5 id="data">Data</h5> | |
468 | <p><code>$data</code> is an array containing:</p> | |
469 | <ul> | |
470 | <li><code>_PAGE_</code>: current target page (eg: <code>linklist</code>, <code>picwall</code>, etc.).</li> | |
471 | <li><code>_LOGGEDIN_</code>: true if user is logged in, false otherwise.</li> | |
472 | </ul> | |
473 | <h5 id="template-placeholders">Template placeholders</h5> | |
474 | <p>Items can be displayed in templates by adding an entry in <code>$data['<placeholder>']</code> array.</p> | |
475 | <p>List of placeholders:</p> | |
476 | <ul> | |
477 | <li><code>buttons_toolbar</code>: after the list of buttons in the header.</li> | |
478 | </ul> | |
479 | <p><img alt="buttons_toolbar_example" src="http://i.imgur.com/ssJUOrt.png" /></p> | |
480 | <ul> | |
481 | <li><code>fields_toolbar</code>: after search fields in the header.</li> | |
482 | </ul> | |
483 | <blockquote> | |
484 | <p>Note: This will only be called in linklist.</p> | |
485 | </blockquote> | |
486 | <p><img alt="fields_toolbar_example" src="http://i.imgur.com/3GMifI2.png" /></p> | |
487 | <h4 id="render_includes">render_includes</h4> | |
488 | <p>Triggered on every page.</p> | |
489 | <p>Allow plugin to include their own CSS files.</p> | |
490 | <h5 id="data_1">Data</h5> | |
491 | <p><code>$data</code> is an array containing:</p> | |
492 | <ul> | |
493 | <li><code>_PAGE_</code>: current target page (eg: <code>linklist</code>, <code>picwall</code>, etc.).</li> | |
494 | <li><code>_LOGGEDIN_</code>: true if user is logged in, false otherwise.</li> | |
495 | </ul> | |
496 | <h5 id="template-placeholders_1">Template placeholders</h5> | |
497 | <p>Items can be displayed in templates by adding an entry in <code>$data['<placeholder>']</code> array.</p> | |
498 | <p>List of placeholders:</p> | |
499 | <ul> | |
500 | <li><code>css_files</code>: called after loading default CSS.</li> | |
501 | </ul> | |
502 | <blockquote> | |
503 | <p>Note: only add the path of the CSS file. E.g: <code>plugins/demo_plugin/custom_demo.css</code>.</p> | |
504 | </blockquote> | |
505 | <h4 id="render_footer">render_footer</h4> | |
506 | <p>Triggered on every page.</p> | |
507 | <p>Allow plugin to add content in page footer and include their own JS files.</p> | |
508 | <h5 id="data_2">Data</h5> | |
509 | <p><code>$data</code> is an array containing:</p> | |
510 | <ul> | |
511 | <li><code>_PAGE_</code>: current target page (eg: <code>linklist</code>, <code>picwall</code>, etc.).</li> | |
512 | <li><code>_LOGGEDIN_</code>: true if user is logged in, false otherwise.</li> | |
513 | </ul> | |
514 | <h5 id="template-placeholders_2">Template placeholders</h5> | |
515 | <p>Items can be displayed in templates by adding an entry in <code>$data['<placeholder>']</code> array.</p> | |
516 | <p>List of placeholders:</p> | |
517 | <ul> | |
518 | <li><code>text</code>: called after the end of the footer text.</li> | |
519 | <li><code>endofpage</code>: called at the end of the page.</li> | |
520 | </ul> | |
521 | <p><img alt="text_example" src="http://i.imgur.com/L5S2YEH.png" /></p> | |
522 | <ul> | |
523 | <li><code>js_files</code>: called at the end of the page, to include custom JS scripts.</li> | |
524 | </ul> | |
525 | <blockquote> | |
526 | <p>Note: only add the path of the JS file. E.g: <code>plugins/demo_plugin/custom_demo.js</code>.</p> | |
527 | </blockquote> | |
528 | <h4 id="render_linklist">render_linklist</h4> | |
529 | <p>Triggered when <code>linklist</code> is displayed (list of links, permalink, search, tag filtered, etc.).</p> | |
530 | <p>It allows to add content at the begining and end of the page, after every link displayed and to alter link data.</p> | |
531 | <h5 id="data_3">Data</h5> | |
532 | <p><code>$data</code> is an array containing:</p> | |
533 | <ul> | |
534 | <li><code>_LOGGEDIN_</code>: true if user is logged in, false otherwise.</li> | |
535 | <li>All templates data, including links.</li> | |
536 | </ul> | |
537 | <h5 id="template-placeholders_3">Template placeholders</h5> | |
538 | <p>Items can be displayed in templates by adding an entry in <code>$data['<placeholder>']</code> array.</p> | |
539 | <p>List of placeholders:</p> | |
540 | <ul> | |
541 | <li><code>action_plugin</code>: next to the button "private only" at the top and bottom of the page.</li> | |
542 | </ul> | |
543 | <p><img alt="action_plugin_example" src="http://i.imgur.com/Q12PWg0.png" /></p> | |
544 | <ul> | |
545 | <li><code>link_plugin</code>: for every link, between permalink and link URL.</li> | |
546 | </ul> | |
547 | <p><img alt="link_plugin_example" src="http://i.imgur.com/3oDPhWx.png" /></p> | |
548 | <ul> | |
549 | <li><code>plugin_start_zone</code>: before displaying the template content.</li> | |
550 | </ul> | |
551 | <p><img alt="plugin_start_zone_example" src="http://i.imgur.com/OVBkGy3.png" /></p> | |
552 | <ul> | |
553 | <li><code>plugin_end_zone</code>: after displaying the template content.</li> | |
554 | </ul> | |
555 | <p><img alt="plugin_end_zone_example" src="http://i.imgur.com/6IoRuop.png" /></p> | |
556 | <h4 id="render_editlink">render_editlink</h4> | |
557 | <p>Triggered when the link edition form is displayed.</p> | |
558 | <p>Allow to add fields in the form, or display elements.</p> | |
559 | <h5 id="data_4">Data</h5> | |
560 | <p><code>$data</code> is an array containing:</p> | |
561 | <ul> | |
562 | <li>All templates data.</li> | |
563 | </ul> | |
564 | <h5 id="template-placeholders_4">Template placeholders</h5> | |
565 | <p>Items can be displayed in templates by adding an entry in <code>$data['<placeholder>']</code> array.</p> | |
566 | <p>List of placeholders:</p> | |
567 | <ul> | |
568 | <li><code>edit_link_plugin</code>: after tags field.</li> | |
569 | </ul> | |
570 | <p><img alt="edit_link_plugin_example" src="http://i.imgur.com/5u17Ens.png" /></p> | |
571 | <h4 id="render_tools">render_tools</h4> | |
572 | <p>Triggered when the "tools" page is displayed.</p> | |
573 | <p>Allow to add content at the end of the page.</p> | |
574 | <h5 id="data_5">Data</h5> | |
575 | <p><code>$data</code> is an array containing:</p> | |
576 | <ul> | |
577 | <li>All templates data.</li> | |
578 | </ul> | |
579 | <h5 id="template-placeholders_5">Template placeholders</h5> | |
580 | <p>Items can be displayed in templates by adding an entry in <code>$data['<placeholder>']</code> array.</p> | |
581 | <p>List of placeholders:</p> | |
582 | <ul> | |
583 | <li><code>tools_plugin</code>: at the end of the page.</li> | |
584 | </ul> | |
585 | <p><img alt="tools_plugin_example" src="http://i.imgur.com/Bqhu9oQ.png" /></p> | |
586 | <h4 id="render_picwall">render_picwall</h4> | |
587 | <p>Triggered when picwall is displayed.</p> | |
588 | <p>Allow to add content at the top and bottom of the page.</p> | |
589 | <h5 id="data_6">Data</h5> | |
590 | <p><code>$data</code> is an array containing:</p> | |
591 | <ul> | |
592 | <li><code>_LOGGEDIN_</code>: true if user is logged in, false otherwise.</li> | |
593 | <li>All templates data.</li> | |
594 | </ul> | |
595 | <h5 id="template-placeholders_6">Template placeholders</h5> | |
596 | <p>Items can be displayed in templates by adding an entry in <code>$data['<placeholder>']</code> array.</p> | |
597 | <p>List of placeholders:</p> | |
598 | <ul> | |
599 | <li> | |
600 | <p><code>plugin_start_zone</code>: before displaying the template content.</p> | |
601 | </li> | |
602 | <li> | |
603 | <p><code>plugin_end_zone</code>: after displaying the template content.</p> | |
604 | </li> | |
605 | </ul> | |
606 | <p><img alt="plugin_start_end_zone_example" src="http://i.imgur.com/tVTQFER.png" /></p> | |
607 | <h4 id="render_tagcloud">render_tagcloud</h4> | |
608 | <p>Triggered when tagcloud is displayed.</p> | |
609 | <p>Allow to add content at the top and bottom of the page.</p> | |
610 | <h5 id="data_7">Data</h5> | |
611 | <p><code>$data</code> is an array containing:</p> | |
612 | <ul> | |
613 | <li><code>_LOGGEDIN_</code>: true if user is logged in, false otherwise.</li> | |
614 | <li>All templates data.</li> | |
615 | </ul> | |
616 | <h5 id="template-placeholders_7">Template placeholders</h5> | |
617 | <p>Items can be displayed in templates by adding an entry in <code>$data['<placeholder>']</code> array.</p> | |
618 | <p>List of placeholders:</p> | |
619 | <ul> | |
620 | <li> | |
621 | <p><code>plugin_start_zone</code>: before displaying the template content.</p> | |
622 | </li> | |
623 | <li> | |
624 | <p><code>plugin_end_zone</code>: after displaying the template content.</p> | |
625 | </li> | |
626 | </ul> | |
627 | <p>For each tag, the following placeholder can be used:</p> | |
628 | <ul> | |
629 | <li><code>tag_plugin</code>: after each tag</li> | |
630 | </ul> | |
631 | <p><img alt="plugin_start_end_zone_example" src="http://i.imgur.com/vHmyT3a.png" /></p> | |
632 | <h4 id="render_taglist">render_taglist</h4> | |
633 | <p>Triggered when taglist is displayed.</p> | |
634 | <p>Allow to add content at the top and bottom of the page.</p> | |
635 | <h5 id="data_8">Data</h5> | |
636 | <p><code>$data</code> is an array containing:</p> | |
637 | <ul> | |
638 | <li><code>_LOGGEDIN_</code>: true if user is logged in, false otherwise.</li> | |
639 | <li>All templates data.</li> | |
640 | </ul> | |
641 | <h5 id="template-placeholders_8">Template placeholders</h5> | |
642 | <p>Items can be displayed in templates by adding an entry in <code>$data['<placeholder>']</code> array.</p> | |
643 | <p>List of placeholders:</p> | |
644 | <ul> | |
645 | <li> | |
646 | <p><code>plugin_start_zone</code>: before displaying the template content.</p> | |
647 | </li> | |
648 | <li> | |
649 | <p><code>plugin_end_zone</code>: after displaying the template content.</p> | |
650 | </li> | |
651 | </ul> | |
652 | <p>For each tag, the following placeholder can be used:</p> | |
653 | <ul> | |
654 | <li><code>tag_plugin</code>: after each tag</li> | |
655 | </ul> | |
656 | <h4 id="render_daily">render_daily</h4> | |
657 | <p>Triggered when tagcloud is displayed.</p> | |
658 | <p>Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.</p> | |
659 | <h5 id="data_9">Data</h5> | |
660 | <p><code>$data</code> is an array containing:</p> | |
661 | <ul> | |
662 | <li><code>_LOGGEDIN_</code>: true if user is logged in, false otherwise.</li> | |
663 | <li>All templates data, including links.</li> | |
664 | </ul> | |
665 | <h5 id="template-placeholders_9">Template placeholders</h5> | |
666 | <p>Items can be displayed in templates by adding an entry in <code>$data['<placeholder>']</code> array.</p> | |
667 | <p>List of placeholders:</p> | |
668 | <ul> | |
669 | <li><code>link_plugin</code>: used at bottom of each link.</li> | |
670 | </ul> | |
671 | <p><img alt="link_plugin_example" src="http://i.imgur.com/hzhMfSZ.png" /></p> | |
672 | <ul> | |
673 | <li> | |
674 | <p><code>plugin_start_zone</code>: before displaying the template content.</p> | |
675 | </li> | |
676 | <li> | |
677 | <p><code>plugin_end_zone</code>: after displaying the template content.</p> | |
678 | </li> | |
679 | </ul> | |
680 | <h4 id="render_feed">render_feed</h4> | |
681 | <p>Triggered when the ATOM or RSS feed is displayed.</p> | |
682 | <p>Allow to add tags in the feed, either in the header or for each items. Items (links) can also be altered before being rendered.</p> | |
683 | <h5 id="data_10">Data</h5> | |
684 | <p><code>$data</code> is an array containing:</p> | |
685 | <ul> | |
686 | <li><code>_LOGGEDIN_</code>: true if user is logged in, false otherwise.</li> | |
687 | <li><code>_PAGE_</code>: containing either <code>rss</code> or <code>atom</code>.</li> | |
688 | <li>All templates data, including links.</li> | |
689 | </ul> | |
690 | <h5 id="template-placeholders_10">Template placeholders</h5> | |
691 | <p>Tags can be added in feeds by adding an entry in <code>$data['<placeholder>']</code> array.</p> | |
692 | <p>List of placeholders:</p> | |
693 | <ul> | |
694 | <li><code>feed_plugins_header</code>: used as a header tag in the feed.</li> | |
695 | </ul> | |
696 | <p>For each links:</p> | |
697 | <ul> | |
698 | <li><code>feed_plugins</code>: additional tag for every link entry.</li> | |
699 | </ul> | |
700 | <h4 id="save_link">save_link</h4> | |
701 | <p>Triggered when a link is save (new link or edit).</p> | |
702 | <p>Allow to alter the link being saved in the datastore.</p> | |
703 | <h5 id="data_11">Data</h5> | |
704 | <p><code>$data</code> is an array containing the link being saved:</p> | |
705 | <ul> | |
706 | <li>id</li> | |
707 | <li>title</li> | |
708 | <li>url</li> | |
709 | <li>shorturl</li> | |
710 | <li>description</li> | |
711 | <li>private</li> | |
712 | <li>tags</li> | |
713 | <li>created</li> | |
714 | <li>updated</li> | |
715 | </ul> | |
716 | <h4 id="delete_link">delete_link</h4> | |
717 | <p>Triggered when a link is deleted.</p> | |
718 | <p>Allow to execute any action before the link is actually removed from the datastore</p> | |
719 | <h5 id="data_12">Data</h5> | |
720 | <p><code>$data</code> is an array containing the link being saved:</p> | |
721 | <ul> | |
722 | <li>id</li> | |
723 | <li>title</li> | |
724 | <li>url</li> | |
725 | <li>shorturl</li> | |
726 | <li>description</li> | |
727 | <li>private</li> | |
728 | <li>tags</li> | |
729 | <li>created</li> | |
730 | <li>updated</li> | |
731 | </ul> | |
732 | <h2 id="guide-for-template-designer">Guide for template designer</h2> | |
733 | <h3 id="plugin-administration">Plugin administration</h3> | |
734 | <p>Your theme must include a plugin administration page: <code>pluginsadmin.html</code>.</p> | |
735 | <blockquote> | |
736 | <p>Note: repo's template link needs to be added when the PR is merged.</p> | |
737 | </blockquote> | |
738 | <p>Use the default one as an example.</p> | |
739 | <p>Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include <code>plugin_admin.js</code>, only if:</p> | |
740 | <ul> | |
741 | <li>you're using a table.</li> | |
742 | <li>you call orderUp() and orderUp() onclick on arrows.</li> | |
743 | <li>you add data-line and data-order to your rows.</li> | |
744 | </ul> | |
745 | <p>Otherwise, you can use your own JS as long as this field is send by the form:</p> | |
746 | <p><input type="hidden" name="order_{$key}" value="{$counter}"></p> | |
747 | <h3 id="placeholder-system">Placeholder system</h3> | |
748 | <p>In order to make plugins work with every custom themes, you need to add variable placeholder in your templates. </p> | |
749 | <p>It's a RainTPL loop like this:</p> | |
750 | <pre><code>{loop="$plugin_variable"} | |
751 | {$value} | |
752 | {/loop} | |
753 | </code></pre> | |
754 | <p>You should enable <code>demo_plugin</code> for testing purpose, since it uses every placeholder available.</p> | |
755 | <h3 id="list-of-placeholders">List of placeholders</h3> | |
756 | <p><strong>page.header.html</strong></p> | |
757 | <p>At the end of the menu:</p> | |
758 | <pre><code>{loop="$plugins_header.buttons_toolbar"} | |
759 | {$value} | |
760 | {/loop} | |
761 | </code></pre> | |
762 | <p>At the end of file, before clearing floating blocks:</p> | |
763 | <pre><code>{if="!empty($plugin_errors) && isLoggedIn()"} | |
764 | <ul class="errors"> | |
765 | {loop="plugin_errors"} | |
766 | <li>{$value}</li> | |
767 | {/loop} | |
768 | </ul> | |
769 | {/if} | |
770 | </code></pre> | |
771 | <p><strong>includes.html</strong></p> | |
772 | <p>At the end of the file:</p> | |
773 | <pre><code class="html">{loop="$plugins_includes.css_files"} | |
774 | <link type="text/css" rel="stylesheet" href="{$value}#"/> | |
775 | {/loop} | |
776 | </code></pre> | |
777 | ||
778 | <p><strong>page.footer.html</strong></p> | |
779 | <p>At the end of your footer notes:</p> | |
780 | <pre><code class="html">{loop="$plugins_footer.text"} | |
781 | {$value} | |
782 | {/loop} | |
783 | </code></pre> | |
784 | ||
785 | <p>At the end of file:</p> | |
786 | <pre><code class="html">{loop="$plugins_footer.js_files"} | |
787 | <script src="{$value}#"></script> | |
788 | {/loop} | |
789 | </code></pre> | |
790 | ||
791 | <p><strong>linklist.html</strong></p> | |
792 | <p>After search fields:</p> | |
793 | <pre><code class="html">{loop="$plugins_header.fields_toolbar"} | |
794 | {$value} | |
795 | {/loop} | |
796 | </code></pre> | |
797 | ||
798 | <p>Before displaying the link list (after paging):</p> | |
799 | <pre><code class="html">{loop="$plugin_start_zone"} | |
800 | {$value} | |
801 | {/loop} | |
802 | </code></pre> | |
803 | ||
804 | <p>For every links (icons):</p> | |
805 | <pre><code class="html">{loop="$value.link_plugin"} | |
806 | <span>{$value}</span> | |
807 | {/loop} | |
808 | </code></pre> | |
809 | ||
810 | <p>Before end paging:</p> | |
811 | <pre><code class="html">{loop="$plugin_end_zone"} | |
812 | {$value} | |
813 | {/loop} | |
814 | </code></pre> | |
815 | ||
816 | <p><strong>linklist.paging.html</strong></p> | |
817 | <p>After the "private only" icon:</p> | |
818 | <pre><code class="html">{loop="$action_plugin"} | |
819 | {$value} | |
820 | {/loop} | |
821 | </code></pre> | |
822 | ||
823 | <p><strong>editlink.html</strong></p> | |
824 | <p>After tags field:</p> | |
825 | <pre><code class="html">{loop="$edit_link_plugin"} | |
826 | {$value} | |
827 | {/loop} | |
828 | </code></pre> | |
829 | ||
830 | <p><strong>tools.html</strong></p> | |
831 | <p>After the last tool:</p> | |
832 | <pre><code class="html">{loop="$tools_plugin"} | |
833 | {$value} | |
834 | {/loop} | |
835 | </code></pre> | |
836 | ||
837 | <p><strong>picwall.html</strong></p> | |
838 | <p>Top:</p> | |
839 | <pre><code class="html"><div id="plugin_zone_start_picwall" class="plugin_zone"> | |
840 | {loop="$plugin_start_zone"} | |
841 | {$value} | |
842 | {/loop} | |
843 | </div> | |
844 | </code></pre> | |
845 | ||
846 | <p>Bottom:</p> | |
847 | <pre><code class="html"><div id="plugin_zone_end_picwall" class="plugin_zone"> | |
848 | {loop="$plugin_end_zone"} | |
849 | {$value} | |
850 | {/loop} | |
851 | </div> | |
852 | </code></pre> | |
853 | ||
854 | <p><strong>tagcloud.html</strong></p> | |
855 | <p>Top:</p> | |
856 | <pre><code class="html"> <div id="plugin_zone_start_tagcloud" class="plugin_zone"> | |
857 | {loop="$plugin_start_zone"} | |
858 | {$value} | |
859 | {/loop} | |
860 | </div> | |
861 | </code></pre> | |
862 | ||
863 | <p>Bottom:</p> | |
864 | <pre><code class="html"> <div id="plugin_zone_end_tagcloud" class="plugin_zone"> | |
865 | {loop="$plugin_end_zone"} | |
866 | {$value} | |
867 | {/loop} | |
868 | </div> | |
869 | </code></pre> | |
870 | ||
871 | <p><strong>daily.html</strong></p> | |
872 | <p>Top:</p> | |
873 | <pre><code class="html"><div id="plugin_zone_start_picwall" class="plugin_zone"> | |
874 | {loop="$plugin_start_zone"} | |
875 | {$value} | |
876 | {/loop} | |
877 | </div> | |
878 | </code></pre> | |
879 | ||
880 | <p>After every link:</p> | |
881 | <pre><code class="html"><div class="dailyEntryFooter"> | |
882 | {loop="$link.link_plugin"} | |
883 | {$value} | |
884 | {/loop} | |
885 | </div> | |
886 | </code></pre> | |
887 | ||
888 | <p>Bottom:</p> | |
889 | <pre><code class="html"><div id="plugin_zone_end_picwall" class="plugin_zone"> | |
890 | {loop="$plugin_end_zone"} | |
891 | {$value} | |
892 | {/loop} | |
893 | </div> | |
894 | </code></pre> | |
895 | ||
896 | <p><strong>feed.atom.xml</strong> and <strong>feed.rss.xml</strong>:</p> | |
897 | <p>In headers tags section:</p> | |
898 | <pre><code class="xml">{loop="$feed_plugins_header"} | |
899 | {$value} | |
900 | {/loop} | |
901 | </code></pre> | |
902 | ||
903 | <p>After each entry:</p> | |
904 | <pre><code class="xml">{loop="$value.feed_plugins"} | |
905 | {$value} | |
906 | {/loop} | |
907 | </code></pre> | |
908 | ||
909 | </div> | |
910 | </div> | |
911 | <footer> | |
912 | ||
913 | <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation"> | |
914 | ||
915 | <a href="../Release-Shaarli/" class="btn btn-neutral float-right" title="Release Shaarli">Next <span class="icon icon-circle-arrow-right"></span></a> | |
916 | ||
917 | ||
918 | <a href="../3rd-party-libraries/" class="btn btn-neutral" title="3rd party libraries"><span class="icon icon-circle-arrow-left"></span> Previous</a> | |
919 | ||
920 | </div> | |
921 | ||
922 | ||
923 | <hr/> | |
924 | ||
925 | <div role="contentinfo"> | |
926 | <!-- Copyright etc --> | |
927 | ||
928 | </div> | |
929 | ||
930 | Built with <a href="http://www.mkdocs.org">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. | |
931 | </footer> | |
932 | ||
933 | </div> | |
934 | </div> | |
935 | ||
936 | </section> | |
937 | ||
938 | </div> | |
939 | ||
940 | <div class="rst-versions" role="note" style="cursor: pointer"> | |
941 | <span class="rst-current-version" data-toggle="rst-current-version"> | |
942 | ||
943 | <a href="https://github.com/shaarli/Shaarli" class="fa fa-github" style="float: left; color: #fcfcfc"> GitHub</a> | |
944 | ||
945 | ||
946 | <span><a href="../3rd-party-libraries/" style="color: #fcfcfc;">« Previous</a></span> | |
947 | ||
948 | ||
949 | <span style="margin-left: 15px"><a href="../Release-Shaarli/" style="color: #fcfcfc">Next »</a></span> | |
950 | ||
951 | </span> | |
952 | </div> | |
953 | <script src="../js/theme.js"></script> | |
954 | ||
955 | </body> | |
956 | </html> |