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/plain
Description: readme
Class: SIREN PHP Templating Library
Template engine featuring recursion and nesting
Author: By
Last change:
Date: 3 months ago
Size: 4,688 bytes
 

Contents

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('text', $pangram);        // defines a var
    setVar('mytext', '{text}');      // defines a var
    parse ('output', 'mytext');      // loads 'mytext' 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\]'
     * 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.


## Manifest (overview)  

### Snippet

    new Snippet($orphans)               // keep, remove, comment  
    setVar($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 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, $orpans)  
    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](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](code_of_conduct.md)

For more information send a message to info at phpclasses dot org.