View source for Usage of Template Engine

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/wacko/class/templatest.php templatest.php))
  1. ((source:master/wacko/class/templatestescaper.php templatestescaper.php))
  1. ((source:master/wacko/class/templatestfilters.php templatestfilters.php))
  1. ((source:master/wacko/class/templatestsetter.php templatestsetter.php))
  1. ((source:master/wacko/class/templatestuser.php templatestuser.php))

folders
  1. ##_cache/template##
  1. ##action/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**

%% [ ' 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_formatted ' ]""##

====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 , . ' ]
[ '  | time_formatted ' ]
[ '  | 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], 1);
%%

This example below shows only the ##\n## issue, you'll find all related files attached for the show and edit handler
%%
$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