3.7. Instructions 3.7.4. opt:component: 3.7.3. opt:capture
« Previous; 3.7.5. opt:dtd
Next »

3.7.4. opt:component

opt:component creates a port for custom component objects in the template. To get to know more about components, see this chapter.

Name	Type	Required?	Description
from	Expression	Yes	Where to load the component object from
datasource	Expression	No	The datasource for the component
template	Identifier	No	The snippet name with the component content
*	Expression	No	Any other tags are converted into component attributes

The port is a runtime instruction and the components may be loaded from variables etc. In the example below, we can see, how to create a dynamic form generated by the script:

<form method="post" parse:action="$action">
<opt:section name="form">
    <opt:component from="$form.component" datasource="$formData" template="genericFormLayout" />
</opt:section>
</form>

Component port content

Parameters

The component parameter values can be read using $system.component.parameterName special variable call:

<opt:component from="$component">
    <p>Title: {$system.component.title}</p>
</opt:component>

The parameter values can be set either with the optional attributes of the opt:component tag or with the opt:set tag:

<opt:set str:name="parameterName" str:value="parameterValue" />

Both of the attributes require the OPT expressions. To provide a constant string value, we may use the str: namespace.

Displaying the component

The place where the component should be displayed is marked by the opt:display tag. The optional attribute values (OPT expressions) will be passed to the component display() method:

<opt:component from="$component">
    <p>Title: {$system.component.title}</p>
    <opt:display />
</opt:component>

Event handlers

The port may handle various events generated by the component with the opt:onEvent tag. It takes one required attribute: name with the event name:

<opt:component from="$component">
    <p>Title: {$system.component.title}</p>
    <opt:display />
    <opt:onEvent name="error">
        <p class="error">The field has been filled incorrectly: {$error}</p>
    </opt:onEvent>
</opt:component>

HTML tags with attributes managed by the components

The components may manage the attributes of certain HTML tags. This is primarily used to change the CSS class of the incorrectly filled component transparently. The tags are marked by the opt:component-attributes namespace:

<opt:component from="$component">
<div opt:component-attributes="default">
    <p>Title: {$system.component.title}</p>
    <opt:display />
    <opt:onEvent name="error">
        <p class="error">The field has been filled incorrectly: {$error}</p>
    </opt:onEvent>
</div>
</opt:component>

The opt:component-attributes attribute has been introduced in OPT 2.0.2. In the previous versions, the only way to manage the attributes was moving the tag to the special com namespace:

<opt:component from="$component">
<com:div>
    <p>Title: {$system.component.title}</p>
    <opt:display />
    <opt:onEvent name="error">
        <p class="error">The field has been filled incorrectly: {$error}</p>
    </opt:onEvent>
</com:div>
</opt:component>

The com namespace is still available for backward compatibility, but we do not recommend to use it in the new projects.

Integration with snippets

Usually, we would like to pack the port content into a snippet in order to use the same form layout across all the forms in our project. We may insert the snippet either using the ordinary opt:use attribute or with the template attribute that supports component-specific features.

Take a look at the following example: we have some statically deployed components. We want to use the shared layout, but we need to set the extra component parameters, so we use the template attribute. It does not remove the opt:set tags from the default content:

<opt:snippet name="formLayout">
<div opt:component-attributes="default">
    <p>{$system.component.title}</p>
    <p><opt:display /></p>
</div>
</opt:snippet>
 
<opt:someComponent template="formLayout">
    <opt:set str:name="title" str:value="Your age" />
</opt:someComponent>

The code above is equivalent to:

<opt:someComponent>
<opt:set str:name="title" str:value="Your age" />
<div opt:component-attributes="default">
    <p>{$system.component.title}</p>
    <p><opt:display /></p>
</div>
</opt:someComponent>

Open Power Template 2.0

opt:component