aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/Plugin-System.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/Plugin-System.html')
-rw-r--r--doc/Plugin-System.html117
1 files changed, 105 insertions, 12 deletions
diff --git a/doc/Plugin-System.html b/doc/Plugin-System.html
index 655536c6..123bf106 100644
--- a/doc/Plugin-System.html
+++ b/doc/Plugin-System.html
@@ -69,6 +69,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
69<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li> 69<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
70<li><a href="Firefox-share.html">Firefox share</a></li> 70<li><a href="Firefox-share.html">Firefox share</a></li>
71<li><a href="RSS-feeds.html">RSS feeds</a></li> 71<li><a href="RSS-feeds.html">RSS feeds</a></li>
72<li><a href="REST-API.html">REST API</a></li>
72</ul></li> 73</ul></li>
73<li>How To 74<li>How To
74<ul> 75<ul>
@@ -87,6 +88,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
87<li><a href="3rd-party-libraries.html">3rd party libraries</a></li> 88<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
88<li><a href="Plugin-System.html">Plugin System</a></li> 89<li><a href="Plugin-System.html">Plugin System</a></li>
89<li><a href="Release-Shaarli.html">Release Shaarli</a></li> 90<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
91<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
90<li><a href="Security.html">Security</a></li> 92<li><a href="Security.html">Security</a></li>
91<li><a href="Static-analysis.html">Static analysis</a></li> 93<li><a href="Static-analysis.html">Static analysis</a></li>
92<li><a href="Theming.html">Theming</a></li> 94<li><a href="Theming.html">Theming</a></li>
@@ -100,9 +102,6 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
100</ul> 102</ul>
101</div> 103</div>
102<h1 id="plugin-system">Plugin System</h1> 104<h1 id="plugin-system">Plugin System</h1>
103<blockquote>
104<p>Note: Plugin current status - in development (not merged into master).</p>
105</blockquote>
106<p><a href="#developer-api"><strong>I am a developer.</strong> Developer API.</a><a href=".html"></a></p> 105<p><a href="#developer-api"><strong>I am a developer.</strong> Developer API.</a><a href=".html"></a></p>
107<p><a href="#guide-for-template-designer"><strong>I am a template designer.</strong> Guide for template designer.</a><a href=".html"></a></p> 106<p><a href="#guide-for-template-designer"><strong>I am a template designer.</strong> Guide for template designer.</a><a href=".html"></a></p>
108<h2 id="developer-api">Developer API</h2> 107<h2 id="developer-api">Developer API</h2>
@@ -121,12 +120,21 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
121| plugins/ 120| plugins/
122|---| demo_plugin/ 121|---| demo_plugin/
123| |---| demo_plugin.php</code></pre> 122| |---| demo_plugin.php</code></pre>
123<h3 id="plugin-initialization">Plugin initialization</h3>
124<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>
125<pre><code>&lt;plugin_name&gt;_init($conf)</code></pre>
126<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>
124<h3 id="understanding-hooks">Understanding hooks</h3> 127<h3 id="understanding-hooks">Understanding hooks</h3>
125<p>A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.</p> 128<p>A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.</p>
126<p>These functions need to be named with this pattern:</p> 129<p>These functions need to be named with this pattern:</p>
127<pre><code>hook_&lt;plugin_name&gt;_&lt;hook_name&gt;</code></pre> 130<pre><code>hook_&lt;plugin_name&gt;_&lt;hook_name&gt;($data, $conf)</code></pre>
131<p>Parameters:</p>
132<ul>
133<li>data: see <a href="https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data">$data section</a><a href=".html"></a></li>
134<li>conf: the <code>ConfigManager</code> instance.</li>
135</ul>
128<p>For exemple, if my plugin want to add data to the header, this function is needed:</p> 136<p>For exemple, if my plugin want to add data to the header, this function is needed:</p>
129<pre><code>hook_demo_plugin_render_header()</code></pre> 137<pre><code>hook_demo_plugin_render_header</code></pre>
130<p>If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.</p> 138<p>If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.</p>
131<h3 id="plugins-data">Plugin's data</h3> 139<h3 id="plugins-data">Plugin's data</h3>
132<h4 id="parameters">Parameters</h4> 140<h4 id="parameters">Parameters</h4>
@@ -159,6 +167,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
159<ul> 167<ul>
160<li><code>description</code>: plugin description</li> 168<li><code>description</code>: plugin description</li>
161<li><code>parameters</code>: user parameter names, separated by a <code>;</code>.</li> 169<li><code>parameters</code>: user parameter names, separated by a <code>;</code>.</li>
170<li><code>parameter.&lt;PARAMETER_NAME&gt;</code>: add a text description the specified parameter.</li>
162</ul> 171</ul>
163<blockquote> 172<blockquote>
164<p>Note: In PHP, <code>parse_ini_file()</code> seems to want strings to be between by quotes <code>&quot;</code> in the ini file.</p> 173<p>Note: In PHP, <code>parse_ini_file()</code> seems to want strings to be between by quotes <code>&quot;</code> in the ini file.</p>
@@ -209,16 +218,28 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
209</tr> 218</tr>
210<tr class="even"> 219<tr class="even">
211<td><a href="#render_tagcloud">render_tagcloud</a></td> 220<td><a href="#render_tagcloud">render_tagcloud</a></td>
212<td style="text-align: center;">Allow to add content at the top and bottom of the page.</td> 221<td style="text-align: center;">Allow to add content at the top and bottom of the page, and after all tags.</td>
213</tr> 222</tr>
214<tr class="odd"> 223<tr class="odd">
224<td><a href="#render_taglist">render_taglist</a></td>
225<td style="text-align: center;">Allow to add content at the top and bottom of the page, and after all tags.</td>
226</tr>
227<tr class="even">
215<td><a href="#render_daily">render_daily</a></td> 228<td><a href="#render_daily">render_daily</a></td>
216<td style="text-align: center;">Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.</td> 229<td style="text-align: center;">Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.</td>
217</tr> 230</tr>
231<tr class="odd">
232<td><a href="#render_feed">render_feed</a></td>
233<td style="text-align: center;">Allow to do add tags in RSS and ATOM feeds.</td>
234</tr>
218<tr class="even"> 235<tr class="even">
219<td><a href="#savelink">savelink</a></td> 236<td><a href="#save_link">save_link</a></td>
220<td style="text-align: center;">Allow to alter the link being saved in the datastore.</td> 237<td style="text-align: center;">Allow to alter the link being saved in the datastore.</td>
221</tr> 238</tr>
239<tr class="odd">
240<td><a href="#delete_link">delete_link</a></td>
241<td style="text-align: center;">Allow to do an action before a link is deleted from the datastore.</td>
242</tr>
222</tbody> 243</tbody>
223</table> 244</table>
224<h4 id="render_header">render_header</h4> 245<h4 id="render_header">render_header</h4>
@@ -376,17 +397,41 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
376<li><p><code>plugin_start_zone</code>: before displaying the template content.</p></li> 397<li><p><code>plugin_start_zone</code>: before displaying the template content.</p></li>
377<li><p><code>plugin_end_zone</code>: after displaying the template content.</p></li> 398<li><p><code>plugin_end_zone</code>: after displaying the template content.</p></li>
378</ul> 399</ul>
400<p>For each tag, the following placeholder can be used:</p>
401<ul>
402<li><code>tag_plugin</code>: after each tag</li>
403</ul>
379<p><img src="http://i.imgur.com/vHmyT3a.png" alt="plugin_start_end_zone_example" /><a href=".html"></a></p> 404<p><img src="http://i.imgur.com/vHmyT3a.png" alt="plugin_start_end_zone_example" /><a href=".html"></a></p>
405<h4 id="render_taglist">render_taglist</h4>
406<p>Triggered when taglist is displayed.</p>
407<p>Allow to add content at the top and bottom of the page.</p>
408<h5 id="data-8">Data</h5>
409<p><code>$data</code> is an array containing:</p>
410<ul>
411<li><code>_LOGGEDIN_</code>: true if user is logged in, false otherwise.</li>
412<li>All templates data.</li>
413</ul>
414<h5 id="template-placeholders-8">Template placeholders</h5>
415<p>Items can be displayed in templates by adding an entry in <code>$data['&lt;placeholder&gt;']</code> array.<a href=".html"></a></p>
416<p>List of placeholders:</p>
417<ul>
418<li><p><code>plugin_start_zone</code>: before displaying the template content.</p></li>
419<li><p><code>plugin_end_zone</code>: after displaying the template content.</p></li>
420</ul>
421<p>For each tag, the following placeholder can be used:</p>
422<ul>
423<li><code>tag_plugin</code>: after each tag</li>
424</ul>
380<h4 id="render_daily">render_daily</h4> 425<h4 id="render_daily">render_daily</h4>
381<p>Triggered when tagcloud is displayed.</p> 426<p>Triggered when tagcloud is displayed.</p>
382<p>Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.</p> 427<p>Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.</p>
383<h5 id="data-8">Data</h5> 428<h5 id="data-9">Data</h5>
384<p><code>$data</code> is an array containing:</p> 429<p><code>$data</code> is an array containing:</p>
385<ul> 430<ul>
386<li><code>_LOGGEDIN_</code>: true if user is logged in, false otherwise.</li> 431<li><code>_LOGGEDIN_</code>: true if user is logged in, false otherwise.</li>
387<li>All templates data, including links.</li> 432<li>All templates data, including links.</li>
388</ul> 433</ul>
389<h5 id="template-placeholders-8">Template placeholders</h5> 434<h5 id="template-placeholders-9">Template placeholders</h5>
390<p>Items can be displayed in templates by adding an entry in <code>$data['&lt;placeholder&gt;']</code> array.<a href=".html"></a></p> 435<p>Items can be displayed in templates by adding an entry in <code>$data['&lt;placeholder&gt;']</code> array.<a href=".html"></a></p>
391<p>List of placeholders:</p> 436<p>List of placeholders:</p>
392<ul> 437<ul>
@@ -397,18 +442,57 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
397<li><p><code>plugin_start_zone</code>: before displaying the template content.</p></li> 442<li><p><code>plugin_start_zone</code>: before displaying the template content.</p></li>
398<li><p><code>plugin_end_zone</code>: after displaying the template content.</p></li> 443<li><p><code>plugin_end_zone</code>: after displaying the template content.</p></li>
399</ul> 444</ul>
400<h4 id="savelink">savelink</h4> 445<h4 id="render_feed">render_feed</h4>
446<p>Triggered when the ATOM or RSS feed is displayed.</p>
447<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>
448<h5 id="data-10">Data</h5>
449<p><code>$data</code> is an array containing:</p>
450<ul>
451<li><code>_LOGGEDIN_</code>: true if user is logged in, false otherwise.</li>
452<li><code>_PAGE_</code>: containing either <code>rss</code> or <code>atom</code>.</li>
453<li>All templates data, including links.</li>
454</ul>
455<h5 id="template-placeholders-10">Template placeholders</h5>
456<p>Tags can be added in feeds by adding an entry in <code>$data['&lt;placeholder&gt;']</code> array.<a href=".html"></a></p>
457<p>List of placeholders:</p>
458<ul>
459<li><code>feed_plugins_header</code>: used as a header tag in the feed.</li>
460</ul>
461<p>For each links:</p>
462<ul>
463<li><code>feed_plugins</code>: additional tag for every link entry.</li>
464</ul>
465<h4 id="save_link">save_link</h4>
401<p>Triggered when a link is save (new link or edit).</p> 466<p>Triggered when a link is save (new link or edit).</p>
402<p>Allow to alter the link being saved in the datastore.</p> 467<p>Allow to alter the link being saved in the datastore.</p>
403<h5 id="data-9">Data</h5> 468<h5 id="data-11">Data</h5>
404<p><code>$data</code> is an array containing the link being saved:</p> 469<p><code>$data</code> is an array containing the link being saved:</p>
405<ul> 470<ul>
471<li>id</li>
406<li>title</li> 472<li>title</li>
407<li>url</li> 473<li>url</li>
474<li>shorturl</li>
408<li>description</li> 475<li>description</li>
409<li>linkdate</li>
410<li>private</li> 476<li>private</li>
411<li>tags</li> 477<li>tags</li>
478<li>created</li>
479<li>updated</li>
480</ul>
481<h4 id="delete_link">delete_link</h4>
482<p>Triggered when a link is deleted.</p>
483<p>Allow to execute any action before the link is actually removed from the datastore</p>
484<h5 id="data-12">Data</h5>
485<p><code>$data</code> is an array containing the link being saved:</p>
486<ul>
487<li>id</li>
488<li>title</li>
489<li>url</li>
490<li>shorturl</li>
491<li>description</li>
492<li>private</li>
493<li>tags</li>
494<li>created</li>
495<li>updated</li>
412</ul> 496</ul>
413<h2 id="guide-for-template-designer">Guide for template designer</h2> 497<h2 id="guide-for-template-designer">Guide for template designer</h2>
414<h3 id="plugin-administration">Plugin administration</h3> 498<h3 id="plugin-administration">Plugin administration</h3>
@@ -537,5 +621,14 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
537 {$value} 621 {$value}
538 {/loop} 622 {/loop}
539<span class="kw">&lt;/div&gt;</span></code></pre></div> 623<span class="kw">&lt;/div&gt;</span></code></pre></div>
624<p><strong>feed.atom.xml</strong> and <strong>feed.rss.xml</strong>:</p>
625<p>In headers tags section:</p>
626<div class="sourceCode"><pre class="sourceCode xml"><code class="sourceCode xml">{loop=&quot;$feed_plugins_header&quot;}
627 {$value}
628{/loop}</code></pre></div>
629<p>After each entry:</p>
630<div class="sourceCode"><pre class="sourceCode xml"><code class="sourceCode xml">{loop=&quot;$value.feed_plugins&quot;}
631 {$value}
632{/loop}</code></pre></div>
540</body> 633</body>
541</html> 634</html>