transition template engine for WackoWiki
* push-style (with pull methods for e.g. csrf & i18n) lazy topo-ordered
* incremental building liberated from von neumann style applicative
Guide -> work in progress
{{toc numerate=1}}
What is a Template engine?
1. https://en.wikipedia.org/wiki/Template_processor
2. Separates visual code (HTML/CSS) from logic code (PHP).
??A guide for the new template engine will hopefully follow soon.??
1. parent file -> associated template
1. how do templates work
2. concept and internals
1. ##$tpl->naming##
1. how to process conditions
1. how to use filters
add an example template with all cases and examples into the ##community## folder
1. action/example.php
2. action/template/example.tpl
classes
1. ((source:master/src/class/templatest.php templatest.php))
1. ((source:master/src/class/templatestescaper.php templatestescaper.php))
1. ((source:master/src/class/templatestfilters.php templatestfilters.php))
1. ((source:master/src/class/templatestsetter.php templatestsetter.php))
1. ((source:master/src/class/templatestuser.php templatestuser.php))
folders
1. ##_cache/template##
1. ##action/template##
1. ##formatter/highlight/template##
1. ##handler/page/template##
1. ##theme/_common##
1. ##theme/default/appearance/template##
===Workflow===
===Base File===
**example.php**
%% $tpl->variable = $value; %%
====Setting and leaving prefixes====
##""__get/__set""## helper for generation internal tags:
keeping stack of simple context name prefixes
%%
$tpl->enter('menu_');
$tpl->leave();
%%
====Assign template definition to variable====
##$variable = $tpl->definitionName();##
Adapt the ##$tpl->myDefinition()## name to the corresponding template definition you want to use.
%%$message = $tpl->definitionName();
$message->mode = $this->_t('RenamePage');
$message->log_l_message = $record['value'];
$this->set_message($message, 'success');
%%
%%
[ == definitionName == ]
<strong>[ ' mode ' ]</strong>
[ ' log ' ]
[ === log === ]
<ul>
[= l _ =
<li>[ ' message ' ]</li>
=]
</ul>
%%
====Hints====
Possible error sources
=====Line endings=====
!!Use **LF** not CRLF line endings in WackoWiki templates.!!
If you don't do this in templates, the templating engine will throw an error:
##templatest: no main template found in action_or_handler/template/path.tpl##
=====Array building=====
creates a new array -> EXPLAIN, keep them in order
##$tpl->a_b_c##
##$tpl->a_b##
same array
##$tpl->a_b##
##$tpl->a_b_c##
=====Assign arrays=====
PHP
%%(php)
<?php
$colors = ['blue', 'green', 'red', 'yellow'];
foreach ($colors as $color)
{
$tpl->n_color = $color;
}
%%
template
%%(hl html)
<ul>
[= n _ =
<li>[ ' color ' ]</li>
=]
</ul>
%%
===Template File===
**template/example.tpl**
%%
simple example template
[ === main === ]
[ ' variable ' ]
%%
====Syntax====
##""[ ' nonstatic ' ]""##
##""[ ' commit | void // alternation hack ' ]""##
=====Include=====
##.include ../../../_common/_header.tpl##
##.include _files.tpl##
##.include _comments.tpl##
=====Definitions=====
%%
[ === DefinitionTwo === ]
[ ' im DefinitionOne ' ] [ ' title ' ]
[ === DefinitionOne === ]
<img src="[ ' db: theme_url ' ]icon/spacer.png" alt="[ ' title ' ]">
%%
##""[ === main === ]""##
##""[ == sortsArr == ]""##
##""[ = UserList = ]""##
##""[ ==== // some text === ]""## comment
The amount of ##=## equal signs you chose is up to you.
=====Inline definitions=====
%%
[ = abc def =
....
= ]
%%
cut off old [= ... =] block, and replace it with lone recall line
=====Variables=====
##""[ ''' l UserList ''' ]""##
##""[ '' pagination '' ]""##
##""[ ' link ' ]""##
##""[ ' // comment ' ]""##
The amount of ##'## single quotes you chose is up to you.
=====Pull=====
%%[ ' pull: value ' ] %%
##""[ ' csrf: login ' ]""##
##""[ ' db: pwd_min_chars ' ]""##
##""[ ' format_t: ForgotLink ' ]""##
##""[ ' href: properties ' ]""##
##""[ ' _t: RealName ' ]""##
====Filters====
%% [ ' variable | filter1 | filter2 | ... ' ] %%
##""[ ' comments | check 2 ' ]""##
##""[ ' note | e ' ]""##
##""[ ' username | e attr ' ]""##
##""[ ' page.hits | number 0 , . ' ]""##
##""[ ' a | replace desc uarr asc darr ' ]""##
##""[ ' count | enclose " (" ")" ' ]""##
##""[ ' preview | nl2br ' ]""##
##[ ' watched | list WatchText UnwatchText | _t ' ]##
##""[ ' created | time_format ' ]""##
====Examples====
-> ((/Dev/Projects/Templatest/Filters Available Pulls, Escaper and Filters))
====Hints====
Possible error sources
put the ##template.tpl## in the **right** folder
%%Warning: Creating default object from empty value in ...%%
====Filter Chains====
Often, multiple filters should be applied to some value in a particular order.
%% [ ' variable | filter1 | filter2 | ... ' ] %%
Filter Chains provides a simple method by which filters may be chained together.
Filters are run in the order they are added to the filter chain.
===Write your own templates===
cheat sheet
%%
[ ' ' ]
[ ' _t: ' ]
[ ' db: ' ]
[ ' href: ' ]
[ ' | checkbox ' ]
[ ' | check 0 ' ]
[ ' | number 0 , . ' ]
[ ' | number_format ' ]
[ ' | time_format ' ]
[ ' | pre ' ]
[ ' | e ' ]
[ ' | e attr ' ]
[= _ =
=]
<form action="[ ' href: add_handler ' ]" method="post" name="add_name">
[ ' csrf: add_name ' ]
<option value="[ ' id ' ]" [ ' sel | list "" 'selected ' ' ]>[ ' mode ' ]</option>
$tpl->enter('prefix_');
$tpl->leave();
%%
%%
[= l _ =
<li>
<a href="[ ' href ' ]" class="tag" rel="tag">[ ' category | e ' ]</a>
</li>
=]
[ '' l link '' ]
[ === link === ]
<li>
<a href="[ ' href ' ]" class="tag" rel="tag">[ ' category | e ' ]</a></li>
</li>
%%
-> ((/Doc/English/ThemeGuide Theme guide with example templates))
===open issues===
meta templates?
What about?
##[ ' integer | int ' ]##
====next line issue for ##textarea## and ##pre##====
1. Templatest strips all ##\n## line breaks from ##[ ' body ' ]## which is in this case undesired. We need all ##\n## line breaks in body for POST or action include.
1. Additional the auto-indent feature may add ##\t##.
2. e.g. in form ##<input type="hidden" name="body" value="multi line body">## , one should not serve HTML in PHP file and pass it as $tpl->kludge = HTML;
All data for ##<textarea>## or ##<pre>## must be passed trough to escape filter as is.
This applies to all ##textarea## fields used in the template engine.
1. ##show## handler (body may have a ##pre## field)
1. ##_comment## handler (body -> ##textarea##)
1. ##edit## handler (body -> ##textarea##)
1. ##permissions## handler (list field holding privileges -> ##textarea##)
1. ##filemeta## handler (file caption -> ##textarea##)
1. ##include## action (body -> ##pre##)
1. ##news## action (body -> ##pre##)
This example from the news action, breaks formatting of ##<pre>## boxes
%%
$tpl->include = $this->action('include', ['page' => '/' . $page['tag'], 'notoc' => 0, 'nomark' => 1], true);
%%
This example below shows only the ##\n## issue
%%
$tpl->body = $body; // Ut::html($body)
echo '<textarea>' . Ut::html($body) . "</textarea>\n";
%%
file:/Dev/Projects/Templatest/Usage/templatest_nl_issue.png
**workaround:**
* ((revision:c7754bc hotfix)), ((revision:4832e60 handlers))
* use ##[ ' data | pre ' ]##, add **NO** additional filter, run HTML escaping ##Ut::html($data);## prior in the PHP file if you have to