UI Composition

Views and Regions

A view is a user interface component. It can be anything from a sophisticated AJAX form to a small piece of static HTML content. Views are typically hosted inside of named regions, but may live outside of a region. Views typically use data-binding expressions in their markup to represent data and state of associated view models. This helps facilitate the separation of concerns.

A region is an area of a visual element that has a name associated with it. Regions are used to define the style and behavior of a particular area of a UI interface. An example would be an area in which a map is typically displayed, or a collapsible area where search results or forms are displayed.

The way a particular region behaves is dictated by its region adapter. A region adapter is a piece of code that displays one or more views in a specific fashion for a given region. An example of a region adapter is an adapter that shows multiple views in an HTML div region and allows a user to switch between them using tabs.

Regions are declared in view markup using the data-region-name attribute on any HTML element that can hold children, for example:

<div class="application-Region" data-region-name="ApplicationRegion"></div>

By default, regions use an adapter that simply shows one view at a time in the given region.

Views typically hold references to the region that they are hosted in. When a view is activated, it is generally added to the desired region and made visible, although the exact behavior depends on the type of region adapter used.

If a view references a region that does not exist, the view is not displayed until that region is created. This is a useful mechanism that allows flexible UI configuration. Views in configuration can be declared before regions that host them are declared, and they are then only created when those regions are available.

Views themselves can contain regions and views can move between regions.

Views can be associated with regions via configuration, or created and placed on the fly programmatically using viewManager object of an application. When creating views (and view models) on the fly, be sure to pass along the application instance, for example, this.app; and the library ID, for example, this.LibraryId of the component doing the creating.

When a region is destroyed, any views inside it are also destroyed.

Views are intended to be flexible and used in the place of manual DOM creation. Views can be created without being associated with regions or view models.

Instead of using string concatenation or DOM manipulation to create UI elements, views and data binding should be used. Using the view-oriented method of UI creation has serious benefits over programmatically creating DOM elements. Views should be the source of nearly all UI markup.

Liquid Layouts

We strongly suggest that developers use liquid layouts when creating views. Liquid layouts are layouts that expand to take up as much space as they are given, and generally have no explicit width or height constraints.

When creating user interfaces for cross-platform applications, avoid checking user-agent strings and creating phone-specific , tablet-specific, or desktop-specific code conditions. Instead, organize your views and regions in ways that allow them to be configured to meet layout requirements.

For example, if you have a view that displays complex results, consider breaking it into two views: a table view for desktops and tablets, and a list view for phones. A developer or administrator can than choose which one to use via configuration, instead of depending on code to detect the appropriate setup.

By creating liquid views, developers can create flexible and reusable user interfaces that work across multiple device form factors.

An example of this is a simple menu view. On a large-format device such as a desktop PC, we may wish to have a menu pop up over the map and take up a small area of the screen to display some options. However, on a smaller device like a phone, we may wish to have the menu take up the whole width and height of the screen in order to be touch friendly. The width and height of the region holding this menu view may differ between devices, but the view itself should simply take up whatever space is available to it.

When creating user interfaces for use on a multitude of device sizes, ensure that it is the layout and styling of the regions that change, rather than the views. Platform-specific concerns should live in configuration files and CSS style sheets, not in code.

Shells

A shell can be thought of as the basic layout of an application. It is the skeleton of a user interface. A shell is typically just a view in which various application regions are defined along with which region adapters are used. A shell view may also have custom code to handle certain behaviors, such as transitions and animations between certain states or layouts.

The HTML5 Viewer ships with three shells:

Desktop shell geared towards devices with large screens.
Tablet shell for large and medium touch-screen devices.
Handheld shell geared towards smaller touch-screen devices such as smartphones.

The shell for both Desktop and Tablet contain the same regions. The shell for Handheld devices contains only essential regions.