templates

The Templates bundle is responsible for managing the layout templates in an app. The bundle provides the meta information about available templates. Additionally, it provides a drop-down list to switch between templates. Switching and rendering of templates is implemented in the templatelayout bundle.

This bundle is a core element of map.apps. It has to be enabled to run map.apps.

Usage

No configuration is required.

Defining a new template

For a detailed description of the anatomy of a template, see the template documentation.

Motivation

Templates define different arrangements for widgets within apps and allow users to switch among different user interface layouts. The templating mechanism consists of the two bundles templates and templatelayout.

The templates bundle provides a model for managing the available templates and adding the template specific CSS rules to the main HTML document. It allows to switch between different templates and also provides a drop down box widget component for this task (TemplateSelector component).

Components

• TemplateModel

Global events

Following global events are fired by the bundle:

Use Cases

Declare a layout widget in a custom bundle

Every bundle can declare widget definitions inside a special manifest property layout-widgets.

The layout-widget property is an array of widget definitions. Each widget is an object as described earlier for the widget property of the TemplateModel component. This mechanism provides a way to link widgets provided in custom bundles into an existing app without having to add new attach points to the layout template.

The property priority is only allowed in the manifest.json file. See the following sample for an explanation.

Example for layout-widgets in manifest.json file:

"layout-widgets": [
{
    // corresponds to the widgetRole property of the widget to display
    "widgetRole": "mywidget",

    // if other bundles define a widget definition for the same widget, the one that has the highest priority wins.
    // default priority is 0
    "priority" : 10,

    // show widget with widgetRole "mywidget" in a window
    "window": {
        "title": "My Widget",
        "marginBox": {
            "l": 50,
            "b": 150
        }
    }
},
{
    // the widget role
    "widgetRole": "mysecondwidget",
    // mysecondwidget should be placed in the "placeholder" attachpoint
    "attachTo": "placeholder"
}]

How to add a drop-down list for selecting a template

To add a drop-down list that lets you select the layout template for a template, you can use the TemplateSelector widget provided by this bundle. It defines the widget role templateSelector.

To add the drop-down list to a layout template, the template must contain an HTML element with the attribute data-dojo-attach-point="templateSelector".

Attach a widget to an attach point

If the template declares a data-dojo-attach-point with the value widget1, a widget can be attached to it with the following widget definition:

"templates": {
    "TemplateModel": {
        "widgets" : [
        {
            // the widget "overviewMap"
            "widgetRole" : "overviewMap",
            // should be placed in the attach-point "widget1"
            "attachTo": "widget1"
        }]
    }
}

Display widget as a window

To display a widget as a window, use the window property. It is not required that a data-dojo-attach-point exists in the template. If one exists the window properties are merged.

"templates": {
    "TemplateModel": {
        "widgets" : [
        {
            // the widget "overviewMap"
            "widgetRole" : "overviewMap",

            // should be shown as window
            "window": {
                "title":"Overview",
                "marginBox":{"w":255,"h":180,"r":90,"b":54},
                "closable":false,
                "resizable":false,
                "windowClass":"myCustomStyleClass"
            }
        }]
    }
}

Change widgets behavior based on active sublayout

Templates can provide multiple sublayouts. A widget can change its display behavior depending on the active sublayout. The available sublayouts are defined by a specific template and not by the templates bundle. For a list of available sublayouts for the seasons template, see the template-seasons documentation.

"templates": {
    "TemplateModel": {
        "widgets" : [
        {
            // on sublayouts desktop and tablet
            "sublayout": [ "desktop", "tablet_landscape", "tablet_portrait" ],
            // the widget "overviewMap"
            "widgetRole" : "overviewMap",
            // should be placed in the attach-point "placeholder_1"
            "attachTo": "placeholder_1"
        },
        {
            // on sublayout mobile
            "sublayout": [ "mobile_landscape", "mobile_portrait" ],
            // the widget "overviewMap"
            "widgetRole" : "overviewMap",
            // should be placed in the attach-point "placeholder_2"
            "attachTo": "placeholder_2"
        }]
    }
}