From 53ed6d7d1e678d7486337ce67a2f17b30bac21ac Mon Sep 17 00:00:00 2001 From: nodiscc Date: Thu, 26 Jan 2017 18:52:54 +0100 Subject: Generate HTML documentation using MkDocs (WIP) MkDocs is a static site generator geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML file. * http://www.mkdocs.org/ * http://www.mkdocs.org/user-guide/configuration/ Ref. #312 * remove pandoc-generated HTML documentation * move markdown doc to doc/md/, * mkdocs.yml: * generate HTML doc in doc/html * add pages TOC/ordering * use index.md as index page * Makefile: remove execute permissions from generated files * Makefile: rewrite htmlpages GFM to markdown conversion using sed: awk expression aslo matched '][' which causes invalid output on complex links with images or code blocks * Add mkdocs.yml to .gitattributes, exclude this file from release archives * Makefile: rename: htmldoc -> doc_html target * run make doc: pull latest markdown documentation from wiki * run make htmlpages: update html documentation --- doc/Plugin-System.html | 634 ------------------------------------------------- 1 file changed, 634 deletions(-) delete mode 100644 doc/Plugin-System.html (limited to 'doc/Plugin-System.html') diff --git a/doc/Plugin-System.html b/doc/Plugin-System.html deleted file mode 100644 index 123bf106..00000000 --- a/doc/Plugin-System.html +++ /dev/null @@ -1,634 +0,0 @@ - - - - - - - Shaarli – Plugin System - - - - - - -
- -
-

Plugin System

-

I am a developer. Developer API.

-

I am a template designer. Guide for template designer.

-

Developer API

-

What can I do with plugins?

-

The plugin system let you:

- -

How can I create a plugin for Shaarli?

-

First, chose a plugin name, such as demo_plugin.

-

Under plugin folder, create a folder named with your plugin name. Then create a .php file in that folder.

-

You should have the following tree view:

-
| index.php
-| plugins/
-|---| demo_plugin/
-|   |---| demo_plugin.php
-

Plugin initialization

-

At the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an init() function to execute and run it if it exists. This function must be named this way, and takes the ConfigManager as parameter.

-
<plugin_name>_init($conf)
-

This function can be used to create initial data, load default settings, etc. But also to set plugin errors. If the initialization function returns an array of strings, they will be understand as errors, and displayed in the header to logged in users.

-

Understanding hooks

-

A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.

-

These functions need to be named with this pattern:

-
hook_<plugin_name>_<hook_name>($data, $conf)
-

Parameters:

- -

For exemple, if my plugin want to add data to the header, this function is needed:

-
hook_demo_plugin_render_header
-

If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.

-

Plugin's data

-

Parameters

-

Every hook function has a $data parameter. Its content differs for each hooks.

-

This parameter needs to be returned every time, otherwise data is lost.

-
return $data;
-

Filling templates placeholder

-

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)
-# OR
-array_push($data['top_placeholder'], 'My', 'content');[](.html)
-
-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
-foreach ($data['links'] as &$value) {[](.html)
-    // String reverse every title.
-    $value['title'] = strrev($value['title']);[](.html)
-}
-
-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:

- -
-

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

- ---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
HooksDescription
render_headerAllow plugin to add content in page headers.
render_includesAllow plugin to include their own CSS files.
render_footerAllow plugin to add content in page footer and include their own JS files.
render_linklistIt allows to add content at the begining and end of the page, after every link displayed and to alter link data.
render_editlinkAllow to add fields in the form, or display elements.
render_toolsAllow to add content at the end of the page.
render_picwallAllow to add content at the top and bottom of the page.
render_tagcloudAllow to add content at the top and bottom of the page, and after all tags.
render_taglistAllow to add content at the top and bottom of the page, and after all tags.
render_dailyAllow to add content at the top and bottom of the page, the bottom of each link and to alter data.
render_feedAllow to do add tags in RSS and ATOM feeds.
save_linkAllow to alter the link being saved in the datastore.
delete_linkAllow to do an action before a link is deleted from the datastore.
-

render_header

-

Triggered on every page.

-

Allow plugin to add content in page headers.

-
Data
-

$data is an array containing:

- -
Template placeholders
-

Items can be displayed in templates by adding an entry in $data['<placeholder>'] array.

-

List of placeholders:

- -

buttons_toolbar_example

- -
-

Note: This will only be called in linklist.

-
-

fields_toolbar_example

-

render_includes

-

Triggered on every page.

-

Allow plugin to include their own CSS files.

-
Data
-

$data is an array containing:

- -
Template placeholders
-

Items can be displayed in templates by adding an entry in $data['<placeholder>'] array.

-

List of placeholders:

- -
-

