Template syntax

From The Smartest Wiki
Jump to: navigation, search

Smartest's template language is built on top of popular tempting engine Smarty, but uses different template tags to avoid difficulties with Javascript:

<?sm: and :?>

Variables and values

To display the value of a variable in a Smartest template, simply write it enlosed in template tags, preceded by a dollar sign:

<?sm:$variable:?>

Arrays can be accessed either with the dot(.) operator for non-numeric keys:

<?sm:$myarray.key:?>

<?sm:$myarray.subarray.key:?>

Or using square brackets for numeric keys:

<?sm:$myarray[0]:?>

<?sm:$myarray[0][5]:?>

Objects also use the dot syntax, and the line between arrays and objects in Smartest template syntax is deliberately blurred. The part after the dot is called an offset:

<?sm:$myobject.offset:?>

Objects, offsets and the dot syntax

Smartest makes heavy use of these offsets, which often fetch and return further objects with their own offsets available, such as in the following hypothetical case:

<?sm:$this.article.thumbnail.image.200x200.web_path:?>

Let's pick this apart:

  • $this -> Class:SmartestPageRenderingDataRequestHandler object. Provides background information about the current page being rendered. For information on all the information available via the $this object's offsets, see $this variable offsets.
  • $this.article -> We are viewing a meta-page of a model called Article, so the SmartestPageRenderingDataRequestHandler can return a Class:SmartestCmsItem-derived object for the Article item currently being viewed
  • $this.article.thumbnail -> Continuing our hypothetical scenario, imagine that the Article model in use has a "Thumbnail" property that refers to an image file in the media library. Properties like this, having a data type SM_DATATYPE_ASSET, are always an instance of the Class:SmartestRenderableAsset class in the template layer.
  • $this.article.thumbnail.image -> When SmartestRenderableAsset objects refer to binary images, the image file itself, on disk, can be accessed via the .image offset, which returns an instance of the Class:SmartestImage class, containing the actual image. (Note this is a subclass of Class:SmartestFile)
  • $this.article.thumbnail.image.200x200 -> The SmartestImage class uses offsets for easy resizing and automatic cropping. Here, the image is resized and cropped as necessary in order to be 200 pixels by 200 pixels. This offset returns a new instance of SmartestImage, meaning these operations can be chained. See Class:SmartestImage for more information on image manipulation using offsets.
  • $this.article.thumbnail.image.200x200.web_path -> Once an image is resized and cropped as necessary, in addition to being rendered as an <img> tag in HTML, other information can also be retrieved about it. In this case, the .web_path offset is used to retrieve a relative URL to the image, in the cache folder where resized and cropped images are saved.

For more information on these objects and the offsets available on them, see Template data, Basic types, and Class:SmartestCmsItem

Conditionals

In situations where you want the template to display something only if a certain variable has the right value, you can use a conditional <?sm:if:?> tag:

<?sm:if $myvariable == "value":?>
   This text won’t always display.
<?sm:/if:?>

You can also cater for alternative conditions using the elseif and else keywords:

<?sm:if $myvariable == "value":?>
   This text won’t always display.
<?sm:elseif $myvariable == "othervalue":?>
   This text might display instead.
<?sm:else:?>
   Otherwise this text will display.
<?sm:/if:?>

Functions

Unlike many other template languages, Smarty also has the ability to support primitive functions.

To call a function, enclose its name in Smartest tags like this: <?sm:myfunction:?>

If the function requires arguments to be passed to it, you pass them as quoted attributes, similar to HTML attributes:

<?sm:myfunction argument="foo" second_argument="bar":?>

Smarty functions don’t return their results as in a normal language, but simply display them. This is because Smarty is only for presentation, not for any complex type of logic.

For a complete list of template functions, see Template functions

String modifiers

Modifiers are applied to variable values via the pipe character, |.

Here, the upper modifier is applied to the variable $myvariable:

<?sm:$myvariable|upper:?>

For a complete list of modifiers, see String modifiers

Looping

Foreach

For basic looping, if for example you need to print something for every member of an array, such as a table row or bullet point, you would use the foreach block, which is a jilt-in component of Smarty:

<ul>
<?sm:foreach from=$myarray key="key" item="foo":?>
  <li><?sm:$key:?>=><?sm:$foo:?></li>
<?sm:/foreach:?>
</ul>

This would print the key and value of the array for every member of that array. The value of $key would be whatever the original array keys were.

The Repeat Block

For more sophisticated looping, you can also use Smartest's <?sm:repeat:?> block. The repeat block can loop through an array, or you can give it a set name, file gallery name, tag name, or page group name:

<ul>
<?sm:repeat from="my_data_set" key="index" item="article":?>
  <li><?sm:$index:?>=><?sm:$article.name:?></li>
<?sm:/repeat:?>
</ul>

The key, in the above cases called $index, will usually be an integer starting at zero. If you want an integer that starts at 1, for instance if you are doing page numbers, use the automatic variable $iteration:

<ul>
<?sm:repeat from="my_data_set" key="index" item="article":?>
  <li><?sm:$iteration:?>. <?sm:$article.name:?></li>
<?sm:/repeat:?>
</ul>

Page groups

To loop through a page group, use the pagegroup: or page_group: namespace, and the name of the page group.

<ul>
<?sm:repeat from="pagegroup:my_page_group" key="index" item="page":?>
  <li><?sm:$index:?>=><?sm:$page.title:?></li>
<?sm:/repeat:?>
</ul>

For a guide on how to use the looping of page groups for building a navigation, see Navigation bars with page groups.

File galleries

To lop through file galleries, use the gallery: namespace, and the name of the gallery.

<ul>
<?sm:repeat from="gallery:my_gallery" key="index" item="membership":?>
  <li><?sm:$index:?>=><?sm:$membership.caption:?>, <?sm:$membership.file:?></li>
<?sm:/repeat:?>
</ul>

In the case of file galleries and the repeat block, the files themselves are not retrieved, but instances of the SmartestAssetGalleryMembership class, which contains additional contextual metadata specific to that file's appearance in that particular gallery, such as captions, and alternative thumbnail images for non-image files. The file (as above) is accessed via the .file offset. If you need files directly, without the membership wrapper class, you can add a 'skip_memberships="true"' parameter to the repeat block, and then the .file offset will not be necessary, but gallery-specific contextual metadata will not be available:

<ul>
<?sm:repeat from="gallery:my_gallery" key="index" item="file" skip_memberships="true":?>
  <li><?sm:$index:?>=><?sm:$file:?></li>
<?sm:/repeat:?>
</ul>

See also Repeat tag