JavaScript module and lifecycle methods for custom widgets

This topic provides recommendations for writing JavaScript code for a custom widget.

You should write your JavaScript code in a modular format as shown below. This example is the skeleton sample from the Samples tab.

(function(){
  return {
    init: function(props) {
    },

    destroy: function() {
    },

    onUpdate: function(props) {
    },

    onSearch: function(props) {
    },

    onitemClick: function(props) {
    },

    onSelect: function(props) {
    },

    onDeselect: function(props) {
    },

    onResize: function(props) {
    },

    onMaximized: function(props) {
    },

    onClick: function(props) {
    },

    onRenderHtml: function(props) {
    },

    onRendered: function(props) {
    },

    myClickHandler: function(ev, props) {
    }
  }
})();

The module consists of several callback methods that are invoked at certain stages in the widget life cycle. Each method receives the props parameter which contains several APIs and relevant information, as an argument.

init(props)

Called every time the widget is mounted. For example, when the user navigates to a tab page that contains this widget. That means the widget is re-initialized every time the widget is shown by opening its container tab pane.

destroy(props)

Called every time the widget is unmounted. For example, when the user moves to another tab pane.

onUpdate(props)

Called every time something in the current page is changed. Be careful when using this method because it is called very frequently.

onSearch(props)

Called when the search result is updated while the widget is listening to data source state changes.

Important: In order to listen to data source state changes the Listen to search results check box must be checked.

onItemClick(props)

Called when a search result item is clicked while the widget is listening to data source state changes. Unlike onSelect, this method is called even when an already-selected item is clicked.

Important: In order to listen to data source state changes the Listen to search results check box must be checked.

onSelect(props)

Called when a search result item is selected while the widget is listening to data source state changes.

Important: In order to listen to data source state changes the Listen to search results check box must be checked.

onDeselect(props)

Called when a search result item is deselected as a result of a new search. In this case, props.selectedItem becomes undefined.

Important: In order to listen to data source state changes the Listen to search results check box must be checked.

onResize(props)

Called when the browser window is resized or the widget frame is maximized.

onMaximized(props)

Called when the widget frame is maximized.

onClick(props)

Called when the widget is clicked. If this method returns false, item selection action will be skipped.

onRenderHtml(props)

Called before the template engine starts rendering. The return value will be passed to the template engine, and can be accessed from the widget's template HTML.

onRendered(props)

Called after widget rendering is finished.

myClickHandler(ev, props)

A custom event handler. In an HTML template, event handlers can be specified as, for example, <button onclick="myClickHandler()">. However, that it is only a marker to let the custom widget know what the node wants to listen to what DOM event. All the actual DOM events are handled by the root node of the widget and dispatched to each custom handler.