Templates in-depth

Defining a template

The template mechanisms is based on the dijit/_TemplatedMixin mechanism of Dijit UI Library for Dojo. See the _TemplatedMixin reference guide for more details.

Basically, a template is an HTML document that 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

Template 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 300 pixels.

The "medium" layout is if:

the width of the viewport is less or equal to 1024 pixels, and
rule before it applies, 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

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` or `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 current execution environment is one of the specified environments.
`excludedExecutionEnvironment`	See class `ct.osgi.ExecutionEnvironment`	Rule applies when the current execution environment is not one of the specified environments.

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 or 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 current execution environment is one of the specified environments.

excludedExecutionEnvironment

See class ct.osgi.ExecutionEnvironment

Rule applies when the current execution environment is not one of the specified environments.

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"]
};

As 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 breakpoint name. A list of available layout breakpoint names are defined in the templatelayout bundle .