Dummy - The Framework for Dummies! - Complete View Reference

As default, $Dummy loads your templates using the View template engine. Tags inside your HTML are delimited by braces ({}), and can be simple ({like_this}) or for content ({_tag}This is the content{/tag}). 

Frame

A good practice is to create your HTML files only for the body part, or even better, only the central content (without menu, headers and footers that are common to all the site, henceforth called the frame). In your controller, after the template is loaded, you can put this inside your main frame, which contains the full HTML, usually called frame.html, using the function envelope. Here is an example

Your page Frame Result after envelope('frame.html','{CONTENT}');

<h1>Title</h1>
<p>Hello! This is the page! Welcome {name}</p>
<p>Yay!</p>

 

<html><head>
<title>{PAGE_TITLE}</title>
{_} metas ... by the way, this is a comment in the template engine {/}
</head><body>
<div>{_} menu {/_}</div>

<article>{CONTENT}</article>

<footer>...</footer>
</body></html>

<html><head>
<title>{PAGE_TITLE}</title>
{_} metas ... by the way, this is a comment in the template engine {/}
</head><body>
<div>{_} menu {/_}</div>

<article><h1>Title</h1>
<p>Hello! This is the page! Welcome {name}</p>
<p>Yay!</p>
</article>

<footer>...</footer>
</body></html>

Tag Formatting

Simple tags can be formatted by adding the format (and parameters) separated by a "|", like {variable|number|2} will format "variable" as a numeric value with 2 decimal numbers.

