WackoWiki: Usage of Template Engine

https://wackowiki.org/doc     Version: 178 (18.02.2024 09:21)

Usage of Template Engine

transition template engine for WackoWiki

Guide -> work in progress



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
  2. how do templates work
  3. concept and internals
  4. $tpl->naming
  5. how to process conditions
  6. 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. templatest.php[link1]
  2. templatestescaper.php[link2]
  3. templatestfilters.php[link3]
  4. templatestsetter.php[link4]
  5. templatestuser.php[link5]

folders
  1. _cache/template
  2. action/template
  3. formatter/highlight/template
  4. handler/page/template
  5. theme/_common
  6. theme/default/appearance/template

1. Workflow


2. Base File

example.php

 $tpl->variable = $value;	

2.1. Setting and leaving prefixes

__get/__set helper for generation internal tags:
keeping stack of simple context name prefixes

$tpl->enter('menu_');

$tpl->leave();	

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

2.3. Hints

Possible error sources

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

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

2.3.3. Assign arrays

PHP
<?php

$colors = ['blue', 'green', 'red', 'yellow'];

foreach ($colors as $color)
{
    $tpl->n_color = $color;
}

template
<ul>
    [= n _ =
        <li>[ ' color ' ]</li>
    =]
</ul>

3. Template File

template/example.tpl

simple example template

[ === main === ]
	[ ' variable ' ]	

3.1. Syntax


[ ' nonstatic ' ]

[ ' commit | void // alternation hack ' ]

3.1.1. Include


.include ../../../_common/_header.tpl
.include _files.tpl
.include _comments.tpl

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

3.1.3. Inline definitions


[ = abc def =
   ....
 = ]	


cut off old [= ... =] block, and replace it with lone recall line

3.1.4. Variables


[ ''' l UserList ''' ]

[ '' pagination '' ]

[ ' link ' ]

[ ' // comment ' ]

The amount of ' single quotes you chose is up to you.

3.1.5. Pull

[ ' pull: value ' ]	


[ ' csrf: login ' ]

[ ' db: pwd_min_chars ' ]

[ ' format_t: ForgotLink ' ]

[ ' href: properties ' ]

[ ' _t: RealName ' ]

3.2. 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 ' ]

3.3. Examples

-> Available Pulls, Escaper and Filters[link6]

3.4. Hints

Possible error sources

put the template.tpl in the right folder
Warning: Creating default object from empty value in ...	

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

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


-> Theme guide with example templates[link7]

5. open issues


meta templates?

What about?
[ ' integer | int ' ]

5.1. 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.
  2. Additional the auto-indent feature may add \t.
    1. 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)
  2. _comment handler (body -> textarea)
  3. edit handler (body -> textarea)
  4. permissions handler (list field holding privileges -> textarea)
  5. filemeta handler (file caption -> textarea)
  6. include action (body -> pre)
  7. 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";	



workaround: