X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=doc%2FPlugin-System.html;h=655536c60cc32190b5ada615202172408162c48d;hb=fdf88d194874a533cf3a8de3d317d70018aa8a62;hp=cb1cb7464bbd3fb4066643379be41a64a5b4379c;hpb=f8b936e7e75601b5d96525f25d5b52dbabd909b4;p=github%2Fshaarli%2FShaarli.git diff --git a/doc/Plugin-System.html b/doc/Plugin-System.html index cb1cb746..655536c6 100644 --- a/doc/Plugin-System.html +++ b/doc/Plugin-System.html @@ -4,46 +4,69 @@ -
--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.
-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',
-);
-Plugin maintained by the community:
-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
-
+
+
+
+
+
-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.
@@ -259,6 +276,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
List of placeholders:
text
: called after the end of the footer text.
+endofpage
: called at the end of the page.
@@ -393,6 +411,20 @@ code > span.er { color: #ff0000; font-weight: bold; }
- 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:
@@ -406,96 +438,104 @@ code > span.er { color: #ff0000; font-weight: bold; }
{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>