====== Introduction to {{macro}}. {{macro}} templates syntax and entities. ======

This page demonstrates a simple example of {{macro}} template and covers briefly {{macro}} syntax and template entities like tags, output expressions and filters.

===== {{macro}} template example =====

<code xml>
{{wrap with="page.phtml" in="content_zone"}}
<img src={$#photo.largeFileUrl} />
<dl>
<dt>Author:</dt><dd>{$#photo.member.name}</dd>
<dt>Category:</dt><dd>{$#photo.category.title}</dd>
<dt>Title:</dt><dd>{$#photo.title}</dd>
<dt>Tags:</dt>
<dd>
{{list using='{$#photo.tags}' as='$tag'}}
  <ul>
  {{list:item}}
    <li>{$tag.title|uppercase}</li>
  {{/list:item}}
  </ul>
  {{list:default}}
  No tags.
  {{/list:default}}  
{{/list}}
</dd>
{{include file="photo/marks.phtml"}}
</dl>
{{/wrap}}
</code>

===== {{macro}} template entities =====


==== Tags ====

There are several **tags** in our example:
<code xml>
{{wrap with="page.phtml" in="content_zone"}}...{{/wrap}}

{{list using='{$#photo.tags}' as='$tag'}}...{{/list}}

{{include file="photo/marks.phtml"/}}
</code>

Tags are commonly have a closing tag (like **list** or **wrap**), but there also tags that don't have a closing tag like **slot**.

Tags have one or more **attributes**. In our example tag **list** has **using** and **as** attributes.

There are rules that are applied to tags. For example, some tags should be used inside particular tag in template, some tags need required attributes, etc. In most cases {{macro}} compiler will warn you about such errors and will display template file path and line number where error has appeared.

{{macro}} already has a [[tags|lot of tags]] for most every-day tasks like rendering lists or tables, working with forms and form elements, any kind of templates composition, lists pagination etc.

[[.tags_intro|More about tags]].

==== Output expressions ====

Output expressions (or just expressions) are used to output variable values.

In our example expressions are:
<code xml>
  {$tag.title|uppercase}
  {$#photo.largeFileUrl}
</code>

You can think about expression as php "echo" operation since{{macro}} really compiles output expressions into <? echo $variable_name; ?> constructions. 

The symbol of grid before variable name tells {{macro}} to convert {$#var_name} into {$this->var_name}. On page [[important_details|{{macro}} compilation and rendering. How to run {{macro}} template]] you will know what {{macro}} compiles template into unique php-class. Thus expression {$#var_name} means to echo some attribute of the generated class.

Expressions are also used as tag attributes values in some cases. In such cases expressions are just point at variables and not rendered.

There are also so called "path-based" expressions with dots between elements. For example, {$tag.title} expression will be actually rendered into something like <?php if(isset($tag['title'])) echo $tag['title']; ?>

[[.expressions|See more about expressions]].

==== Filters or formatters ====

Filters (sometimes called formatters) are used to modify/format variables on rendering. Filters are applied to output expressions. 

In our example:
<code xml>
  {$tag.title|uppercase}
</code>

  * uppercase - is a simple filter for rendering variable in UPPERCASE. You can think about this filter as an alias for php-function strtoupper(), that is applied to $tag.title value.

In most cases filters are just wrappers for commonly used php-functions and several unique Limb3 functions.

[[.filters_intro|More about filters]].

==== Further reading ====

  * [[.important_details|{{macro}} compilation and rendering. How to run {{macro}} template.]] - you will know how {{macro}} actually ticks. This page is a key for effective {{macro}} usage.
  * [[.data_sources|How {{macro}} template gets data for displaying?]]