Event handlers for view design-time preview

The following functions can be used to provide an enhanced design-time experience, allowing user interface developers to visualize how a view will appear at run time. These functions are set up to parallel the runtime view APIs as closely as possible to facilitate code reuse.
Function Description
getHTMLSnippet() Returns the HTML snippet as a String for the view design time rendering. If an HTML preview file has also been set on the view, then the content of this.htmlSnippet is automatically set and returned. This function can be overridden to modify the snippet or, if an HTML preview is not specified, supply a template via coding.
createPreview(containingDiv, labelText, callback) Creates the preview for the view at design time. If an HTML snippet has been supplied (by either a managed asset or the getHTMLSnippet() function), then containingDiv will have these contents:
  • containingDiv(Node). The wrapper div supplied and owned by the editor in which to create the preview contents.
  • labelText (String). The initial label text, if the view supports a label.
  • callback (function). The callback function which must be called after the preview has been created. The callback allows for asynchronous preview creation, such as the usage of require.
destroyPreview() Function called when the preview of the view instance is no longer being used. Use this function to clean up the resources that preview used when it was active.
propertyChanged(propertyName, propertyValue) Function called when the view instance is first initialized and when a property changes. These changes are similar to those returned by the modelChanged function except the values are mapped to runtime values where possible.

Some model facets are combined into one grouping. For example, one @style notification is returned containing all effective values for the current device selected, instead of separate notifications for @width, @height and so on.

If the data type is a URL, for example in the case of a stock image binding, and a managed asset is chosen, then propertyValue is resolved to a usable URL or null if not found.

If the configuration option is responsive, the effective value is passed in, which could be inherited from another screen size setting.

If the value is a localization key, the value passed is the resolved value for the current locale.

If the user selects a different screen size setting, the function is called with the property name @device.

  • propertyName(String). The name of the configuration option for the item being changed. Built-in configuration options and other special events have the @ prefix, as follows:
    • @binding. The data binding of the view instance.
    • @layoutItemId. The ID of the view instance. At run time, this is called viewID, and in the properties, it is called controlID.
    • @device. The screen size currently selected in the editor.
    • @style. The set of layout options combined into a single object.
  • propertyValue. The data associated with the property. If the property is a configuration option, the data is always a String. If complex static data is set as the configuration data, then the propertyValue is a JSON String. If the configuration option is a service, the UUID of the service will be the value. It is not recommended to use these advance preview event handlers to call the AJAX services set on a view instance. If the property name is @style or @device, then the data is an Object instead of a String.
modelChanged(propertyName, propertyValue)

Function called when the model changes. Notification is triggered by configuration data changes, or changes to the bound data (via the @binding property name) and layout item control ID(@layoutItemId).

  • propertyName(String)
  • propertyValue
In any of the JavaScript helper functions, this.context exists and can be called to do various things:
this.context Description
context.device

Provides the currently selected device in the editor. It is recommended that you use the propertyChanged() function instead.

context.getManagedAssetUrl(fileName, assetType, projectAcronym, returnWithoutAssetName, pathInZip)
Returns a URL that points to the managed asset that is specified by fileName.
  • fileName(String). File name of a managed asset. Example: 'button_palette.png'
  • assetType (String). Unused. This is included for consistency with the runtime API.
  • projectAcronym(String). Unused. This is included for consistency with the runtime API.
  • returnWithoutAssetName(null). Unused. This is included for consistency with the runtime API.
  • pathInZip (String). If defined, the URL is constructed to point to a path within the .zip file. (The managed asset is assumed to be a .zip file).