The Component Tag Language

Declaring user interface controls

Component Tag Language

The component tag language eases the definition of user interface components within our templates.
Component tag language offers an extendible XML-based syntax that is interpreted by the framework and replaced by client-side specific code in run-time (i.e. XHTML + javascript code).

Note that components can be declared by using the tag language just in template based views. Out of the box Lion uses a view based on Smarty templates to render the user interface.

Declaring Components

The component tag has the following syntax:

Do not assign template placeholders to component properties.
To initialize a component with a value taken from the model, use the __EventHandler::init() method.

See the Event Handlers section for more information.

<comp:tag
    [name="component-name"]
    [
        property = value
    ]*
/>

where

tag is a name identifying the component that the tag represents to (i.e. commandbutton, inputbox, ...).
component-name is a name to identify a concrete component instance. This parameter is optional. If no names are supplied, a default one will be assigned to the component.
The list of pair property-value is a set of initial values to setup a component.

i.e.

<comp:commandbutton name="myButton" caption="Click on me!"/>
<comp:inputbox name="myInputBox" value=""/>

In this example, we have defined 2 components, a command button and an input box.
An yes, components are defined within the template content as part of.

Defining Containers

A component can be also defined by ussing a pair begin-end tags. It allows to close a piece of template content:

<comp:tag
    [name="component-name"]
    [
        property = value
    ]*
>

...

</comp:tag>

In that case, the content closed by the component can also contain other component tags. In that case, the component acts as container.

i.e.

<html>
<head>
  <title>Component rendering engine sample</title> 
</head>
<body>
 
<comp:form name="myTabPane">
 
  Login: <comp:inputbox name="login"/>
  
  Password: <comp:inputbox name="password" type="password"/>
  
  <comp:commandbutton name="submit" type="submit" caption="Login!"/>
 
</comp:form>
 
</body>
</html>

Defining Properties

Finally, a component can define properties within the enclosed area by ussing the comp-property tag.
This is really usefull to assign components as property for other components.

The syntax for ussing the comp-property is the following one:

<comp-property name="property-name">
(property value goes here)
</comp-property>

i.e.

<html>
<head>
  <title>Component rendering engine sample</title> 
</head>
<body>
 
<comp:commandlink name="about_us">
  <comp-property name="caption">
    <comp:resource key="about_us_i18n_literal"/>
  </comp-property>
</comp:commandlink>
 
</body>
</html>

In this example we are using the comp-property tag to assign a component to the caption property.

It's really important to note that we can not use template placeholders as attribute values within component tags, because the template is processed before the component render engine parses it.

However, Lion offers a workarround by ussing the tag comp-property as we have seen. i.e.:

<html>
<head>
  <title>Component rendering engine sample</title> 
</head>
<body>
 
  <!-- Assign a placeholder to a property within the  
       comp tag DOES NOT WORK: -->
  <comp:commandlink name="about_us" caption="{$about_us_literal}">
 
  <!-- Assign a placeholder to a property by ussing the
       comp-property tag WORKS: -->
  <comp:commandlink name="about_us">
    <comp-property name="caption">{$about_us_literal}</comp-property>
  </comp:commandlink>
 
</comp:tabpane>
 
</body>
</html>

In this example, we can not assign directly the placeholder about_us_literal as an attribute value, but we have the workarround of ussing the comp-property tag for the same purpose.

The The Hello World Deluxe is a simple but practical tutorial regarding components and event handlers.

The Component Tag Language

Table of Contents

Component Tag Language

Declaring Components

Defining Containers

Defining Properties