Templates in Depth

Defining a template

The template mechanisms is based on the dijit/_TemplatedMixin mechanism of dojo. See the dojo _TemplatedMixin reference guide for more details.

Basically, a template is an HTML document which describes the overall structure of the layout. To add widgets to individual HTML elements, specify an attribute named data-dojo-attach-point on that HTML element. The value of this attribute is an arbitrary string value that designates the widget to attach, for example map or scalebar. To attach a widget component to a data-dojo-attach-point the component has to provide a dijit.Widget interface and must have a property named widgetRole. The widgetRole value must be the same as the name of the data-dojo-attach-point within the template.

It is possible to define windows in the template as containers for widgets. The following code creates a window and adds the widget with the widgetRole "streetView“ to it.

<div data-dojo-attach-point="streetView" class="dijitHidden"
    data-template-window="
       title:'${i18n.streetview.title}',
       dockable:true,
       dockingBar:'dockingBarBottom',
       dockTool:'streetViewToggleTool',
       marginBox:{w:400,h:300,r:145,b:45},
       maximizable:true,
       closable:true,
       minimizeOnClose:true,
       minSize:{w:250,h:200},
       windowClass:'myCustomStyleClass'"

    data-template-windowevents="onShow:'show',onHide:'hide'">
</div>

The values of the element attributes window and windowEvents are in JSON format. In this example the window gets a title that is defined in the bundle.js files in the nls folder of the template. The window is dockable, that means a button is added to the docking bar specified with the key dockingBar. The tool to initiate when the docking button is clicked is specified with the dockTool parameter. For details about creating windows, see the ct/ui/desk­top/WindowManager class documentation. The windowEvents attribute defines event handlers for window events. In the preceding code sample the method show of the widget inside this window is called when the window is shown. Analogously, the method hide is called when the window is hidden.

The template folder

Each template is stored in a separate folder. The folder's name is the same as the name of the template.

The template folder contains the NLS-files for internationalization, the HTML files for different layouts of the same template, and a <template_name>.js file. The <template_name>.js file describes, which HTML files are available and contains the screen rules.

seasons
├─ seasons.css
├─ seasons.html
├─ seasons.js
├─ seasons_desktop.css
├─ seasons_mobile_landscape.html
└─ nls
   ├─ bundle.js
   └─ de
      └─ bundle.js

Layouts

A template can have several layouts, each described by a separate HTML file. A layout is chosen based on size restrictions of the viewport. The layout is switched when the size of the viewport changes. The HTML template as a string is assigned to the templateString property.

Template with a single layout:

import templateString from "text!./template.html";

export default {
    templateString: templateString,
    i18n: ["bundle"]
};

Template with multiple layouts:

import small from "text!./small.html";
import medium from "text!./medium.html";
import big from "text!./big.html";

export default {
        layouts:[{
            name: "small",
            maxWidth : 300,
            templateString: small
        },{
            maxWidth : 1024,
            templateString: medium
        },{
            templateString: big
        }],
        i18n: ["bundle"]
    };

At the beginning of the <template>.js file three HTML layout files are imported: layouts for small, medium, and large screens. The small layout is visible up to a width of 300px. The medium layout is chosen up to a width of 1024px and only if no rule before it is used and the big layout is chosen if none of the layouts before are selected.

You can specify a name for a layout. The value of this attribute is used to add a CSS class to the root DOM node of the application. In the preceding code sample, the CSS class ctLayout_small is appended to the DOM node when the layout small is active.

The following layout rule properties are available:

Property Possible values Description
minWidth Positive integers Rule applies when the width of the viewport is at least minWidth pixels.
maxWidth Positive integers Rule applies when the width of the viewport is at most maxWidth pixels.
minHeight Positive integers Rule applies when the height of the viewport is at least minHeight pixels.
maxHeight Positive integers Rule applies when the height of the viewport is at most maxHeight pixels.
orientation portrait|landscape Rule applies when the orientation of the screen is either portrait or landscape. The orientation is portrait when the height of the screen is greater than or equal to the screen width. Otherwise the orientation is landscape.
requiredExecutionEnvironment See class ct.osgi.ExecutionEnvironment Rule applies when the width of the viewport is at least minWidth pixels.
excludedExecutionEnvironment See class ct.osgi.ExecutionEnvironment Rule applies when the width of the viewport is at least minWidth pixels.

Template with multiple layouts using layout breakpoint names:

import medium from "text!./template.html";
import small from "text!./small.html";

export default {
    layouts: {
        "medium-landscape": medium,
        "extra-small-landscape": small
    },
    i18n: ["bundle"]
};

An alternative to the object syntax for sub layouts it is possible to use layout breakpoint names. In the preceding sample, two different layouts are registered, the template engine detects orientation and current screen size and finds the best matching template according to the defined layout break point name. A list of available layout break point names are defined in templatelayout.