PHP Classes

File: readme.md

Recommend this page to a friend!
  Classes of wim niemans   SIREN PHP Templating Library   readme.md   Download  
File: readme.md
Role: Documentation
Content type: text/markdown
Description: readme
Class: SIREN PHP Templating Library
Template engine featuring recursion and nesting
Author: By
Last change: added text
Date: 3 years ago
Size: 5,258 bytes
 

Contents

Class file image Download

SIREN -- a Simple, Recursive, and Nimble template engine.

This library contains two classes; Snippet and Templet. While Snippet is the workhorse, which does the parsing and recursion, Templet adds a few very usable features like including files and processing blocks.

A variable (var) is the concept to give a name to a piece of text. Snippet collects these var's in a (key, value) structured associative array.

> Technically a var exists by name and can exhibit its text (content).

The text itself may contain embedded var's. These are delimited by curly braces. Parsing is the process of substituting these embedded var's with the content they identify. This is done recusively.

Example. $pangram = 'The quick brown fox jumps over the lazy dog.'

setVar('somename', $pangram);    // defines the var 'somename'
setVar('myvar', '{somename}');   // defines the var 'myvar'
parse ('output', 'myvar');       // loads 'myVar' and substitutes embedded var's
echo  ( getVar('output') );      // displays the result, stored as var 'output'

> For more examples, see demo.php.

Snippet is 'limited' to basic text lines. These can be chunks of HTML, SQL commands, nifty code lines as formatting rules, etc. Usage in three ways:

  • feed a small text and it's variables, than parse and quit,
  • feed a lot of variables (f.i. data items), than feed a small text and parse, repeat the parsing unlimited with ever changing text,
  • simulate a foreach by appending to the same var.

Templet joins the fun with

  • loading files as large texts with lots of embedded variables,
  • add (unlimited) hierachies of text's as nested template blocks,
  • simulate several foreach by appending blocks to their respective var's,
  • feature template files with a theme.

Syntax reference.

What's a var?

 * syntax: {[$|?]var} where var  is [text]{var}[text]
 *                    where text is '-.:_[\w\d\]' repeated zero or more times
 * example: ['a' => 'x', 'b' => 'y', 'c' => 'z', 'ayc' => 'final', 'A' => '{c}']
 *            {b}   becomes   'y'
 *           a{b}c  becomes  'ayc'
 : {a{b}c} becomes  {ayc}  then becomes 'final'
 *            {A}   becomes   {c}   then becomes 'z'
 *           A{A}A  becomes  A{c}A  then becomes 'AzA'
 : {A{A}A} becomes {A{c}A} then becomes '{AzA}' then becomes orphan
 *
 * gotcha: while '{a}{b}' is a correct specification, '{{a}{b}}' is not !

What's a block?

 * syntax: <!?- BEGIN blockname ?->
 *         < specific text >
 *         <!?- END blockname ?->
 * Blocks can be nested unlimited, as long as the blocknames are unique.

What's that '$' and '?'

A marker may start with a single '$', saying that the var is a global PHP variable. In stead of finding the var in the known var's, Snippet wil look for $GLOBALS['var']. A marker may start with a single '?', saying that the var must not exist AND that is not an error if it doesn't. Existing var's will be replaced, and otherwise ignored /the var is never an orphan!).

Manifest (overview)

Snippet

new Snippet($orphans)               // keep, remove, comment  
setVar($var, $value, $append)       // single, multiple items, optional bool $append  
setVarData($var, $value, $append)   // single, multiple items, optional bool $append  
getVar($var)                        // returns value or empty string  
contains($var)                      // returns true/false indicating the existence of $var
unsetVar($var)                      // delete $var from collection  
parse($sink, $source, $append)      // parse $source into $sink, optional bool $append  
tidy($var, $orphans)                // returns cleaned value of $var, optional orphans handling  
getOrphans($var)                    // return array of unrecognised var's  

Parse uses a recursive PCRE pattern to locate a var. Substitution occurs recursively by parsing its contents.

Templet extends Snippet

new Templet($themeDir, $orphans)   // base theme directory, optional orphans handling  
setTheme($themeDir, $orphans)  
setFile($var, $value)              // $value contains a valid filename relative to themeDir  
setLazyMode($bool)                 // true for lazyLoad (load on reference; otherwise on setFile)  
setFailMode($bool)                 // true for failSilent (ignore file not found)  
setBlock($parent, $var, $ref)      // var $parent contains a block named $var which is replaced  
                                   // by a var named $ref with value of the separated block  

Parsing detects automaticly that a var is declared a file or is declared a block.

<a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-sa/4.0/88x31.png" /></a><br />All Siren documentation is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-sa/4.0/">Creative Commons Attribution-ShareAlike 4.0 International License</a>.

Contributor Covenant