- version 1.0
- author Alfasado Inc. <webmaster@alfasado.jp>
- copyright 2017 Alfasado Inc. All Rights Reserved.
- PHP version requirements to PHP 5.6 or 7 or later.
- Supports UTF-8 encoded text only.
<?php
require_once( '../class.PAML.php' );
$ctx = new PAML ();
$ctx->prefix = 'paml';
$ctx->assign( 'page_title', '<span>PAML Example Page</span>' );
$ctx->assign( array (
'foo' => 'bar',
'bar' => 'baz',
'baz' => 'qux' )
);
$ctx->assign( array( 'loop_vars1' =>
array ( 'foo','bar','baz', 'qux' )
) );
$ctx->assign( array (
'loop_vars2' =>
array (
'foo' => 'bar',
'bar' => 'baz',
'baz' => 'qux' )
) );
$ctx->display( 'tmpl/template.tpl' );
<!DOCTYPE html>
<html>
<head>
<title><paml:var name="page_title" remove_html="1"></title>
</head>
<body>
<h1><paml:var name="page_title"></h1>
<p><paml:var name="foo">,<paml:var name="bar">,<paml:var name="baz"></p>
<paml:loop from="$loop_vars1">
<paml:if name="__first__">
<ul>
</paml:if>
<li class="<paml:if name="__odd__">odd<paml:else>even</paml:if>">
<paml:var name="__value__" escape="1">
</li>
<paml:if name="__last__">
</ul>
</paml:if>
</paml:loop>
<paml:loop from="$loop_vars2" sort_by="value:reverse">
<paml:if name="__first__">
<ul>
</paml:if>
<li class="<paml:if name="__odd__">odd<paml:else>even</paml:if>">
<paml:var name="__key__"> : <paml:var name="__value__" escape="1">
</li>
<paml:if name="__last__">
</ul>
</paml:if>
</paml:loop>
Template Tags are not case sensitive. You can give '$' at the beginning and ending. You can give ':' at after prefix. The closing tag '/' is optional.
In modifiers that do not require argument, arguments is optional.
<pamlvar name="name" escape>, <pamlvar name="name" escape="1">,
<PAMLVar name="name" escape />, <paml:getVar name="name" escape="1" />,
<Paml:var name="name" escape="1" />, <$paml:Getvar name="name" escape="1"$>,
<paml:Var name="name" escape="1" />...
<paml:setvar name="name" value="value">
<paml:name> is equivalent to <paml:var name="name">
or
<paml:array.key1.key2>
The following template does not work well because Template tags are high priority than inline variable.
<paml:setvar name="var" value="value">
<paml:$var> <= OK
<paml:var> <= It is interpreted as a template tag var.
<paml:setvar name="variable" value="value">
<paml:$variable> <= OK
<paml:variable> <= It is also interpreted as a template tag var.
In order to avoid this, it is better to give a prefix (e.g.'_') to the beginning of the variable name or explicitly give $ to the beginning.
<paml:block param1="1" param2="2"> ... </paml:block>
<paml:if name="variable_name1">
...
<paml:elseif name="variable_name2">
...
<paml:else>
...
</paml:if>
The tag arguments specification is made by either value, array with key, variable, or array(CSV).
value : <paml:var name="name">
array : <paml:var name="array[key]">
or : <paml:var name="array.key1.key2">
variable : <paml:var name="$variable">
or : <paml:var name="$variable[key]">
request variable
: <paml:var name="request.name">
(From HTTP Request variables '$_REQUEST'.)
csv : <paml:var name="name" replace="'value1':'value\'2'">
or : <paml:var name="name" replace="value1:value2">
(<=Depending on the tag implementation.)
CSV enclosure and CSV delimiter are properties of the class(they can be changed).
Initial value
: $csv_enclosure = "'" (enclosure)
$csv_delimiter = ':' (delimiter)
A function tag used to store and return values from variables. if given 'value' attribute, set a variable (no output when setting the value of a variable) (Alias for 'setvar').
- name(required) : A name for get or set variable.
- value : For set a variable.
- append : Append a value to the end of an existing variable.
- prepend : Prepend a value to the end of an existing variable.
Alias for 'var'. When it's confirmed that name is a literal, please specify this(faster).
A function tag used to set the value of a template variable.
- name(required) : A name for set variable.
- var : Alias for 'name'.
- value : For set a variable.
- append : Append a value to the end of an existing variable.
- prepend : Prepend a value to the end of an existing variable.
Alias for 'setvar'.
Translate phrase. See => ./locale/ja.json
- phrase : String for translate.
- params : For format string(s). use sprintf function. When passing multiple values, specify CSV.
- component : Plugin class name.
Output left_delimiter(Default '{{').
Output left_delimiter(Default '}}').
Execute the loop only once. If a name attribute is specified and the variable has a value, output it.
- name : Set a output value to variable. Output empty string.
- append : The block content will be be appended to the content of the parent template block.
- prepend : The block content will be be prepended to the content of the parent template block.
- The other attributes be passed to the inside of block as custom attribute.
Loop over the values in a hash or an array.
- name(required) : The name of the array, hash data to process.
- from : Alias for 'name'
- key : The name of the variable that is the current key.
- item : The name of the variable that is the current element.
- sort_by : Causes the data in the given array to be resorted in the manner specified. e.g.: sort_by="value,numeric,reverse"
- glue : When specified, the string will be placed in between each row.
Within this tag, the following variables are assigned
- __first__ : Assigned when the loop is in the first iteration.
- __last__ : Assigned when the loop is in the last iteration.
- __odd__ : Assigned true when the loop is on odd numbered rows.
- __even__ : Assigned true when the loop is on even numbered rows.
- __counter__ : Loop counter.
- __index__ : Loop counter(Starting from 0).
- __key__ : Holds the 'key' of the array or objects for loop(When the tag attribute 'key' is not specified.).
- __value__ : Holds the 'value' of the array or objects for loop (When the tag attribute 'item' is not specified.).
- __total__ : Count an array or objects for loop.
Alias for 'loop'
The block is repeatedly output during the specified value.
- to(end or loop) : The ending number for the loop(default:1).
- from(start) : The starting number for the loop(default:0).
- increment(step) : The amount to increment the loop counter(default:1).
- var : Assigned to template variable to 'var'(default:'__value__').
- glue : When specified, the string will be placed in between each row.
Within this tag, the following variables are assigned
- __first__ : Assigned when the loop is in the first iteration.
- __last__ : Assigned when the loop is in the last iteration.
- __odd__ : Assigned true when the loop is on odd numbered rows.
- __even__ : Assigned true when the loop is on even numbered rows.
- __counter__ : Loop counter.
- __index__ : Loop counter(Starting from 0).
- __value__ : Holds the 'value' of the array or objects for loop(When the tag attribute 'var' is not specified.).
- __total__ : Total loop count.
Alias for 'for'.
Always produces an empty string.
Allow a block of data to be taken literally. Anything within this tags is not interpreted, but displayed as-is.
Make sure that certain parts of the template are not page cached.
A block tag used to set the value of a template variable. Note that you can also use the 'setvar' modifier to achieve the same result as it can be applied to any tag.
- name(required) : A name for set variable.
- append : Append a value to the end of an existing variable.
- prepend : Prepend a value to the end of an existing variable.
Alias for 'setvarblock'. Use attribute 'var' instead 'name'.
Set variables collectively. The key and value delimiter is '='. When specified 'name' attribute, assigned to array to 'name'.
<paml:setvars>
_url =http://www.example.com/
_site_name =PAML
_site_desc =<paml:var name="description">
</paml:setvars>
Alias for 'setvars'.
A conditional tag that is evaluated if the name attributes evaluate true. This tag can be used in combination with the 'elseif' and 'else' tags.
- name(required) : A Name for evaluate.
- eq : Given value is equal to the variable.
- ne(not) : Given value is not equal to the variable.
- gt : Given value is greater than the variable.
- lt : Given value is less than the variable.
- ge : Given value is greater than or equal to the variable.
- le : Given value is less than or equal to the variable.
- like : Given value contains the variable.
- test : By expression result.
It simply branches on the presence or absence of the value of the variable specified in the name attribute, and it is faster than the if statement.
Used within If and Unless blocks to output the alternate case.
Used within If and Unless blocks to evaluated alternate condition. All attributes supported by the 'if' tag are also supported.
Used within If block to evaluated alternate condition. Like the ifgetvar condition tag, It simply branches on the presence or absence of the value of the variable specified in the name attribute. It's faster than the elseif statement.
The logical opposite of the 'if' tag. All attributes supported by the 'if' tag are also supported.
Includes the content of external file into the current template. It is not included in property $include_paths The directory trace distribution file can not be included.
- file(required) : File path for include.
- Other Parameters be passed to the included template file as custom attribute.
Write this tag like a block tag. Includes the content of external file into the current template. It is not included in property $include_paths The directory trace distribution file can not be included. Block content to set variable 'contents'.
- file(required) : File path for include.
- Other Parameters be passed to the included template file as custom attribute.
This tags are used in child templates in template inheritance for extending parent templates. For details see section of Template Interitance.
The tag must be on the first line of the template.
- file(required) : The name of the template file which is extended.
Encodes any special characters to HTML entities or URL encode.
- "1" or "html" (to HTML entities ) or "url"
Used to set a output value to variable. Output empty string.
- A name for set variable.
Format the date.
Strip HTML and PHP tags from a string.
Encodes special characters in JavaScript.
Make a string uppercase.
Make a string lowercase.
Strip whitespace (or other characters) from the beginning and end of a string.
Strip whitespace (or other characters) from the beginning of a string.
Strip whitespace (or other characters) from the end of a string.
Truncates a variable to a character length ( or trims the variable ).
See => http://www.smarty.net/docsv2/en/language.modifier.truncate or https://movabletype.org/documentation/appendices/modifiers/trim-to.html
Alias for 'truncate'.
Adds '0' to the left of string to the length specified.
Removes any linefeed characters.
Return a formatted string.
Inserts HTML line breaks before all newlines in a string.
Replace all occurrences of the search string with the replacement string.
A regular expression search and replace on a variable. Use the preg_replace() syntax from the PHP manual.
Wraps a string to a given number of characters.
Specified 1, trim whitespace. Specified 2, trim linefeed. Specified 3, both.
JSON representation of a value to template variable.
Decodes a JSON string from template variable.
Build template from string.
Inheritance brings the concept of Object Oriented Programming to templates.
Replace the block tag with the name attribute of the parent template specified by the extends tag at the top of the child template with the result of the block tag specified by the child template.
See => http://www.smarty.net/docs/en/advanced.features.template.inheritance.tpl
Function tags are functions of the form
<paml:var name="name">
- array $args : tag attributes
- object $ctx : Object class PAML
The output (return value) of the function will be substituted in place of the function tag in the template, e.g. the <paml:var> function.
Alternatively, the function can simply perform some other task without any output, e.g. the <paml:setvar> function.
Block tags are functions of the form
<paml:block> ... </paml:block>
Block tag returns output $content.
- array $args : tag attributes
- string &$content : *1
- object $ctx : Object class PAML
- boolean &$repeat : *2
- numeric $counter : loop counter value
*1 $content is the template output.
In case of first loop, it will be null, and in after the second time loop it will be the contents of the template block.
*2 $repeat is true at the first call of the block function and false on all subsequent calls to the block function.
Each time the function implementation returns with $repeat being true, the contents between <paml:block> ... </paml:block> are evaluated and the function implementation is called again with the new block contents in the parameter $content.
Simplest implementation example
function some_block_tag ( $args, $content, $ctx, &$repeat, $counter ) {
return ( $counter ) ? $content : null;
}
BlockOnce(block_once) tags are functions of the form
<paml:block>...</paml:block>
BlockOnce tag execute only once.
The tag implementation is the same as the Block tag.
The parameter $counter always 1(numeric).
Conditional tags are functions of the form
<paml:if name="name"> ... </paml:if>
<paml:else> and <paml:elseif> are also permitted. Conditional tag returns true or false;
- array $args : Tag attributes
- string $content : Always null
- object $ctx : Object class PAML
- boolean $repeat : Always true
- boolean $context : if specified false, Behave as unless.
Creating a new conditional tag, tag attributes such as eq, ne, like can be used by returning $ctx->conditional_if instead of returning true or false.
Modifiers are little functions that are applied to a variable in the template before it is displayed. Modifiers can be chained together.
- mixed $str : Template output
- mixed $arg : Tag attribute
- object $ctx : Object class PAML
- string $name : Name of called modifier
or Smarty2(BC) style plugin
- string $str : Template output
- mixed $arg1 : Tag attribute1
- mixed $arg2 : Tag attribute2...
if exists modifier encode_javascript in plugin, escape="javascript" is equivalent to encode_javascript="1"
Callbacks always returns the value of the first argument( or after processing first argument ) unless there is any special intention.
- string $content : template source (input_filter) or output content (output_filter)
- object $ctx : Object class PAML
Call at before DOMDocument::loadHTML.
- string $content : template content for loadHTML.
- object $ctx : Object class PAML
- string $insert : insert_text(Measures against the problem that blank characters disappear.)
Call at before DOMDocument::saveHTML.
- object $dom : object DOMDocument
- object $ctx : Object class PAML
Call at after DOMDocument::saveHTML.
- string $content : compiled template source
- object $ctx : Object class PAML
There is a definition of class ClassName in plugins/PluginID/class.ClassName.php,
Registration is done automatically.
- object $plugin : Plugin class
- string $path : Plugin directory path( __DIR__)
- array $registry : An array of template tags or callbacks(or $registry to file 'config.json').
- string $tag_name : Tag name
- string $tag_kind : Tag kind (function, block, block_once, conditional include or modifier)
- string $func_name : Plugin class's method name
- object $plugin : Plugin class
- string $id : Callback id (It needs to be unique by $type)
- string $type : Callback type (input_filter, output_filter, loop_filter, conditional_filter or dom_filter)
- string $func_name : Plugin class's method name
- object $plugin : Plugin class
Set variables.
- mixed $name : Name of set variables or array variables.
- array $value : Variable for set variables.
Where the variable is stored.
- string $name : Name of set or get variable to(from) stash.
- mixed $value : Variable for set to stash.
- mixed $var : Stored data.
Build template file and display or return result.
- string $path : Template file path.
- array $params : Array of template variables to set.
- string $cache_id : Template cache id.
- bool $disp : Display result or return result.
- string $src : Template source text.
- string $content : After processing $content.
Build template file and return result(Do not display).
- string $path : Template file path.
- array $params : Array of template variables to set.
- string $cache_id : Template cache id.
- string $content : After processing $content.
Build template file and display result and return result.
- string $path : Template file path.
- array $params : Array of template variables to set.
- string $cache_id : Template cache id.
- string $content : After processing $content.
Build template from content.
- string $src : Template source text.
- array $params : Array of template variables to set.
- string $cache_id : Template cache id.
- string $content : After processing $content.
Build from source text always it does not use caching.
- string $src : Template source text.
- bool $compiled : Get compiled PHP code.
- string $build : After processing $src.
Set common loop variables ( '__index__', '__counter__', '__odd__', '__even__', '__first__', '__last__', '__total__' ) by $counter and array or objects for loop.
- int $counter : Loop counter.
- array $params : Array or object for loop.
Localize the scope of the variable.
In the first iteration ( $counter == 0 ), call localize and in the last iteration, call restore.
When passing an array in array as an argument, localize or restore $ctx->__stash[ 'vars' ][ $value ]
of the value of each array.
When passing an string in array as an argument, localize or restore $ctx->stash( $value ).
Get variable matching one of $local_vars[ $name ] or $vars[ $name ].
Setup tag attributes. value, variable, or array(CSV).
When $advanced_mode is true, call automatically.
Set properties from JSON file.
- string $json : JSON file path.
Global template variables.
$__stash['vars'] is alias for $vars.
Localized variables in block scope.
Localized array or object for loop.
Property $local_vars and $local_params are always the localized variables of the block scope.
When exiting the block it is reassigned to its original variables.
Tag prefix.
Tag delimiters.
Alias for $tag_block.
Page cache expiration seconds.
This forces PAML to (re)compile templates on every invocation.
Whether or not to cache the output of the templates.
Check to see if the current template has changed (different time stamp) since the last time it was compiled.
Cache driver('Memcached' or null). If null, use simple file cache.
Use 'Memcached', lib/cachedriver.base.php and lib/cachedriver.memcached.php are required.
$ctx->cache_driver = 'Memcached';
$ctx->memcached_servers = [ 'localhost:11211' ];
If false, The tag arguments specification is value only(It is not possible to specify array with key, variable, or array(CSV)) but depending on the template, it may be several to 10% faster.
CSV delimiter for parse tag attributes.
CSV enclosure for parse tag attributes.
Everything is escaped(When there is no designation of 'raw' modifier).
$debug = 1: error_reporting( E_ALL ) / 2: debugPrint error. / 3. debugPrint compiled code.
An array of file extensions that allow include.
When $ctx->plugin_compat = 'smarty_',
function smarty_function_<prefix>functionname in plugins/function.<prefix>functionname.php
function smarty_block_blockname in
plugins/block.blockname.php
function smarty_block_<prefix>ifconditionalname in
plugins/block.<prefix>ifconditionalname.php
function smarty_modifier_modifiername in
plugins/modifier.modifiername.php
Using class PAML's language property.
When not specified, $_SERVER[ 'HTTP_ACCEPT_LANGUAGE' ] automatically in use.
plugins/PluginID/locale/<language>.json
{
"Welcome to %s!":"%sへようこそ!"
}
<paml:trans phrase="Welcome to %s!" params="PAML" component="PAML">