WackoWiki: Template Engine

https://wackowiki.org/doc     Version: 25.06.2019 07:10
Dev[link10]/Release[link11]/R55[link12]/TemplateEngine
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 -> 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/template.php
  2. action/template/template.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. handler/page/template
  4. 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. Hints

Possible error sources

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

3. Template File

template/example.tpl

 [ ' variable ' ]

3.1. Syntax


.include ../../../_common/_header.tpl

[ ' nonstatic ' ]

[ ' commit | void // alternation hack ' ]

3.1.1. 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.2. Inline definitions


[ = abc def =
   ....
 = ]


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

3.1.3. Variables


[ ''' l UserList ''' ]

[ '' pagination '' ]

[ ' link ' ]

[ ' // comment ' ]

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

3.1.4. 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_formatted ' ]

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


4. Write your own templates


cheat sheet
[ '  ' ]
[ ' _t:  ' ]
[ ' 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>


-> 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], 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";



workaround::