Bellow, all formatting options:

  • integer - alias to number, but rounds the number to integer
     
  • number (alias float) prints out as numeric values, have 3 optional parameters:
    1. number of decimal numbers
    2. Decimal separator (default ",")
    3. Thousands separator (default ".")

    tag formatted like {tag|number|2|-|x} where tag is 1000,123 would output 1x000-23, while one formatted like {tag|number|2|.|,} would output 1,000.12
     
  • each - works as a mapping in case of a loop. It basically calculates the mod of the numeric value of the tag to calculate which to serve. Options are:
    1. Comma delimited list of number and what to output
    2. Default if not in the list
       
    For {#|each|2=even,5=fives|others} will output, where # is a number, from 1 to 5:
    1: others
    2: even
    3: others
    4: even
    5: fives
     
  • truncate - truncates a string (UTF-8 compatible) by default 50, though you can set several options:
    Therefore, {variable|truncate|10|...} were variable is "This has 22 characters" would output "This ha...". Note how it cuts before 10 because it fits the "..." (tip: use the UTF-8 character "…" instead, thus consuming only one character)
    1. Number of characters
    2. Elipses to be added in the end
    3. If should strip HTML tags (anything in this field means true
    4. When stripping HTML, preserve end of line - will turn end of line as a <br/> (anything in this field means true
       
  • nl2br - self explanatory
     
  • onnull or on_null - if the variable is null or empty, shows the parameter instead, so:
    {variable|onnull|This is empty} will show the variable if it is set, but "This is empty" if it is empty or not set.
     
  • toplain - simple translation of "<" to "&lt;" and ">" to "&gt;"
     
  • html - Uses htmlspecialchars on the variable, and also translates "&" to "&amp;". If the only parameter is set, removes single quote ('). Useful to fill variables inside an html input field
     
  • textarea - similar to toplain, translates "<" to "&lt;" and "&" to "&amp;"
     
  • htmlentities - runs the internal LazyDummy::htmlentities_ex, which basically translates some language characters (like ñ) and then applies htmlentities
     
  • url - Tries to normalize a string that should be a valid HREF. It will attempt like this:

    If variable is empty, returns a #
    If variable does not have a protocol (http:// or https://), but is a valid folder+page with .html, or .php, pre-pends a "/" to the variable
    If can't detect folders and extension, and does not start with "/", pre-pends "http://" to the variables
    If have a protocol, outputs as is.
     
  • deutf - returns the variable with utf8_decode
     
  • uc or ucwords - returns the variable in lowercase and applies ucwords
     
  • up - returns the variable in uppercase
     
  • nohtml - totally strips any HTML out. If the only parameter is set, also removes quotes
     
  • map - similar to each, but rather maps anything, not only numbers. IMPORTANT: Big mappings are causing PHP to loop out of control, I cannot find why, avoid using this for now. 

    Example: 

    {variable|map|one=1,two=⚋,three=III,four=➃|others} will output depending on variable value:
    zero = others
    one = 1
    two = ⚋
    three = III
    four = ➃
    five = others
     
  • select or selected - if the field is as defined (or simply set), outputs "selected='selected'", which is useful for loops on html select options. Example: {variable|select|5} will output "selected='selected'" only if variable=5
     
  • check or checked  - same as selected, but outputs "checked='checked'"
     
  • date - outputs in the internal date format defined in $stdDate or as defined in the parameter
     
  • datetime - same as above, but datetime (uses $stdDatetime)
     
  • math - performs a simple math on top of the variable. The first parameter is the operator, which can be +, -, *, / or %. Example for variable=10:

    {variable|math|+10} = 20
    {variable|math|-3} = 7
    {variable|math|%2} = 0

Functions

    You can interact with the template (view) directly using several functions, you can use them on the default $Dummy->view or your own view objects (an example of handling your own view templates is to fill a list using a template):

  • __construct(&$core, &$parent = null, $debugMode)
    When instancing a new view, you must send the framework as the first parameter ($Dummy) and optionally another view to copy the attributes from ($parent). The attributes copied are used on the tag formating, like decimals, standard date format and constants that should always be filled. The $Dummy framework have these constants in the $templateParams variable, but you can just send the default view to get them.
     
  • copyFrom($other)
    Works mostly as copying one view object into the current one. Due to some optimization pointers inside the view objects, default PHP cloning (which is also overriden in the view template) are not perfect, so this will guarantee that the current view is an actual copy of the $other view, without pointers corrupting and pointing to the same memory space.
     
  • reset()
    Resets all internal variables and constants to default, cascading to nested objects, without deleting the contents.
     
  • clear($preserveConstants=true)
    Similar to reset, but clears the contents as well. If you do not specify you don't want to preserve the constants, it will leave them untouched, thus having the exact complementar effect of reset: clear the contents, but not the variables and constants.
     
  • getAllTags($forceLower=false)
    Returns a list of all tags in the current object, including nested ones
     
  • tagExists($tag)
    Returns a boolean of either the tag exists or not (including nested views)
     
  • assignFile($tag,$file,$checkfirst=false,$forcePlainParse=false;$cropBODY=false)
    Reads the contents of $file as a template and puts in the $tag specified.
    If $checkfirst is specified, will check if the file exists, preventing an unexpected error if it doesn't;
    If $forcePlainParse is specified, will read the file as text only, ignoring any templates;
    If $cropBODY is specified, will only return what is inside the <body> HTML tag of the file.
     
  • envelope($file,$tag)
    Puts the current view contents inside the $tag of $file, and makes the new view the result. This is the function used to performe the mentioned in "Frame" at the top of this article; Returns true or false on success;
     
  • fetch($file,$cropBODY=false)
    Reads the $file into the view, optionally cropping only the contents of <body>
    This function is cached (the actual view object is saved), so if you change the original file, you must delete the cache (The cache folder is specified by the $cacheSeed variable, which the $Dummy framework sets)
    Returns true or false on success;
     
  • append($content, $atTag='')
    Appends a content (can be a string or another view) to the current view. If you specify $atTag, will append inside that tag, otherwise at the end of the current view;
     
  • addContent($name,$tipo,$content)
    Adds a string (if there is no $name) or tag, with tag formating ($tipo), at the end of the view. If $content is a string that have valid tags inside, automatically transform it into a view object. Returns the number of nodes (tags or strings) the current view have.
     
  • get($tag, $noerror=true)
    Returns the contents of the $tag. Raises no error if the tag is not found unless you specify false on the second parameter;
    Since this function can return an object or a string (depending on the contents of the tag), it returns a pointer for a view object OR a string OR false (tag not found).
     
  • getTxt($tag, $noerror=true)
    Same as get, but always returns a string (if the tag is an view object, will compose it first). Returns false if tag not found;
     
  • populate($tag, $rows, $n, $params=array(), $callback=array(), $overflowprotect=0)
    This is a rather complex function that aims at populating a whole list based on an associative array ($rows).

    Given the list $rows and a template $tag (must be a content tag, like {_list}), it iterates the array adding a new instance of the $tag for each, filling the contents based on the associative array and the tags inside the $tag template.

    $n must contain the total number of items, regardless if they will show or not based on pagination parameters.

    $params have different parameters for the listing process, as follows:
    • "p_init" : starting item for the current page (item, not page) - if none is specified, it will try to look at $_REQUEST;
    • "p_size": size of each page (items per page) - if none is specified, will try to look at $_REQUEST. If all fails, will use CONS_DEFAULT_PAGESIZE;
    • "excludes": array with a list of tags that should be removed from the template tag on each iteration. You can change for each item on the callback;
    • "no_paging": if just set to true, will ignore all paging systems and list all items;
    • "grouping": A string in the format "field name:tag name". Each time the field in the array changes during iteration, the tag specified will be shown (and populated). This is useful for creating groupings, as the name implies;
    • "reverse": if set to true, will list backwards

    $callback is a list of callback functions (string name) to be called on each iteration. These callbacks must follow the following parameter setting:

        callbackname(&$view, &$params, $item)

    Note that the first item is the current view and the second the parameters, both sent by reference (changing them inside the callback will change in the populate function), the third parameter is the item from $rows to be shown; You can use this callback to change/tweak the items, change the excludes for this item, or perform other actions such as counts and math based on the result; The callback MUST return the $item or false if the item is to be skipped;

    $overflowprotect creates a protection in case of recursive loops that can be created by mishandling tag names (for instance, a tag inside the template have the same tag as one outside). If zero, no protection is used, otherwise, set for the number of expected interactions (tip: $n) before the function is forcibly terminated;

    Aside from the contents of the provided list $rows, other tags will be automatically filled per iteration:
    {#} is the number of the item (starts with 0)
    {islast} is 0 or 1 if the item is the last to be shown. You can use the |map format to make changes to the css, for instance
    {isfirst} is 0 or 1 if the item is the first to be shown.

    After creating the list, this function will also set $lastReturnedSet with the last $row used, and $firstReturnedSet with the first $row used (you can access them from the view object, like $Dummy->view>lastReturnedSet

    This function has no return, errors will be sent to the $Dummy errorLog or warningLog.
  • parse($in, $cropBODY=false)
    As the name implies, this function parses a string $in into the view object, creating the tags and objects. It optionally can read just what is inside the <body>

    Some automation performed is the creation of the tag {AUTOHEAD} just before </head> and {AUTOBODY} just before </body> so the framework can add things automatically to the head or body of the template;

    Returns true of false if the parse was successful;
     
  • assign($tag, $content)
    Assigns the value ($content) of a tag. Note you can have any number of tags with the same name, all will be changed.
     
  • compose($arrayin = false, $emptyme = array)
    Fillls the current tag with the contents of $arrayin (optional), remove content tags specified on the optional $emptyme, and returns the constructed string, respecting tag formating. Basically, this turns the view into a string;
     
  • fill($arrayin, $emptyme = array)
    Same as compose, but does not returns a string, just fills the tags and remove (optionally) the ones specified in $emptyme
     
  • haveTag($string)
    Given a string, detects if it have valid view tags and, therefore, can/should be parsed to a view object
     
  • compactjs($tag)
    Given a content tag that should contain only javascript, compact it (minify, so to speak)

 


Functions to add to this documentation: getTreeTemplate, getTreeTemplate_ex, getPagingLinks, createPaging


 

◀ Back


Ads by google (click here to hide, consider tipping me to maintain the site)
Check other of my articles, like: Save the planet saving water, energy and money
Important Notice