tplinc Plugin

Compatible with DokuWiki

2023-04-04 "Jack Jackrum" unknown
2022-07-31 "Igor" unknown
2020-07-29 "Hogfather" unknown
2018-04-22 "Greebo" yes

Provide a flexible page include mechanism to DokuWiki templates

Last updated on: 2023-01-03
Provides: Helper, Admin
Repository: Source

Similar to include

Tagged with include

By Andreas Gohr

This plugin allows template authors to define areas in the template where additional content can be included. Users of that template can then use this plugin to define which logic should be used to determine the content (pages) that should be included depending on the current page.

This is similar to how the sidebar works in the default template, only much more flexible. It is also possible to include multiple pages in the same area (one after another).

Installation

Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

The plugin needs a suitable template to provide hooks to which it can include the pages! So far, the following templates include such hooks:

sprintdoc

You can use this plugin with templates that use traditional include hooks, by calling the plugin from within those hook files. For the DokuWiki Template you can simply use the hookfiles distributed with this plugin. To do so copy all the files within the dokuwiki directory of this plugin to your wiki's conf directory. This will make all the supported Include Hooks available as hooks within this plugin.

cp lib/plugins/tplinc/dokuwiki/* conf/

Configuration and Settings

To configure, select “Template Includes” in the admin menu. Each include rule consists of four configs:

Pattern – this is a pattern that is matched against the currently shown page, when it matches, the rule is applied
Page – this is the page to include when the pattern matches
Location – this is where the page will be shown in the template, the available areas are set by the used template
Skip ACL – unless this box is ticked, only page the current user may read are included

As pattern you can use the following:

For a single page just specify its full page id
For namespaces excluding subnamespaces use namespace:*
For namespaces including subnamespaces use namespace:**
Regular Expressions can be used starting and ending with / - they are matched against a : prefixed full page id

Pages can optionally be given as relative IDs and will be resolved against the current page's namespace. When matching regular expressions, matched groups can be reused in the inserted page name by referencing them as $0, $1, …, $n.

Rules can be reordered by drag'n'drop.

Development

If you're a template author and want to integrate this plugin in your template, here is how you do it:

Announcing available Include Locations

You need to announce which locations are available in your template by registering a BEFORE handler for the PLUGIN_TPLINC_LOCATIONS_SET. The $event->data is an associative array with location identifiers and their user readable descriptions.

Please refer to Action Plugins to learn more.

Here's an example handler:

lib/tpl/example/TplIncludeHandler.php

<?php
namespace dokuwiki\template\example;
 
class TplIncludeHandler {
    public function __construct() {
        /** @var \Doku_Event_Handler */
        global $EVENT_HANDLER;
        $EVENT_HANDLER->register_hook('PLUGIN_TPLINC_LOCATIONS_SET', 'BEFORE', $this, 'registerIncludes');
    }
 
    public function registerIncludes(\Doku_Event $event) {
        $event->data['footer'] = 'Footer below the page content';
        $event->data['sidebarfooter'] = 'Footer below the sidebar';
        $event->data['sidebarheader'] = 'Header above the sidebar';
    }
}

You'd call this handler at the beginning of your main.php:

lib/tpl/example/main.php

<?php
new dokuwiki\template\example\TplIncludeHandler();
 
... main code follows

Be sure the PHP namespaces match your template name.

Using Includes

At the places where you want to allow users to include pages, use the following code:

$tplinc = plugin_load('helper', 'tplinc');
if($tplinc) echo $tplinc->renderIncludes('footer');

The footer string in the example above refers to one of the location identifiers announced earlier.

Commit-Ticker

Version upped (2023-01-03 23:51)
code cleanup, php8 compatibility (2023-01-03 14:07)
Version upped (2019-03-21 23:53)
fix testing (2019-03-21 10:01)
Version upped (2019-03-12 23:53)
Merge pull request #1 from LotarProject/master (2019-03-12 16:58)
Removed duplicated action attribute (2019-03-12 16:36)
Version upped (2018-07-02 23:53)

Releases:

2023-01-03 by splitbrain
Version upped
2019-03-21 by splitbrain
Version upped
2019-03-12 by splitbrain
Version upped
2018-07-02 by splitbrain
Version upped
2018-06-12 by splitbrain
Version upped
2017-03-28 by splitbrain
initial (untested) commit

Table of Contents