From 5409ade28c5f0acf99dbadd4d95e6f8efda5d395 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Thu, 14 Apr 2016 14:20:23 +0200 Subject: Update docs from Wiki --- doc/Plugin-System.html | 222 +++++++++++++++++++++++++++++-------------------- 1 file changed, 132 insertions(+), 90 deletions(-) (limited to 'doc/Plugin-System.html') diff --git a/doc/Plugin-System.html b/doc/Plugin-System.html index cb1cb746..2a660c49 100644 --- a/doc/Plugin-System.html +++ b/doc/Plugin-System.html @@ -4,31 +4,49 @@ - Shaarli - Plugin System + Shaarli – Plugin System - +

Plugin System

-
Note: Plugin current status - in developpement (not merged into master).
+
Note: Plugin current status - in development (not merged into master).

I am a user. Plugin User Guide.

I am a developper. Developper API.

I am a developer. Developer API.

I am a template designer. Guide for template designer.

Plugin User Guide

Manage plugins

In config.php, change $GLOBALS'config'['ENABLED_PLUGINS'] array:

$GLOBALS['config'['ENABLED_PLUGINS']]('ENABLED_PLUGINS'].html)

Full list:

$GLOBALS['config'['ENABLED_PLUGINS'] = array(]('ENABLED_PLUGINS']-=-array(.html)
-    'qrcode', 'archiveorg', 'readityourself', 'playvideos',
-    'wallabag', 'markdown', 'addlink_toolbar',
-);

List of plugins

Plugin maintained by the community:

Archive.org - add a clickable icon to every link to archive.org.
Addlink in toolbar - add a field to paste new links URL in toolbar.
Markdown - write and display Shaare in Markdown.
Play videos - popup to play all videos displayed in linklist.
QRCode - add a clickable icon generating a QRCode for every link.
ReadItYourself - add a clickable icon for ReadItYourself.
Wallabag - add a clickable icon for Wallabag.

Developper API

Developer API

What can I do with plugins?

The plugin system let you:

Template placeholders are displayed in template in specific places.

RainTPL displays every element contained in the placeholder's array. These element can be added by plugins.

For example, let's add a value in the placeholder top_placeholder which is displayed at the top of my page:

$data['top_placeholder'[] = 'My content';](]-=-'My-content';.html)
+$data['top_placeholder'[] = 'My content';](]-=-'My-content';.html)
 # OR
 array_push($data['top_placeholder'], 'My', 'content');[](.html)
 
-return $data;
+return $data;

Data manipulation

When a page is displayed, every variable send to the template engine is passed to plugins before that in $data.

The data contained by this array can be altered before template rendering.

For exemple, in linklist, it is possible to alter every title:

// mind the reference if you want $data to be altered
+// mind the reference if you want $data to be altered
 foreach ($data['links'] as &$value) {[](.html)
     // String reverse every title.
     $value['title'] = strrev($value['title']);[](.html)
 }
 
-return $data;
+return $data;

Metadata

Every plugin needs a <plugin_name>.meta file, which is in fact an .ini file (KEY="VALUE"), to be listed in plugin administration.

Each file contain two keys:

description: plugin description
parameters: user parameter names, separated by a ;.

+
Note: In PHP, parse_ini_file() seems to want strings to be between by quotes " in the ini file.
+

It's not working!

Use demo_plugin as a functional example. It covers most of the plugin system features.

If it's still not working, please open an issue.

Hooks

tags

Guide for template designer

Plugin administration

Your theme must include a plugin administration page: pluginsadmin.html.

+
Note: repo's template link needs to be added when the PR is merged.
+

Use the default one as an example.

Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include plugin_admin.js, only if:

you're using a table.
you call orderUp() and orderUp() onclick on arrows.
you add data-line and data-order to your rows.

Otherwise, you can use your own JS as long as this field is send by the form:

Placeholder system

In order to make plugins work with every custom themes, you need to add variable placeholder in your templates.

It's a RainTPL loop like this:

{loop="$plugins_header.buttons_toolbar"}
     {$value}
 {/loop}

At the end of file, before clearing floating blocks:

{if="!empty($plugin_errors) && isLoggedIn()"}
+    <ul class="errors">
+        {loop="plugin_errors"}
+            <li>{$value}</li>
+        {/loop}
+    </ul>
+{/if}

