LiteCommerce:Flexy templates engine - Revision history

Admin: /* Built-in functions */

2010-02-05T13:27:45Z

‎Built-in functions

Admin at 13:25, 5 February 2010

2010-02-05T13:25:55Z

Admin: Created page with '== Overview == LiteCommerce is based on the powerful FLEXY template engine. It allows you to easily separate visual design from program code and to customize the look and feel …'

2010-02-05T13:25:03Z

Created page with '== Overview == LiteCommerce is based on the powerful FLEXY template engine. It allows you to easily separate visual design from program code and to customize the look and feel …'

New page

== Overview ==

LiteCommerce is based on the powerful FLEXY template engine. It allows you to easily separate visual design from program code and to customize the look and feel of your store using WYSIWUG HTML editors like MS FrontPage and Macromedia Dreamweaver or by hand. Unlike Smarty (http://smarty.php.net/) LiteCommerce FLEXY engine supports template tags incorporated into standard HTML tags.

'''Example 5.1.1 FLEXY using example'''

<pre>
{* This is a FLEXY comment, not displayed in the final output of the template *}
{* creates a PHP if statement *}
{if:someCondition}
There is non-empty condition.
{else:}
 condition is empty
{end:}
{* using statement in HTML tag *}
 There is non-empty condition.
 condition is empty
{* creates PHP foreach statement *}
<table>
<tr foreach=”arrayOfObjects,index,obj”>
<td>{obj.property1}</td>
<td>{obj.property2}</td>
</tr>
</table>
</pre>

A set of templates for visualizing LiteCommerce customer and admin zone is called skin. There is also a special mail skin which is used for mail notifications. Skin templates are organized into a skin tree.

'''Example 5.1.2 LiteCommerce skins tree'''

Litecommerce_root_dir/
skins_original - top level skins directory (source repository)
skins/ - top level skins directory (installed)
default/ - default customer zone skin
en/ - default locale (English)
main.tpl - main template for customer zone
welcome.tpl
style.css
…
admin/
en/
main.tpl - main template for admin zone
style.css
categories.tpl
…
mail/
en/
order_created/ - directory for mail notification
body.tpl - template for mail notification subject
subject.tpl - template for mail notification body
order_processed/
body.tpl
subject.tpl

…

It’s possible to switch between LiteCommerce skins by editing etc/config.php configuration file in section “skin_details”.

Compiled templates (resulting PHP code) are stored into the runtime directory var/run/skins. Every template is compiled only once and recompiled after you modify the original template.

== FLEXY templates design ==

=== Basic syntax ===

FLEXY tags can be enclosed within delimiters, { and }, or used within HTML tags, like . FLEXY interpreter parses the found tags info PHP code and displays code output in the place of FLEXY tags.

=== Comments ===

FLEXY comments are surrounded by asterisks, and the whole expression is surrounded by the delimiter tags like this: {* this is a comment *} Comments are not displayed in the final output of the template. Besides, FLEXY parser does not parse the template code between HTML comments, i.e. <!— This text wont be parsed by FLEXY à, but these comments are included into the final output.

=== Variables and methods ===

FLEXY template engine is designed to visualize object properties and these properties and methods can be easily accessed from the template assigned to an object. Generally, every LiteCommerce Dialog handler has a FLEXY template “main.tpl” assigned (located in the corresponding skins tree, depending on customer or administrator zone). After the Dialog handles a request, it uses the main template to visualize the processing result. The template accesses dialog variables and methods.

'''Example 5.2.1 Typical FLEXY template usage '''

<source>
// define handler for target “example”
class Dialog_example extends Dialog
{

var $template = “example.tpl”; // for customer zone, template skins/default/en/example.tpl will be
// used

var $greeting = “Hello, world!”;
// define getter method.

function &getGreetingMessage()
{
return $this->greeting;
}
}
</source>

<source lang="html4strict">
// template for target “example”
<html>
<body>
Example message from dialog property is {greeting:h}
Example message from dialog property is {greeting}
Example message from dialog method is {greetingMessage:h} in short form
Example message from dialog method is {getGreetingMessage():h} in full form
</body>
</html>
</source>

output:

<pre>
Example message from dialog property is Hello, world!
Example message from dialog property is Hello, world!
Example message from dialog property is Hello, world! in short form
Example message from dialog property is Hello, world! in full form
</pre>

=== Variable modifiers ===

Variable modifiers can be applied to variables and methods. To apply a modifier, specify one of the available modifiers (h, r, u) after a variable or a method. The variable and modifier must be separated by a colon.

* {variable:h} will display variable “as is”
* {variable} will display htmlspecialchars(variable)
* {variable:r} will display variable with quotes “ replaced with "
* {variable:u} will display urlencode(variable)

=== 5.2.5 Logical operators ===

FLEXY engine supports three logical operands, “Not”, ‘”And” (note that “And” syntax is different from PHP) and “Equal”. These operands can be used in control structures or widget parameters (see “widget” section below).

{| class="wikitable"
| '''Example'''
| '''Name'''
| '''Result'''
|-
| {if:!a}
| Not
| True if variable “a” is not TRUE or NULL or not set
|-
| {if:a&b}
| And
| True if variable “a” and “b” are TRUE or is not NULL or isset
|-
| {if:a=#literal_const#}
| Equal
| True if variable “a” is equal to literal constant “literal_const”
|-
| {if:a=b}
| Equal
| True if variable “a” is equal to variable “b”
|}

Operand “And” has a higher precedence, so the condition

<nowiki>!a&b&c</nowiki> will be parsed as

<nowiki>!(a&b&b)</nowiki>

{{Note|it is strongly recommended that you use method call in template control structures to calculate/combine logical conditions, i.e.}}

<pre>
{if:checkCondition} or {if:isCheckCondition()}

function isCheckCondition()
{
return $this->a && $this->b;
}
</pre>

=== Control structures ===

<pre>
{if:condition[&!=conditions..]}
{else:}
{end:}

<tag IF=”condition”/>, <tag if=”condition”/>
</pre>

{if} statements in FLEXY have much the same flexibility as PHP if statements, with a few additional features for the template engine. Every {if} must be paired with a closing tab {end:}. {else} statement is also permitted. All FLEXY conditionals are recognized, such as “&”, “!” and “=”.

{{Note| tag IF statement does not support “else” statement.}}

'''Example. If statement'''

<pre>
{if:name}
Name is {name:h}
{else:}
Name is not set
{end:}

{if:name=#John#}
Here is John
{else:}
{if:!name=##}
Hello, {name:h}!
{else:}
Please, enter your name.
{end:}
{end:}

Name is {name:h}
Name is not set
Here is John
</pre>

FLEXY foreach gives an easy way to iterate over arrays. foreach works only on arrays, and will issue an error when you try to use it on a variable with a different data type. If an array is empty or not defined, no output will be produced.

<pre>
{foreach:array,[index,]element}
{end:}
<tag FOREACH=”array,[index,]element>”/>
</pre>

'''Example. Foreach statement'''

<pre>
{foreach:products,pid,product}
Product name is {product.name:h} 
{end:}
<table IF=”products”>
<tr FOREACH=”products,pid,product”>
<td>Product name is is {product.name:h}</td>
</tr>
</table>
</pre>

{{Note|you cannot combine IF and FOREACH statements in one HTML tag, i.e.

 {* invalid condition *}}}

Please use separate tags for the statements.}}

===Built-in functions===

FLEXY engine provides access to any method call from a method associated with a template. LiteCommerce contains several methods already implemented in the core class Widget and used in the customer and admin zone templates:

'''date_format($date)
date_format($base, $field , $format)'''

Formats date with General settings / date format mask or with $format. Returns formatted string.

'''time_format($time)
time_format($base, $field, $format)'''

Formats date with General settings / date + time format mask or with $format. Returns formatted string.

'''price_format($price)
price_format($base, $field, $thousand_delim, $decimal_delim)'''

Formats price with General settings / price format. Returns formatted string,

'''addSlashes($value)
addSlashes($base, $field)'''

Escapes $value of base object field value with slashes. Returns escaped string.

'''split($array, $count)'''

Splits array into pieces with $count values in a piece. Returns array.

'''percent($count)'''

Calculates percent value of $count. Returns decimal.

'''truncate(&$baseObject, $field, $length, $etc, $break_words)
truncate($text..)'''

Truncates the base object field value or $text to the specified length. Returns truncated string.

'''wrap($object, $prop, $width)
wrap($text..)'''

Wraps the base object field value or $text with the specified width. Returns wrapped string.

'''rand()'''

Returns randomly generated value (for images fetch, for example). Returns decimal.

'''isSelected($val1, $val2, $val3)'''

Use this method to check whether the specified value is selected and present in request. Returns boolean.

'''isEmpty(&$data)'''

Checks for empty data. Returns boolean.

=== 5.2.8 Widgets ===

The basic component of LiteCommerce templates is a widget. Widget has its own attribute “<widget>” that is parsed by FLEXY and can be used only in templates. Combining widgets allows you to build a complex hierarchical visualization without writing a lot of dialog handlers.

'''Example 5.2.4 Using FLEXY widget tag'''

<pre>
{* code below only includes a specified template *}
<widget template=”welcome.tpl”>

{* code below will include template only for dialog handler “main”, “news” *}
<widget target=”main,news” template=”footnote.tpl”>

{* code below displays register form dialog *}
<widget target="profile" mode="register" class="CRegisterForm" template="common/dialog.tpl" head="New member" body="register_form.tpl" name="registerForm">
</pre>

When used without additional parameters, just with template=”template_file.tpl”, widget always includes the specified template in the place of the <widget> tag after it has been compiled with FLEXY. But the real power of widget is attribute-based behavior. Let us assume that we have two sample dialog pages that interact with a customer, register form and confirmation page. The first page will contain register form and confirmation dialog and the second page will display a register success message. First of all you need to develop two dialog handlers for the targets regform and regsuccess (see section “LiteCommerce request dispatcher” for more details) Both dialogs will have an inherited property template=”main.tpl”. From this main template all other widgets will be included.

'''Example 5.2.5 Main template '''

<source lang="html4strict">
<html>
<body>
<widget target=”regform” template=”regform.tpl”>
<widget target=”regsuccess” template=”regsuccess.tpl”>
</body>
</html>
</source>

When we access the “regform” target of the store via the URL cart.php?target=regform, the register form template will be included into output. After a user fills in the register form and submits it, the regform dialog handler uses the form data to create the user’s profile and redirects the customer to register success target with the URL cart.php?target=regsuccess. A confirmation/success template content will be displayed than.

'''Table 5.2.1 Widget tag attributes'''

{| class="wikitable"
| template=”path_to_template.tpl”
| Specifies the template that will be included for this tag. This field is required.
|-
| target=”target[,target[,…]]”
| The list of static handlers targets to display widget
|-
| mode=”mode”
| Additional static parameters to control widget displaying.
|-
| visible=”{condition}”
| Runtime evaluated condition to control widget displaying.
|-
| IF=”condition”
| Runtime evaluated condition to control widget displaying
|-
| class=”ComponentClass”
| Component class to be used as control class for widget. If component class is specified for widget, widget gets access to all the properties and methods of the component.
|-
| name=”name”
| Name for widget instance (instead of default run-time evaluated) Can be used in a dialog handler to address widget’s components
|-
| param=”value”

param1=”{condition}”

…

paramN=…
| You can pass any additional parameter into widget. Available from template through {widget.param}
|}

'''Note:''' If you’re using FLEXY IF condition inside widget tag, you should use XML-style closing bracket for widget, i.e. <widget IF=”condition” template=”template.tpl”/> FLEXY FOREACH condition is not supported within widget tag!

@@ Line 231: / Line 231: @@
 FLEXY engine provides access to any method call from a method associated with a template. LiteCommerce contains several methods already implemented in the core class Widget and used in the customer and admin zone templates:
-'''date_format($date)
+; '''date_format($date), date_format($base, $field , $format)''' : Formats date with General settings / date format mask or with $format. Returns formatted string.
-Formats date with General settings / date format mask or with $format. Returns formatted string.
+; '''time_format($time), time_format($base, $field, $format)''' : Formats date with General settings / date + time format mask or with $format. Returns formatted string.
-'''time_format($time)
+; '''price_format($price), price_format($base, $field, $thousand_delim, $decimal_delim)''' : Formats price with General settings / price format. Returns formatted string,
-Formats date with General settings / date + time format mask or with $format. Returns formatted string.
+; '''addSlashes($value), addSlashes($base, $field)''' : Escapes $value of base object field value with slashes. Returns escaped string.
-'''price_format($price)
+; '''split($array, $count)''' : Splits array into pieces with $count values in a piece. Returns array.
-Formats price with General settings / price format. Returns formatted string,
+; '''percent($count)''' : Calculates percent value of $count. Returns decimal.
-'''addSlashes($value)
+; '''truncate(&$baseObject, $field, $length, $etc, $break_words), truncate($text..)''' : Truncates the base object field value or $text to the specified length. Returns truncated string.
-Escapes $value of base object field value with slashes. Returns escaped string.
+; '''wrap($object, $prop, $width), wrap($text..)''' : Wraps the base object field value or $text with the specified width. Returns wrapped string.
-'''split($array, $count)'''
+; '''rand()''' : Returns randomly generated value (for images fetch, for example). Returns decimal.
-Splits array into pieces with $count values in a piece. Returns array.
+; '''isSelected($val1, $val2, $val3)''' : Use this method to check whether the specified value is selected and present in request. Returns boolean.
-'''percent($count)'''
+; '''isEmpty(&$data)''' : Checks for empty data. Returns boolean.
 === 5.2.8 Widgets ===

@@ Line 73: / Line 73: @@
 FLEXY template engine is designed to visualize object properties and these properties and methods can be easily accessed from the template assigned to an object. Generally, every LiteCommerce  Dialog handler has a FLEXY template “main.tpl” assigned (located in the corresponding skins tree, depending on customer or administrator zone). After the Dialog handles a request, it uses the main template to visualize the processing result. The template accesses dialog variables and methods.
-'''Example 5.2.1 Typical FLEXY template usage '''
+'''Example. Typical FLEXY template usage '''
 <source>
@@ Line 123: / Line 123: @@
 * {variable:u}  will display urlencode(variable)
-=== 5.2.5 Logical operators ===
+=== Logical operators ===
 FLEXY engine supports three logical operands, “Not”, ‘”And” (note that “And” syntax is different from PHP) and “Equal”. These operands can be used in control structures or widget parameters (see “widget” section below).
@@ Line 149: / Line 149: @@
 |}
-Operand “And” has a higher precedence, so the condition
+Operand “And” has a higher precedence, so the condition '''!a&b&c''' will be parsed as '''!(a&b&b)'''
 {{Note|it is strongly recommended that you use method call in template control structures to calculate/combine logical conditions, i.e.}}
@@ Line 355: / Line 349: @@
 '''Note:''' If you’re using FLEXY IF condition inside widget tag, you should use XML-style closing bracket for widget, i.e. &lt;widget IF=”condition” template=”template.tpl”/&gt; FLEXY FOREACH condition is not supported within widget tag!