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



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
  2. templatestescaper.php
  3. templatestfilters.php
  4. templatestsetter.php
  5. templatestuser.php

folders

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

In other words templates are available for actions, formatters, page handlers and themes.

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

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

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:

  • hotfix, handlers
  • use [ ' data | pre ' ], add NO additional filter, run HTML escaping Ut::html($data); prior in the PHP file if you have to

Show Files (1 file)