DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:templateconfhelper

templateconfhelper Plugin

Compatible with DokuWiki

2014-09-29

plugin Template switching and inheritance

Last updated on
2015-05-16
Provides
Helper, Action
Repository
Source

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

Tagged with farm, template

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: example tpl with default base_tpl

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 session
  • save_session( $var, $false ) – save utpl to session
  • save_user( $var, $val ) – #DUMMY
  • tpl_switch( $tpl ) – change style after init.php has been run
  • tpl_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 setting
  • base_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/' ),
  );

example getConfigPath debugging output

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 in cascade_config[$type]

Template

  • tpl_include( $file, $t=false ) – use getConfigPath to include file from cascade_config['template_path'], checks templates $t, default_tpl and base_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

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

plugin/templateconfhelper.txt · Last modified: 2018-06-06 00:22 by Klap-in

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki