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.

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.