The js file contains specific JavaScript code that implements a widget as an element of the user interface. This page shows examples of how to extend existing widgets and implement changes by registering them as new widget classes.

Overview

The js files contain functions for rendering the widget template file (.tpl.html) and dynamically building the DOM element. To customize a widget, you need to extend the standard widget class in a new widget js file contained in your customization project directory.

The js is associated with a template file. If the js and the template file are in the same directory and have the same name (for example, MyEditWidget.js and MyEditWidget.tpl.html), they are associated automatically.

NOTE: If the template file does not have the same name as the js, you can associate them by setting the __templateName value in the js file.

Extending a basic widget

This sample code shows the minimal code you need to extend a basic widget in js.

"use strict";

modulum('newWidget', ['baseWidget', 'WidgetFactory'],
  function(context, cls) {

    cls.newWidget = context.oo.Class(cls.baseWidget, function($super) {
      return {
        __name: "newWidget",
        __templateName: "newTemplate",

        /* your custom code */
      };
    });
    cls.WidgetFactory.register('widgetType', cls.newWidget);
  });

where:

• newWidget is your custom widget
• baseWidget is the built-in widget that it extends
• newTemplate is the template file to associate with the widget. This is optional; if the .tpl.html file has the same name as the js file, you do not need to specify the template name.
• widgetType is the widget representation (node name) in the AUI tree.

Extending a basic widget and registering a new widget style

Register a new widget style to allow for selective application of your customization as specified by the style settings in your form source.

"use strict";

modulum('newWidget', ['baseWidget', 'WidgetFactory'],
  function(context, cls) {

    cls.newWidget = context.oo.Class(cls.baseWidget, function($super) {
      return {
        __name: "newWidget",

        /* your custom code */
      };
    });
    cls.WidgetFactory.register('widgetType', ‘widgetStyle’, cls.newWidget);
  });

where:

• newWidget is your custom widget
• baseWidget is the built-in widget that it extends
• widgetType is the widget representation (node name) in the AUI tree.
• widgetStyle is the style name.

The widgetStyle argument (optional) allows you to reference your widget in your Genero form source. For example, in this form (.per) file snippet, the style "widgetStyle" is applied to the defined Edit form field:

EDIT f01 = formonly.edit, STYLE=”widgetStyle”;

Only fields with the style applied will be customized.

Widget best practices

You can create a widget using a widget factory, for example:

var button = cls.WidgetFactory.createWidget("Button", opts);

• opts is a object which contains some parameters for the widget constructor. The opts.appHash option is recommended. This option contains the current application id and is used by the GBC core to detect memory leaks.

You can also get all the build parameters of a widget by using WidgetBase.getBuildParameters().

The simplest way to build a widget from another widget is to use this syntax:

var button = cls.WidgetFactory.createWidget("Button", this.getBuildParameters());

Example 1: Extending a simple widget

For simple widget customization, you can extend the Edit widget as an example, in a file gbc-project-dir/customization/customization-project-dir/js/MyEditWidget.js, like:

"use strict";

modulum('MyEditWidget', ['EditWidget', 'WidgetFactory'],
 
  function(context, cls) {

    /**
     * Edit widget.
     * @class classes.MyEditWidget
     * @extends classes.EditWidget
     */
    cls.MyEditWidget = context.oo.Class(cls.EditWidget, function($super) {
      /** @lends classes.MyEditWidget.prototype */
      return {
        __name: "MyEditWidget",
        
        setTitle: function(title) {
          $(this.getElement()).find(".title").text(title);
        },

        getTitle: function() {
          return $(this.getElement()).find(".title").text();
        }
      };
    });
    cls.WidgetFactory.registerBuilder('Edit', cls.MyEditWidget);
  });

And a template file gbc-project-dir/customization/customization-project-dir/js/MyEditWidget.tpl.html, like:

<div class="mt-field gbc_dataContentPlaceholder">
  <input type="text" class="gbc-label-text-container" autocomplete="new-password"/>
</div>

This customization extends the built-in EditWidget. You can reference an element in the HTML template for the widget by using the this.getElement() function.

Example 2: Extending a container widget

For container widget customization, you can set for example a file gbc-project-dir/customization/customization-project-dir/js/MyComposedWidget.js.

"use strict";

modulum('MyComposedWidget', ['WidgetGroupBase', 'WidgetFactory'],
  function(context, cls) {
    cls.MyComposedWidget = context.oo.Class(cls.WidgetGroupBase, function($super) {
      /** @lends classes.MyComposedWidget.prototype */
      return {
        __name: "MyComposedWidget",

        _label: null,
        _edit: null,

        constructor: function() {
          $super.constructor.call(this);
          this._label = cls.WidgetFactory.createWidget('Label');
          this._edit = cls.WidgetFactory.createWidget('Edit');
          this.addChildWidget(this._label);
          this.addChildWidget(this._edit);
        },

        [...]
        destroy: function() {
          this.removeChildWidget(this._label);
          this.removeChildWidget(this._edit);
          this._label.destroy();
          this._label = null;
          this._edit.destroy();
          this._edit = null;
          $super.destroy();
        },
        [...]
      };
    });
    cls.WidgetFactory.registerBuilder('MyComposed', cls.MyComposedWidget);
  });

For a Container widget, the root base widget is always WidgetGroupBase. You add the child elements with this.addChildWidget and remove child elements with this.removeChildWidget.