Basics of working with widgets and templates

Basic principles

It's a recommended practice to separate the application logic from the presentation. We follow this parctice, so in LiteCommerce there are PHP classes (the logic) and template files (the presentation).

Sometimes you need HTML code to depend on a certain condition or have a portion of HTML repeat in a template file. Although the template engine we use allows coding simple conditions and loops directly in the template files, we recommended putting all complex presentation logic into classes. Usually, those classes ("view" classes) themselves do not output any HTML code. Instead, they declare methods with presentation logic and instruct the template engine which JavaScript and CSS files to load and which template file to render. So, what we call "Widget" is a combination of such a PHP class and multiple JavaScript, CSS and template files associated with the class.

There are two ways a widget or a template file can be inserted into a web page:

• using the "<widget />" tag to include a widget or a template file into that place
• using the "<list />" tag to mark the place ("view list") where other widgets and templates can insert themselves by declaring the "@ListChild" tag.

Since the second method ("view list") is more flexible and allows third-party modules to insert their widgets into your template without modifying it, we recommend you to use it whereever possible.

Every time the template engine renders a template file, there is a widget class whose methods can be called from the template:

• when inserting a widget, that is the widget class
• when inserting a template file, that is the "view" class that was used for the upper-level template your template file is being inserted into.

Inserting widget/template into template file

You can insert a widget or a template file by placing the following tag in the template where it should be inserted:

<widget template="[path_to_template_file]" class="[widget_class_name]" [arg_1]="[value_1]" [arg_2]="[value_2]" ... />

If you omit the "class" tag attribute, the template engine will render the specified template file using the same "view" class as is used for the upper-level template.

When inserting a widget, you can omit the "template" tag attribute, and the widget will automatically determine which template file to display. If you do specify the attribute, the template engine will render the specified template file instead of the file the widget class wants.

Working with View Lists

Adding widgets/templates to view list

To display a widget in a view list, you should edit the widget class and add the "@ListChild" tag to the PHPDoc for the class as follows:

/**
 * ... other PHPDoc tags
 * @ListChild (list="[name]", weight="[optional]", zone="[optional]")
 * ...
 */

Where the attributes are:

• "list" (required) - name of the view list, a unique identifier. To make names of nested view lists easier to understand, we join them together and use the "." character as delimiter; for example, by looking at the "checkout.review.selected.items" view-list name we may guess that this list will likely be shown in a template file that would appear in the "checkout.review.selected" view list, and so on.
• "weight" (optional) - a number that determines the position of the widget among other widgets and templates shown on the list; the greater the number, the closer the widget is to the end of the list.
• "zone" (optional) - makes the widget visible in a single user interface only; allowed values are "customer", "admin" and "mail".

To display a template file in a view list, you should edit the template file and add the "@ListChild" tag to template comments at the top of the file as follows:

{**
 * ...
 * @ListChild (list="[name]", weight="[optional]", zone="[optional]")
 * ...
 *} 

If you define multiple @ListChild tags for a widget/template, it will be added to all the view lists specified in the tags.

Displaying a view list from a template file

You can insert a view list into a template file by using one of the following tags:

<list name="[name]" />
<list name="[name]" type="nested" />
<list name="[name]" type="inherited" />

The "type" attribute determines how LiteCommerce will treat the "[name]" attribute:

• when the "type" attribute is omited "[name]" should be the full name of the view list to be displayed there
• when it is "nested" LiteCommerce will construct the full name of the view list by finding the upper-level view list and joining its name with the "[name]" attribute (using "." as delimiter)
• when it is "inherited" the full name will be constructed by joining the value returned by "getListName()" method of the current "view" class with the "[name]" attribute (using "." as delimiter).

If you want to pass extra arguments to widgets and templates which will be displayed in the list, you can do it as follows:

<list name="[list_name]" [arg_1]="[value_1]" [arg_2]="[value_2]" ... />
<list name="[list_name]" type="nested" [arg_1]="[value_1]" [arg_2]="[value_2]" ... />
<list name="[list_name]" type="inherited" [arg_1]="[value_1]" [arg_2]="[value_2]" ... />

JavaScript and CSS files

You can instruct LiteCommerce to load JavaScript and CSS files before displaying a widget by declaring the following methods in the widget class:

public function getCSSFiles()
{
    $list = parent::getCSSFiles();
    $list[] = 'CSS_file_path_1';
    $list[] = 'CSS_file_path_2';
    ...
    return $list;
}

public function getJSFiles()
{
    $list = parent::getJSFiles();
    $list[] = 'JS_file_path_1';
    $list[] = 'JS_file_path_2';
    ...
    return $list;
} 

All file paths are relative to the "skins/[name]/[language]/" directory.