Template elements allow you to declare a set of visual elements in one place and then insert those visual elements into other places in your UJML code. See Visual Elements. Templates provide reusable chunks of user interface code which may be copied as many times as needed.

Templates are declared with a templates element containing one or more template elements. See templates, template. Each template element has a name, which is used to refer to that template in UJML code. See Identifiers. The template element contains a display element, which contains visual elements. See display, Visual Elements. 

Somewhere else in your UJML program, you can declare an expand element inside of a state transition. See expand, State Transitions. When the state transition becomes active, the byte code for the template is copied to the code location for the expand element. Any scripting expressions in the template are evaluated during expansion.

Templates simplify your UJML programs by reducing the number of times you need to hand-code similar things. Used carefully, templates result in cleaner, easier-to-maintain code.

Templates result in smaller byte code files. See Byte Code Files. This reduces network bandwidth requirements and decreases application startup time. When templates are used in conjunction with state variable arrays which have 'default' state transitions containing expand elements, the compiled code is smaller than if the visual elements of the template were used inside of the transition. See State Transitions. At run time, the template byte code is copied only to those transitions of the state variable array which are activated. 

Note: Templates will not necessarily reduce memory footprint at run time. If all elements of a state variable array have active state transitions which expand templates, the memory footprint will be much the same as if templates had not been used.

Templates are the only way a state machine can provide visual elements with controllable z-order. See State Machines, Z-Order. This is because visual elements displayed by transitions inside of state machines are restricted to the location of the state machine in the module, and therefore display either toward the bottom or the top of the z-order for that module. However, you can expand a template provided by a state machine anywhere and the template visual elements will have the z-order of the expand element.

The scripting code in a template may change variables and state variables in the same module scope as the template was declared. See Data Scoping and Sharing. 

UJML templates are named and use the same scoping rules as any other identifier. See Identifiers, Template Scoping and Sharing. This means only expand elements in the proper scope may refer to them. For example, a template declared and exported in one partition may only be expanded in that partition or in another partition that imports it. However, templates can only access variables in the same scope as they are declared. So, in our example of expanding a template declared in another partition, that template can only use variables in its scripting expressions which are declared in the partition declaring the template.

Template nesting is allowed; templates may contain expand elements for other templates. There is no limit to template nesting other than device memory. 

Note: Avoid circular references where a template expands itself or expands another template that expands itself.

When expanded inside of a state transition, a scripting expression in a template can not call the _state_index() function the way a scripting expression declared directly in the transition element can. See State Transitions. 

No matter where a template is expanded, its scripting elements are scoped to the context where it was declared. For example, in templates provided by state machines, the scripting elements in the templates may only refer to variables and functions within the scope of the state machine. This means, if your application contains a variable named 'foo' and also contains a state machine with a variable named 'foo', templates declared inside the state machine will use the 'foo' from the state machine scope even if they are expanded by UJML code in the application scope. See State Machines, State Machine Scoping and Sharing.

Figure 1. Templates expanded by the colors.ujml sample.

The following example shows how to declare two templates, one that displays a grid point and one that displays a box with a label. It is part of the colors.ujml sample.

<templates>
    <template name="tGridPoint">
        <display>
            <box>
                <x>
                    <eval>
                        mGridSpacing + (mGridCtrX * mGridSpacing) - 1
                    </eval>
                </x>
                <y>
                    <eval>
                        mGridSpacing + (mGridCtrY * mGridSpacing) - 1
                    </eval>
                </y>
                <width>1</width>
                <height>1</height>
                <fg>&_COLOR_WHITE;</fg>
                <bg>&_COLOR_WHITE;</bg>
            </box>
        </display>
    </template>
    <template name="tColorBox">
        <display>
            <box>
                <x>
                    <eval>
                        &COLOR_SPACING; + (mColorCtrX * &COLOR_SPACING;) +
                            (mColorCtrX * mColorWidth)
                    </eval>
                </x>
                <y>
                    <eval>
                        &COLOR_SPACING; + (mColorCtrY * &COLOR_SPACING;) +
                            (mColorCtrY * mColorHeight)
                    </eval>
                </y>
                <width><eval>mColorWidth</eval></width>
                <height><eval>mColorHeight</eval></height>
                <fg>0xFFDDEEFF</fg>
                <bg><eval>mColorVal[mColorCtrY][mColorCtrX]</eval></bg>
                <x-clip>true</x-clip>
                <label>
                    <text><eval>mColorName[mColorCtrY][mColorCtrX]</eval></text>
                    <x>&COLOR_SPACING;</x>
                    <y>&COLOR_SPACING;</y>
                    <fg><eval>mColorNameColorVal[mColorCtrY][mColorCtrX]</eval></fg>
                    <size>&_FONT_SIZE_SMALL;</size>
                    <style>&_FONT_STYLE_PLAIN;</style>
                    <face>&_FONT_FACE_SYSTEM;</face>
                </label>
           </box>
        </display>
    </template>
</templates>

The following example shows how to declare two transitions, which expand the templates declared above. It is part of the colors.ujml sample.

<states>
    <!-- Show background grid. -->
    <state var="sGrid" index="*, *">
        <transition value="true">
            <display>
                <expand template="tGridPoint"/>
            </display>
        </transition>
    </state>
    <state var="sColors" index="*, *">
        <transition value="true">
            <display>
                <expand template="tColorBox"/>
            </display>
        </transition>
    </state>
</states>

The following example shows how to declare a template which is contained by the 'ScreenPane' state machine. It is part of the screenpane.ujms sample.

<template name="tPaneBox" visibility="public">
        <display>
            <box>
                <x><eval>mPaneOffsetX - mPaneBorder</eval></x>
                <y><eval>mPaneOffsetY - mPaneBorder</eval></y>
                <width><eval>mPaneWidth + (mPaneBorder * 2)</eval></width>
                <height><eval>mPaneHeight + (mPaneBorder * 2)</eval></height>
                <bg><eval>mPaneBorderColor</eval></bg>
            </box>
            <box>
                <x><eval>mPaneOffsetX</eval></x>
                <y><eval>mPaneOffsetY</eval></y>
                <width><eval>mPaneWidth</eval></width>
                <height><eval>mPaneHeight</eval></height>
                <bg><eval>mPaneBackColor</eval></bg>
            </box>
        </display>
</template>

The following example elaborates on the template declared above. It is part of the lunarlander.ujml sample.

<state var="sPaneBox">
    <transition value="true">
        <display>
            <expand template="ScreenPane.tPaneBox"/>
        </display>
    </transition>
</state>

State Transitions, <template>, <expand>, colors.ujml, screenpane.ujms, lunarlander.ujml