includes.html

At the end of the file:

{loop="$plugins_includes.css_files"}
+{loop="$plugins_includes.css_files"}
 <link type="text/css" rel="stylesheet" href="{$value}#"/>
-{/loop}
+{/loop}

page.footer.html

At the end of your footer notes:

{loop="$plugins_footer.text"}
+{loop="$plugins_footer.text"}
      {$value}
-{/loop}
+{/loop}

At the end of file:

{loop="$plugins_footer.js_files"}
+{loop="$plugins_footer.js_files"}
      <script src="{$value}#"></script>
-{/loop}
+{/loop}

linklist.html

After search fields:

{loop="$plugins_header.fields_toolbar"}
+{loop="$plugins_header.fields_toolbar"}
      {$value}
-{/loop}
+{/loop}

Before displaying the link list (after paging):

{loop="$plugin_start_zone"}
+{loop="$plugin_start_zone"}
      {$value}
-{/loop}
+{/loop}

For every links (icons):

{loop="$value.link_plugin"}
+{loop="$value.link_plugin"}
     <span>{$value}</span>
-{/loop}
+{/loop}

Before end paging:

{loop="$plugin_end_zone"}
+{loop="$plugin_end_zone"}
      {$value}
-{/loop}
+{/loop}

linklist.paging.html

After the "private only" icon:

{loop="$action_plugin"}
+{loop="$action_plugin"}
      {$value}
-{/loop}
+{/loop}

editlink.html

After tags field:

{loop="$edit_link_plugin"}
+{loop="$edit_link_plugin"}
      {$value}
-{/loop}
+{/loop}

tools.html

After the last tool:

{loop="$tools_plugin"}
+{loop="$tools_plugin"}
      {$value}
-{/loop}
+{/loop}

picwall.html

Top:

<div id="plugin_zone_start_picwall" class="plugin_zone">
+<div id="plugin_zone_start_picwall" class="plugin_zone">
     {loop="$plugin_start_zone"}
         {$value}
     {/loop}
-</div>
+</div>

Bottom:

<div id="plugin_zone_end_picwall" class="plugin_zone">
+<div id="plugin_zone_end_picwall" class="plugin_zone">
     {loop="$plugin_end_zone"}
         {$value}
     {/loop}
-</div>
+</div>

tagcloud.html

Top:

   <div id="plugin_zone_start_tagcloud" class="plugin_zone">
+   <div id="plugin_zone_start_tagcloud" class="plugin_zone">
         {loop="$plugin_start_zone"}
             {$value}
         {/loop}
-    </div>
+    </div>

Bottom:

    <div id="plugin_zone_end_tagcloud" class="plugin_zone">
+    <div id="plugin_zone_end_tagcloud" class="plugin_zone">
         {loop="$plugin_end_zone"}
             {$value}
         {/loop}
-    </div>
+    </div>

daily.html

Top:

<div id="plugin_zone_start_picwall" class="plugin_zone">
+<div id="plugin_zone_start_picwall" class="plugin_zone">
      {loop="$plugin_start_zone"}
          {$value}
      {/loop}
-</div>
+</div>

After every link:

<div class="dailyEntryFooter">
+<div class="dailyEntryFooter">
      {loop="$link.link_plugin"}
           {$value}
      {/loop}
-</div>
+</div>

Bottom:

<div id="plugin_zone_end_picwall" class="plugin_zone">
+<div id="plugin_zone_end_picwall" class="plugin_zone">
     {loop="$plugin_end_zone"}
         {$value}
     {/loop}
-</div>
+</div>

Hooks	Hooks	Description
render_header	render_header	Allow plugin to add content in page headers.
render_includes	render_includes	Allow plugin to include their own CSS files.
render_footer	render_footer	Allow plugin to add content in page footer and include their own JS files.
render_linklist	render_linklist	It allows to add content at the begining and end of the page, after every link displayed and to alter link data.
render_editlink	render_editlink	Allow to add fields in the form, or display elements.
render_tools	render_tools	Allow to add content at the end of the page.
render_picwall	render_picwall	Allow to add content at the top and bottom of the page.
render_tagcloud	render_tagcloud	Allow to add content at the top and bottom of the page.
render_daily	render_daily	Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.
savelink	savelink	Allow to alter the link being saved in the datastore.