Table of Contents
templateconfhelper Plugin
Compatible with DokuWiki
2014-09-29
This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.
Similar to loadskin, multitemplate_styleman
Needed for subconfhelper
Installation
This plugin helps developing and managing templates. It does not add any functionality by its own.
This is a beta release. The functions included or their use might be a security risk
Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.
Or checkout the source on GitHub:
git clone git://github.com/samfisch/dokuwiki-plugin-templateconfhelper.git templateconfhelper
Features
- template inheritance, templates can reference php and style files from other templates – inheritance
- template switcher action plugin, later version might include template tags or user-settings-page extension – templateaction
- template images via fetch.php – fetchaction
- cascading template path, templates can be stored outside dokuwiki directory if you use preload
Examples
An example template making use of css iheritance could look like this:
- style.ini
[stylesheets] layout.css = screen design.css = screen style.css = screen example.css = screen media.css = screen _mediaoptions.css = screen _admin.css = screen _linkwiz.css = screen _subscription.css = screen rtl.css = rtl print.css = print [replacements] ; main text color __text__ = "#F439CB"
- example.css
body .dokuwiki { font-size: 0.7em !important; }
Templateaction
Changes template based on users Selection via GET and saves it in the Session.
Parameter
$_GET[utpl] /^[\w-]+$/
– override template
Functions
get_user( $var=false )
– get utpl from sessionsave_session( $var, $false )
– save utpl to sessionsave_user( $var, $val )
– #DUMMYtpl_switch( $tpl )
– change style after init.php has been runtpl_loadconfig( $tpl )
– reload config for template, called on switch
Fetchaction
Uses FETCH_MEDIA_STATUS event to hook into fetch.php. This allows to have template files outside of webroot.
Parameter
$_GET[mode] styleimg
– trigger$_GET[template /^[\w-]*$/
– template dir to search for the file
a nginx rewrite rule to fix path used in templates
rewrite ^/lib/tpl/((.*)/)?images/(.*) /lib/exe/fetch.php?mode=styleimg&media=$3&template=$2 last;
or with nicer path
rewrite ^/_img/((.*)/)?(.*) /lib/exe/fetch.php?mode=styleimg&media=$3&template=$2 last;
Inheritance
The custom css.php
and the functions in inc/template.php
use following config settings to look up templatefiles. Files that dont exist in the active template are choosen from the next template in this order:
- template, existing dokuwiki template setting possibly overwritten by template switch
default_tpl
, automaticaly set dokuwiki template settingbase_tpl
, new config setting for fallback template
For the main.php
the default is hardcoded in DokuWiki. So for templates to overwrite the main.php
they have to exist in the DokuWiki lib/tpl/
directory. Fallback is always lib/tpl/default/
. This is a security feature as without a special template making use of e.g. the tpl_include
function no php code from the following cascade path is interpreted. (I think.)
Configuration
The base_tpl
can be configured using the DokuWiki configuration manager available in the admin menu.
base_tpl | The default template which is used if the file was not found in the page or user template |
---|
Cascade Path is an extension to the cascade config values in dokuwiki init. It can be set in preload.php
. The new template_path
setting allows to read templates from pathes outside dokuwiki code. E.g. per domain in farming environments.
The plugin has a hardcoded cascade path wich is used if the $cascade_path['template_dir']
setting is empty as it is in a default install.
$config_cascade['template_dir'] = array( // used in confutils 'default' => array( dirname( DOKU_TPLINC ).'/' ), );
Example
Example cascade path for inc/preload.php
$version = '/dokuwiki/' $farmdir = "$farmbasedir/domains/$animal/"; $config_cascade['template_dir'] = array( // used in templateconfig plugin 'default' => array( $farmbasedir.'/extension/tpl/', $farmbasedir.$version.'lib/tpl/' ), 'local' => array( $farmdir.'tpl/' ), #'protected' => array( $farmbasedir.'/extension/tpl_protected/' ), );
To allow animals to overwrite template php files a main.php
like this can be used in the default_tpl
or base_tpl
in dokuwiki lib/tpl/
directory. It will check the cascade path for a main.php
in the active template.
- main.php
<?php tpl_include( 'main.php' );
Preload
This is a rather creative apporach to hook into css.php
. The templateaction plugin class deffinition includes inc/preload.php
. Here css.php calls are intercepted and the custom css.php from the plugins exe directory is loaded.
If the template_path
cascade config has not been set. Defaults are made up for a standard dokuwiki setup.
Helper
ConfUtils
getConfigPath( $type, $file )
– find file incascade_config[$type]
Template
tpl_include( $file, $t=false )
– usegetConfigPath
to include file fromcascade_config['template_path']
, checks templates$t
,default_tpl
andbase_tpl
- … some undocumented and likely to change functions for use in templates
CSS
Include style.ini and css files based on inheritance. Makes use of default_tpl
, base_tpl
and getConfigPath( )
.
Changes
- clean ununsed template functions (2013-02-25 08:10)
- adora belle stable (2013-02-25 07:20)
- base_tpl precedence (2013-02-25 07:20)
- preload for js files (2013-02-25 07:20)
- Merge remote-tracking branch 'm3/develop' into develop (2012-10-03 04:03)
- dont create config path that was already included (2012-08-13 03:22)
- tplinc fix (2012-08-06 21:52)
- compatibility with angua (2012-08-06 17:35)
FAQ
ToDo
- Exclude or document template helper functions
- Add template switcher for user settings
- Publish some templates
Discussion
Let me know if you use this or not. I ll try to provide some of my templates that make use of this functions. — sf 2011/03/06 16:21