====== templateconfhelper Plugin ======

---- plugin ----
description: Template switching and inheritance
author     : Samuel Fischer
email      : sf@notomorrow.de
type       : action helper
lastupdate : 2015-05-16
compatible : 2014-09-29
depends    : 
conflicts  : 
similar    : loadskin, multitemplate_styleman
tags       : template farm

downloadurl: https://github.com/samfisch/dokuwiki-plugin-templateconfhelper/zipball/master
bugtracker : https://github.com/samfisch/dokuwiki-plugin-templateconfhelper/issues
sourcerepo : https://github.com/samfisch/dokuwiki-plugin-templateconfhelper
donationurl: 

screenshot_img: 

----

===== 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 [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

  * https://github.com/samfisch/dokuwiki-plugin-templateconfhelper

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 [[devel:preload|preload]]

===== Examples =====

An example template making use of css iheritance could look like this:
{{ http://m3.notomorrow.de/public/repos/dokuwiki/plugins/dokuwiki-plugin-templateconfhelper-example.png?400|example tpl with default base_tpl}}

<file css 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"
</file>

<file css example.css>
body .dokuwiki {
    font-size: 0.7em !important;
}
</file>

===== 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.

<code php>
$config_cascade['template_dir'] = array(    // used in confutils
  'default' => array( dirname( DOKU_TPLINC ).'/' ),
);
</code>

==== Example ====

Example cascade path for ''inc/preload.php''

<code 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/' ),
  );
</code>

{{ http://m3.notomorrow.de/public/repos/dokuwiki/plugins/dokuwiki-plugin-templateconfhelper-path.png?400|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.

<file php main.php>
<?php
tpl_include( 'main.php' );
</file>

===== 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 =====

{{rss>https://github.com/samfisch/dokuwiki-plugin-templateconfhelper/commits/master.atom date}}

===== 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.  --- [[user>sf|sf]] //2011/03/06 16:21//