Templates: Part III

Dynamic Property Tags

Dynamic property tags are very similar to dynamic content tags, except that they are applied to component properties. The purpose of dynamic property tags is to allow more versatile component property configuration. Note, you are not required to use dynamic property tags because what can be done using dynamic property tags can also be done in PHP code. However, using dynamic property tags bring you much more convenience at accomplishing the same tasks. The basic usage of dynamic property tags is as follows,

<com:ComponentType PropertyName=DynamicPropertyTag ...>
body content
</com:ComponentType>

where you may enclose DynamicPropertyTag within single or double quotes for better readability.

Like dynamic content tags, we have expression tags, databind tags, parameter tags, asset tags and localization tags. (Note, there is no statement tag here.)

Expression Tags

An expression tag represents a PHP expression that is evaluated when the control is in PreRender stage. The expression evaluation result is assigned to the corresponding component property. The format of expression tags is as follows,

<%= PhpExpression %>

In the expression, $this refers to the control owning the template. The following example specifies a TLabel control whose Text property is initialized as the current page title when the TLabel control is being constructed,

<com:TLabel Text=<%= $this->Page->Title %> />

Databind Tags

Databind tags are similar to expression tags, except that they can only be used with control properties and the expressions are evaluated only when a dataBind() call is invoked on the controls represented by the component tags. In the expression, $this refers to the control owning the template. Databind tags do not apply to all components. They can only be used for controls.

The format of databind tags is as follows,

<%# PhpExpression %>

Since v3.0.2, expression tags and databind tags can be embedded within static strings. For example, you can write the following in a template,

<com:TLabel>
  <prop:Text>
  Today is <%= date('F d, Y',time()) %>.
  The page class is <%= get_class($this) %>.
  </prop:Text>
</com:TLabel>

Previously, you would have to use a single expression with string concatenations to achieve the same effect.

Parameter Tags

Parameter tags are used to assign application parameter values to the corresponding component properties. The format of parameter tags is as follows,

<%$ ParameterName %>

Note, application parameters are usually defined in application configurations or page directory configurations. The parameters are evaluated when the template is instantiated.

Asset Tags

Asset tags are used to publish private files and assign the corresponding the URLs to the component properties. For example, if you have an image file that is not Web-accessible and you want to make it visible to end-users, you can use asset tags to publish this file and show the URL to end-users so that they can fetch the published image. The asset tags are evaluated when the template is instantiated.

The format of asset tags is as follows,

<%~ LocalFileName %>

where LocalFileName refers to a file path that is relative to the directory containing the current template file. The file path can be a single file or a directory. If the latter, the content in the whole directory will be made accessible by end-users.

BE VERY CAUTIOUS when you are using asset tags as it may expose to end-users files that you probably do not want them to see.

Localization Tags

Localization tags represent localized texts. They are in the following format,

<%[string]%>

where string will be translated to different languages according to the end-user's language preference. The localization tags are evaluated when the template is instantiated. Localization tags are in fact shortcuts to the function call Prado::localize(string).