Extending the Rich UI widget set

A Rich UI widget is written in EGL and is of type RUIWidget (specifically, egl.ui.rui.RUIWidget). You often need to do only as follows:

• Specify an HTML tag name in property tagName. Alternatively, specify a declared Widget in property targetWidget, in which case the following statements apply:
  • The HTML tag that is the basis of the referenced widget's type is the basis of the Widget type that you are defining
  • You can use the name of the referenced widget to access the functions and properties defined for that widget's type

  If you specify both tagName and targetWidget, the latter applies.

• Specify some or all of the properties that are listed in a later section.
• Specify an on-construction function and set a CSS class name in that function.
• Build the functionality from other widgets.

Here is the outline of an H3 definition, which requires no import statements:

Handler H3 type RUIWidget{tagName = "h3", onConstructionFunction = start,
   @VEWidget{
				category = "New Widgets",
				template = "my.package.H3{ text=\"The Heading Text\" }",
				smallIcon = "icons/h3small.gif",
				largeIcon = "icons/h3large.gif" 	}}

   text String  { @EGLProperty { getMethod=getText, setMethod=setText }, 
                  @VEProperty{}};
   function start()
      class = "EglRuiH3";
   end

   function setText(textIn String in)
      text = textIn;
      this.innerText = textIn;
   end

   function getText() returns (String)
      return (text);
   end
end

Given this definition, you can create widgets that are based on the type H3. For example, the following declaration creates a box with a nested H3 widget:

ui Box { children = [ 
            new H3 { text = "Summary" }
       	]};  	

To create a new Rich UI widget based on JavaScript, do as follows:

1. Create a JavaScript file to contain the code for the widget. Invoke egl.defineWidget and specify the following arguments:
   • The name of the package in which the custom JavaScript resides. The package name is required, is case sensitive, and identifies the WebContent subfolder that contains the JavaScript.

     Include dots in place of a forward slash for every subfolder under the first. For example, if your JavaScript is in folder WebContent/myPkg/test, the packageName value is myPkg.test.

   • The name of the widget class (for example, Button); that class name is the name of the external type that you will create.
   • The package name of the EGL external type for the parent widget. You might be extending an external type of your own; but in most cases, the parent type is Widget, which is provided for you and is the basis of other EGL external-type widgets. If the parent type is Widget, the package name is egl.ui.rui.
   • The name of the EGL external type (for example, Widget) for the parent widget.
   • The tag name (for example, button) of the DOM element for the new widget.
   Here is the example:

   egl.defineWidget( 'egl.rui.widgets', 'Button',
                     'egl.rui.widgets', 'Widget',
                     'button', { } );

2. Within the curly brackets ( { } ), define the JavaScript functions to reflect the following outline, separating one function from the next with a comma:

   "functionName" : function(/*parameters*/)
   { //JavaScript Source }

   Here is an example:

   "getSelected" : function() {
      return this.check.checked;
   },
   "setSelected" : function(value) {
      this.check.checked = value;
   },
   "toString" : function() {
      return "[CheckBox, text=\""+this.egl$$DOMElement.innerHTML+"\"]";
   }

3. Each widget can specify the following functions for the JavaScript runtime to invoke:
   • The function constructor is invoked whenever a new widget instance is created, and that function can be used, for example, to initialize data
   • The function egl$$initializeDOMElement is invoked whenever the HTML element is being created for the widget, and that function can be used, for example, to set initial properties on the element
   • The function childrenChanged is invoked whenever the application developer updates the new widget's children property, if any.

   Each widget also has a field called this.egl$$DOMElement, which represents the HTML element (or top-level HTML element) created for the widget.

4. In an EGL source file, create an EGL external type that extends from egl.ui.rui.Widget or from an existing widget. The External Type needs a stereotype of JavaScriptObject, as described in “External type for JavaScript.”

   When you create the external type, specify some or all of the properties that are listed in the next section.