Note: only add the path of the CSS file. E.g: plugins/demo_plugin/custom_demo.css.

-
- -

Triggered on every page.

-

Allow plugin to add content in page footer and include their own JS files.

-
Data
-

$data is an array containing:

- -
Template placeholders
-

Items can be displayed in templates by adding an entry in $data['<placeholder>'] array.

-

List of placeholders:

- -

text_example

- -
-

Note: only add the path of the JS file. E.g: plugins/demo_plugin/custom_demo.js.

-
- -

Triggered when linklist is displayed (list of links, permalink, search, tag filtered, etc.).

-

It allows to add content at the begining and end of the page, after every link displayed and to alter link data.

-
Data
-

$data is an array containing:

- -
Template placeholders
-

Items can be displayed in templates by adding an entry in $data['<placeholder>'] array.

-

List of placeholders:

- -

action_plugin_example

- -

link_plugin_example

- -

plugin_start_zone_example

- -

plugin_end_zone_example

- -

Triggered when the link edition form is displayed.

-

Allow to add fields in the form, or display elements.

-
Data
-

$data is an array containing:

- -
Template placeholders
-

Items can be displayed in templates by adding an entry in $data['<placeholder>'] array.

-

List of placeholders:

- -

edit_link_plugin_example

-

render_tools

-

Triggered when the "tools" page is displayed.

-

Allow to add content at the end of the page.

-
Data
-

$data is an array containing:

- -
Template placeholders
-

Items can be displayed in templates by adding an entry in $data['<placeholder>'] array.

-

List of placeholders:

- -

tools_plugin_example

-

render_picwall

-

Triggered when picwall is displayed.

-

Allow to add content at the top and bottom of the page.

-
Data
-

$data is an array containing:

- -
Template placeholders
-

Items can be displayed in templates by adding an entry in $data['<placeholder>'] array.

-

List of placeholders:

- -

plugin_start_end_zone_example

-

render_tagcloud

-

Triggered when tagcloud is displayed.

-

Allow to add content at the top and bottom of the page.

-
Data
-

$data is an array containing:

- -
Template placeholders
-

Items can be displayed in templates by adding an entry in $data['<placeholder>'] array.

-

List of placeholders:

- -

For each tag, the following placeholder can be used:

- -

plugin_start_end_zone_example

-

render_taglist

-

Triggered when taglist is displayed.

-

Allow to add content at the top and bottom of the page.

-
Data
-

$data is an array containing:

- -
Template placeholders
-

Items can be displayed in templates by adding an entry in $data['<placeholder>'] array.

-

List of placeholders:

- -

For each tag, the following placeholder can be used:

- -

render_daily

-

Triggered when tagcloud is displayed.

-

Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.

-
Data
-

$data is an array containing:

- -
Template placeholders
-

Items can be displayed in templates by adding an entry in $data['<placeholder>'] array.

-

List of placeholders:

- -

link_plugin_example

- -

render_feed

-

Triggered when the ATOM or RSS feed is displayed.

-

Allow to add tags in the feed, either in the header or for each items. Items (links) can also be altered before being rendered.

-
Data
-

$data is an array containing:

- -
Template placeholders
-

Tags can be added in feeds by adding an entry in $data['<placeholder>'] array.

-

List of placeholders:

- -

For each links:

- - -

Triggered when a link is save (new link or edit).

-

Allow to alter the link being saved in the datastore.

-
Data
-

$data is an array containing the link being saved:

- - -

Triggered when a link is deleted.

-

Allow to execute any action before the link is actually removed from the datastore

-
Data
-

$data is an array containing the link being saved:

- -

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:

- -

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="$plugin_variable"}
-    {$value}
-{/loop}
-

You should enable demo_plugin for testing purpose, since it uses every placeholder available.

-

List of placeholders

-

page.header.html

-

At the end of the menu:

-
{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"}
-<link type="text/css" rel="stylesheet" href="{$value}#"/>
-{/loop}
-

page.footer.html

-

At the end of your footer notes:

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

At the end of file:

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

linklist.html

-

After search fields:

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

Before displaying the link list (after paging):

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

For every links (icons):

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

Before end paging:

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

linklist.paging.html

-

After the "private only" icon:

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

editlink.html

-

After tags field:

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

tools.html

-

After the last tool:

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

picwall.html

-

Top:

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

Bottom:

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

tagcloud.html

-

Top:

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

Bottom:

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

daily.html

-

Top:

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

After every link:

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

Bottom:

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

feed.atom.xml and feed.rss.xml:

-

In headers tags section:

-
{loop="$feed_plugins_header"}
-  {$value}
-{/loop}
-

After each entry:

-
{loop="$value.feed_plugins"}
-  {$value}
-{/loop}
- - -- cgit v1.2.3