Template

From Frontal Wiki

Introduction to the template Tag

The 'template' tag is used to create snippets of Frontal code that can be used and reused throughout the Frontal document. For example, Frontal uses template tags to define its scroll bars. This is taken from The Default Frontal Style Sheet and is the template used for vertical scroll bars:

<template name="frScrollbarVert">
    <div class="frScrollbarVert">
        <!-- <div name="up" /> -->
        <div name="track">
            <div name="trackButton" />
            <div name="slider" />
        </div>
        <!-- <div name="down" /> -->
    </div>
</template>

By defining a template, we haven't added any visual elements to the Frontal definition. All we've done is marked a snippet of the Frontal definition for later use. In this case, that later use is adding a scroll bar to an element.

We can use this same mechanism for our own purposes. Here for example is a template that defines a complex structure of elements.

<template name="myTemplate">
    <div class="container">
        <img />
        <text />
    </div>
</template>

Now we can use our template via some Frontal script. Here we add a style sheet that will match the elements in our template. Then we define our template. Next, we create a function that copies the template into the Frontal document and sets the "src" attribute of the "img" tag and the text of the "text" tag. And finally, we call the function to add several slides to our document. Run the following code sample.

<style><![CDATA[
    document
        {
            // Scroll our document.
            scroll: auto;
        }
    .container
        {
            // Create a padded gray frame for the slide.
            width: 320px;
            height: 280px;
            float: left;
            background-color: gray;
            margin: 10px;
            padding: 5px;
        }
    .container img
        {
            // Set our image dimensions. Frontal will scale the source to fit.
            width: 100%;
            height: 240px;
			overflow: hidden;
        }
    .container text
        {
            // Set our text attributes for a description.
            margin-top: 5px;
            width: 100%;
            height: 30px;
            scroll: auto;
            color: orange;
        }
]]></style>
<template name="myTemplate">
    <div class="container">
        <img />
        <text />
    </div>
</template>
<script><![CDATA[
function addSlide ( src, description )
{
    var newSlideDefn = com.frontalcode.DocElemTemplate.getTemplateByName ( document, "myTemplate" ).copy ( );
    document.insertXML ( newSlideDefn );
    var newSlideElem = document.getNodeElement ( newSlideDefn );
    newSlideElem.gE ( 1 ).sA ( "src", src );
    newSlideElem.gE ( 2 ).text = description;
}
addSlide ( "http://www.frontalcode.com/assets/images/image_1.jpg", "Lorem ipsum dolor sit amet, consectetur adipisicing elit." );
addSlide ( "http://www.frontalcode.com/assets/images/image_2.jpg", "Lorem ipsum dolor sit amet, consectetur adipisicing elit." );
addSlide ( "http://www.frontalcode.com/assets/images/image_3.jpg", "Lorem ipsum dolor sit amet, consectetur adipisicing elit." );
addSlide ( "http://www.frontalcode.com/assets/images/image_4.jpg", "Lorem ipsum dolor sit amet, consectetur adipisicing elit." );
addSlide ( "http://www.frontalcode.com/assets/images/image_5.jpg", "Lorem ipsum dolor sit amet, consectetur adipisicing elit." );
addSlide ( "http://www.frontalcode.com/assets/images/image_6.jpg", "Lorem ipsum dolor sit amet, consectetur adipisicing elit." );
addSlide ( "http://www.frontalcode.com/assets/images/image_7.jpg", "Lorem ipsum dolor sit amet, consectetur adipisicing elit." );
addSlide ( "http://www.frontalcode.com/assets/images/image_8.jpg", "Lorem ipsum dolor sit amet, consectetur adipisicing elit." );
addSlide ( "http://www.frontalcode.com/assets/images/image_9.jpg", "Lorem ipsum dolor sit amet, consectetur adipisicing elit." );
addSlide ( "http://www.frontalcode.com/assets/images/image_10.jpg", "Lorem ipsum dolor sit amet, consectetur adipisicing elit." );
]]></script>

The "addSlide" function is a little complex so let's look at it more closely. First, we use the static method "getTemplateByName" of the DocElemTemplate class to find our template:

    var newSlideDefn = com.frontalcode.DocElemTemplate.getTemplateByName ( document, "myTemplate" ).copy ( );

Because getTemplateByName returns the same XMLList every time it is called for a particular template, we actually want to work with a copy of the result and that explains the "copy ( )" call at the end. ("copy" is a method of the Flash XMLList class of which the return of getTemplateByName is an instance.)

Templates are identified by the value of their "name" attribute and so in this case since we gave our template the name "myTemplate" then that is what we are searching for.

Next, we want to add the template's contents to our document.

    document.insertXML ( newSlideDefn );

Next, we want to get the instance of the Frontal object that is implementing the XML node we just added. We do that using the "getNodeElement" method of our document object. This method takes a single XML node and returns the instance of the Frontal class responsible for it. In this case, since newSlideDefn is a "div" tag, this method is returning an instance of the Container class.

    var newSlideElem = document.getNodeElement ( newSlideDefn );

Now we can use our standard methods to access this element's children (see Accessing Frontal Tags for Scripting) and to manipulate them. In this case, the first child is the 'img' tag and we set its "src" attribute to the src parameter passed in to the function:

    newSlideElem.gE ( 1 ).sA ( "src", src );

The second child is the 'text' tag and we set its value to the description parameter passed in to the function:

    newSlideElem.gE ( 2 ).text = description;

An obvious advantage of this approach is brevity. A less obvious advantage is the ease with which modifications can be made. If this example had been done without using a template, then any change to the structure of a slide would have required making edits in 10 places. But with the template, the change need only be made in one place - the template itself.

Implementation

The 'template' element is implemented by the DocElemTemplate class which extends the DocumentElement class.

Properties

The 'template' element adds these properties to those of the DocumentElement class:

• template: Returns an instance of the Flash XMLList class instantiated from the contents of the 'template' tag.

Methods

The DocElemTemplate class defines this static method:

• getTemplateByName: This method searches all the templates in the document for the one with the provided name. If one is found, the method returns an instance of the Flash XMLList class created by the template's contents. This same XMLList instance is returned by multiple calls to getTemplateByName and so should be copied using the XMLList "copy" method before use. The method takes a single parameter:
  • name: The name of the template to return.

Attributes

These attributes are particular to the 'template' tag:

• name: Use the name attribute to give the template a name. It is this name that is used by getTemplateByName. If two templates have the same name then the latter overwrites the former.