UIZE JavaScript Framework

MODULES Uize.Widget

1. Introduction

The Uize.Widget class serves as the base class for widgets in the UIZE JavaScript Framework, providing services to ease the implementation of widgets.

DEVELOPERS: Chris van Rensburg, Ben Ilegbodu, Vinson Chuong

1.1. An Abstract Class

The Uize.Widget class is primarily an abstract class, intended for the creation of widget subclasses.

That said, however, it is possible and sometimes useful to create instances of this class that will act as wrappers for sets of child widgets in order to achieve functional grouping for the child widgets within a widget class. Child widgets grouped together in this way can then be enabled or disabled as a group, separately from the other child widgets.

1.2. Examples

The following example pages are good showcases for the Uize.Widget module...

Shared UI - See how some widget HTML for a slider widget can be shared by multiple slider widget instances. The UIZE JavaScript Framework makes this possible.
The setNodeValue Method - See a demo of the setNodeValue method, which can set a value on select boxes, checkboxes, radio buttons, text inputs, textareas, divs, spans...
enabled/busy in Widget Tree - See a demonstration of the busy and enabled mechanisms of the widget base class, and how busy and enabled state can be inherited within a widget tree.
setNodeValue on Multi-select - See a demo of the setNodeValue and getNodeValue instance methods being used to set and get the value for a multiple select style listbox form element.

SEARCH FOR EXAMPLES

Use the link below to search for example pages on the UIZE Web site that reference the Uize.Widget module...

SEARCH

1.3. Implementation Info

The Uize.Widget module defines the Uize.Widget class, which is a subclass of Uize.Class.

INHERITANCE CHAIN

Uize.Class −> Uize.Widget

1.3.1. Features Introduced in This Module

1.3.2. Features Overridden in This Module

The features listed in this section have been overridden in this module.

The module that an overridden feature was initially introduced in will be noted in the IMPLEMENTATION INFO notes for the feature.

INSTANCE METHODS

kill | valueOf

STATIC PROPERTIES

Uize.Widget.moduleName | Uize.Widget.nonInheritableStatics

1.3.3. Features Inherited From Other Modules

1.3.4. Modules Directly Under This Namespace

Uize.Widget.AutoSuggest | Uize.Widget.AutoTooltip | Uize.Widget.Bar | Uize.Widget.Button | Uize.Widget.Calculator | Uize.Widget.CalculatorAbstract | Uize.Widget.Calendar | Uize.Widget.Captcha | Uize.Widget.Collapsy | Uize.Widget.Collection | Uize.Widget.CollectionItem | Uize.Widget.ColorGrid | Uize.Widget.Committer | Uize.Widget.Count | Uize.Widget.Dialog | Uize.Widget.DirectionalPad | Uize.Widget.Drag | Uize.Widget.EdgeHugger | Uize.Widget.EggTimer | Uize.Widget.FilterGroups | Uize.Widget.Fleeting | Uize.Widget.Flip | Uize.Widget.Form | Uize.Widget.FormDialog | Uize.Widget.FormElement | Uize.Widget.FormElementWarning | Uize.Widget.FormElements | Uize.Widget.FormWarnings | Uize.Widget.HoverFader | Uize.Widget.HtmltCompiler | Uize.Widget.ImagePort | Uize.Widget.ImageWipe | Uize.Widget.InlinePicker | Uize.Widget.ListEditor | Uize.Widget.Log | Uize.Widget.MagView | Uize.Widget.Mask | Uize.Widget.Options | Uize.Widget.Page | Uize.Widget.Pagination | Uize.Widget.Picker | Uize.Widget.Population | Uize.Widget.PopupPalette | Uize.Widget.Resizer | Uize.Widget.Scrolly | Uize.Widget.SegmentDisplay | Uize.Widget.SlideShow | Uize.Widget.Stretchy | Uize.Widget.Swap | Uize.Widget.TableSort | Uize.Widget.TextInput | Uize.Widget.TextInputBasic | Uize.Widget.ThumbZoom | Uize.Widget.Tree | Uize.Widget.V2 | Uize.Widget.mBindings | Uize.Widget.mChildBindings | Uize.Widget.mChildrenLinked | Uize.Widget.mCssBindings | Uize.Widget.mDeclarativeChildren | Uize.Widget.mEventBindings | Uize.Widget.mHtmlBindings | Uize.Widget.mLoc | Uize.Widget.mModels | Uize.Widget.mV2 | Uize.Widget.mWeb | Uize.Widget.mWebBindings | Uize.Widget.mWidthHeight

1.3.5. Unit Tests

The Uize.Widget module is unit tested by the Uize.Test.Uize.Widget test module.

2. DOM Nodes

2.1. Root Node

The optional root node of a widget is the DOM node with the name '' (empty string).

The id for the root node of a widget instance is the value of that instance's idPrefix state property - there is no "-" (hyphen) separating the idPrefix and the empty DOM node name. So, for an instance of the slider class with its idPrefix set to the value 'mySlider', the id of that instance's root node would be just mySlider.

A reference to the root node can be obtained by either specifying the value '' (empty string) or no nodeSTRorBLOB parameter when calling the getNode instance method, as in...

var theRootNode = myWidget.getNode ();
var alsoTheRootNode = myWidget.getNode ('');

Similarly, when using the node related instance methods, one can specify the value '' (empty string), as in...

myWidget.displayNode ('',false); // hide myWidget, if it has a root node in its HTML

2.2. shell

The optional shell DOM node for a widget instance provides a "slot" in the document into which markup for that instance can be inserted.

3. Instance Properties

3.1. addedChildren

A Uize.Class instance whose state properties reflect whether or not child widgets by the same name has been added.

You can use the condition system methods like isMet, once, and whenver on addedChildren to determine if and when a child widget has been added to the widget.

NOTES

the addedChildren object is read-only - its state should not be directly modified
see also the related children instance property

3.2. children

An object, each of whose properties is a reference to one of a widget's child widgets.

For example, an instance of the Uize.Widget.SlideShow class assigned to the variable mySlideShow may have child widgets that can be referenced as follows...

mySlideShow.children.first
mySlideShow.children.last
mySlideShow.children.previous
mySlideShow.children.next

3.2.1. Don't Directly Modify the children Object

The contents of the children object is managed by the various instance methods of the Uize.Widget class, such as the addChild and removeChild methods.

One should not directly modify the contents of the children object, but should only do this through the child widget management methods.

3.2.2. The Special children state Property

The children instance property has a companion state property of the same name, but which has a special behavior.

The children state property provides a convenient way to distribute widget properties to any or all of a widget's child widgets.

NOTES

the children object is read-only - its contents should not be directly modified
see also the special children state property
see also the related addedChildren instance property and the parent state property

3.3. isWired

An alternate way of accessing the value of the wired state property, that doesn't require using the get instance method.

Using this property is functionally equivalent to myWidget.get ('wired'). This property is provided primarily as a convenience and to improve performance, since the wired state property is accessed many times in many widget class files, and often in heavily hit areas of code. Using this property to access the value of the wired state property offers slightly better performance than using the get instance method, which may help a little with performance optimization.

INSTEAD OF...

if (!this.get ('wired')) {
  // code to perform wiring
}

USE...

if (!this.isWired) {
  // code to perform wiring
}

NOTES

see also the wired state property

3.4. showConfirm

IMPLEMENTATION INFO

this feature was introduced in this module

3.5. showInform

IMPLEMENTATION INFO

this feature was introduced in this module

4. Instance Methods

4.1. addChild

The addChild method lets you add a child widget to a widget.

SYNTAX

childWidgetOBJ = myWidget.addChild (
  childWidgetNameSTR,childWidgetClassOBJ,childWidgetPropertiesOBJ
);

VARIATION

childWidgetOBJ = myWidget.addChild (childWidgetNameSTR,childWidgetClassOBJ);

The childWidgetPropertiesOBJ parameter is optional and can be omitted when the default property values for a widget class are sufficient, or when the properties will be set to the desired values at a later stage.

NOTES

returns a reference to the child widget instance that was added
a state property matching the child widget name is marked as met in the addedChildren instance property
the value of the childWidgetNameSTR can be null or undefined if a value is specified for the name property in the childWidgetPropertiesOBJ parameter
see also the removeChild instance method, and the children instance property

IMPLEMENTATION INFO

this feature was introduced in this module

4.2. addChildren

Lets you conveniently add multiple child widgets in a single method call, by specifying the children in an object that maps child names to child properties.

DIFFERENT USAGES

Add Multiple Child Widgets

myInstance.addChildren (childrenOBJ);

Add Multiple Child Widgets, Specifying Properties That Are Common to All

myInstance.addChildren (childrenOBJ,commonPropertiesOBJ);

4.2.1. Add Multiple Child Widgets

Multiple child widgets can be added in a single call, by specifying a single childrenOBJ parameter.

SYNTAX

myInstance.addChildren (childrenOBJ);

The value of the childrenOBJ parameter should be an object, where the name of a property should be the name of a child widget, and where the value of a property should be an object specifying values for a child widget's state properties. The widget class for a child widget should be specified using the special widgetClass widget property.

EXAMPLE

this.addChildren ({
  ok:{
    text:'OK',
    widgetClass:Uize.Widgets.Button,
    size:'small'
  },
  cancel:{
    text:'CANCEL',
    widgetClass:Uize.Widgets.Button,
    size:'small'
  },
  reset:{
    text:'RESET',
    widgetClass:Uize.Widgets.Button,
    size:'small'
  }
});

In the above example, the addChildren method is being used to add three button child widgets.

4.2.2. Add Multiple Child Widgets, Specifying Properties That Are Common to All

Multiple child widgets can be added in a single call, without repeating widget property values that are common to all children being added, by specifying the common property values in the optional commonPropertiesOBJ parameter.

SYNTAX

myInstance.addChildren (childrenOBJ,commonPropertiesOBJ);

EXAMPLE

this.addChildren (
  {
    ok:{text:'OK'},
    cancel:{text:'CANCEL'},
    reset:{text:'RESET'}
  },
  {
    widgetClass:Uize.Widgets.Button,
    size:'small'
  }
);

In the above example, the addChildren method is being used to add three button child widgets of the same Uize.Widgets.Button widget class and with the same 'small' value for their size state property. Because the widget class and size are the same for all the buttons being added, these values can be specified using the optional commonPropertiesOBJ parameter so that the values don't need to be repeated in the child properties object for each of the child widgets.

4.2.3. More Concise

Using the addChildren method can produce more concise code in situations where you are adding multiple child widgets that share some common properties.

Consider the following example of adding multiple button child widgets...

INSTEAD OF...

this.addChild (
  'ok',
  Uize.Widgets.Button,
  {
    text:'OK',
    size:'small'
  }
);

this.addChild (
  'cancel',
  Uize.Widgets.Button,
  {
    text:'CANCEL',
    size:'small'
  }
);

this.addChild (
  'reset',
  Uize.Widgets.Button,
  {
    text:'RESET',
    size:'small'
  }
);

USE...

this.addChildren (
  {
    ok:{text:'OK'},
    cancel:{text:'CANCEL'},
    reset:{text:'RESET'}
  },
  {
    widgetClass:Uize.Widgets.Button,
    size:'small'
  }
);

In the above example, we are adding multiple button child widgets of the same widget class and of the same size (as specified in the size state property). Rather than calling the addChild method multiple times, each time passing the same common property values, we can use the addChildren method and tale advantage of its optional commonPropertiesOBJ parameter to avoid having to repeat the property values that are common to all the button child widgets.

NOTES

compare to the companion addChild instance method

IMPLEMENTATION INFO

this feature was introduced in this module

4.3. ajax

Performs an asynchronous service (Ajax) request with the specified service parameters and (optional) request parameters.

SYNTAX

myWidget.ajax (serviceParamsOBJ,requestParamsOBJ);

The serviceParamsOBJ contains parameters needed by the service (typically what is passed on the query string or as post data in the request). The requestParamsOBJ contains parameters used in configuring the request itself, such as callbacks, caching level, request method, etc.

EXAMPLE

myWidget.ajax (
  {
    action:'getresults',
    query:'dog shirts',
    sort:'price_asc',
    pg:2,
    num:25
  },
  {
    cache:'browser',
    requestMethod:'GET',
    callback:function (responseObj) {
      // Do something with search results data
    }
  }
);

Depending on how ajax has been implemented for widgets in your site-specific page widget (see performAjax Implementation), the resulting Ajax service request could look like:

http://www.somedomain.com/services?action=getresults&query=dog%20shirts&sort=price_asc&pg=2&num=25

4.3.1. performAjax Implementation

Strictly speaking, the parameters supported by the serviceParamsOBJ and requestParamsOBJ parameters are determined by the specific implementation of ajax.

Technically, what happens when the ajax instance method is called is that the widget finds the nearest parent up the parent chain that provides an implementation for the performAjax instance method.

Typically, performAjax is implemented at the page widget level, but it can also be overriden by parent widgets closer to the widget on which the ajax instance method is called. If no performAjax implementation is provided, anywhere up the parent chain, then no Ajax request would be made and the code will fail silently. There is no default implementation for ajax aside from supporting the variations outlined below.

SAMPLE IMPLEMENTATION

_class.instanceMethods ({
  performAjax:function (_serviceParams,_requestParams) {
    this._commObject.request ({
      url:['http://www.somedomain.com/services',_requestParams],
      returnType:'json',
      requestMethod:_requestParams.requestMethod || 'POST',
      cache:_requestParams.cache,
      callback:_requestParams.callback
    })
  }
});

The above sample implementation assumes that there is a private reference to a comm object, which could be an instance of either the Uize.Comm.Ajax or the Uize.Comm.Iframe class, and that was most likely created in the constructor of this widget.

The base implementation of ajax does not contain code to make an Ajax request; it is up to your site-specific implementation to handle this (see performAjax Implementation). However, the base implementation does support abstract variations to ajax so that the site-specific implementation only has to deal with the single method syntax outlined above.

VARIATION 1

myWidget.ajax (serviceParamsOBJ,callbackFUNC);

This variation supports just passing a callback function (with no additional request parameters) as the second parameter to ajax.

EXAMPLE

myWidget.ajax (
  {
    action:'getresults',
    query:'dog shirts',
    sort:'price_asc',
    pg:2,
    num:25
  },
  function (responseObj) {
    // Do something with search results data
  }
);

This would be equivalent to...

myWidget.ajax (
  {
    action:'getresults',
    query:'dog shirts',
    sort:'price_asc',
    pg:2,
    num:25
  },
  {
    callback:function (responseObj) {
      // Do something with search results data
    }
  }
);

VARIATION 2

myWidget.ajax (serviceParamsOBJ);

In this variation, the requestParamsOBJ parameter is completely ommitted. This variation is useful when you do not need to alter how the Ajax request is made and calling a callback is unnecessary. Making an Ajax request without a callback is typically rare, but there are some use cases where it is appropriate, such as when logging information.

IMPLEMENTATION INFO

this feature was introduced in this module

4.4. buildHtml

Rebuilds the HTML for a widget instance, replacing its existing HTML in the DOM.

SYNTAX

myWidget.buildHtml ();

HTML for a widget instance is generated by using the instance's html state property. If the value of the html property is a function, or is an object with a process property whose value is a function, then the HTML generator function will be supplied with the current state of the instance's state properties as input - in the form of a single input object.

The generator function can either return a string containing HTML markup, a DOM node, or an array of DOM nodes.

The generated HTML for the widget is inserted into a node in the document, according to a series of fallbacks. Priority is given to the container state property. If container is set to null or undefined, then the shell DOM node is considered. If the shell DOM node is not present, then the root node is considered. If no root node is present, then the HTML is inserted at the bottom of the document's body.

This method always builds the HTML for a widget instance and does not consider the value of the instance's built state property. Moreover, after this method has been called, the built state property will be set to true.

VARIATION

myWidget.buildHtml (alternateTemplateInputOBJ);

When the optional alternateTemplateInputOBJ parameter is specified, then the object specified by this parameter will be used as the input for the HTML generator, rather than the current state of the instance's state properties.

NOTES

see also the shell and root node DOM nodes
compare to the insertUi and insertOrWireUi instance methods

IMPLEMENTATION INFO

this feature was introduced in this module

4.5. callInherited

Returns a function, being a caller for the specified instance method, as inherited from the widget's parent chain.

SYNTAX

callerFUNC = myInstance.callInherited (methodNameSTR);

Once you have a caller function for calling an instance method inherited from up the parent chain, then you can call it and pass parameters as if you were calling that method on the instance that provides the method.

EXAMPLE

myWidget.callInherited ('useDialog') ({
  widgetClassName:'MyNamespace.SomeDialogWidget',
  widgetProperties:{
    name:'myDialog',
    title:'This is My Diaog, Hear it Roar'
  },
  submitHandler:function (_confirmed) {
    // handle dialog being submitted (i.e. OK or CANCEL)
  }
});

In the above example, myWidget is a widget instance that is on a widget tree with a page widget instance (an instance of Uize.Widget.Page, or a subclass of it) at the root. The Uize.Widget.Page class implements a useDialog instance method. Now, even though the widget class of the myWidget instance doesn't implement a useDialog instance method, and even though it isn't a subclass of Uize.Widget.Page and, therefore, doesn't inherit the implementation from the page widget class, the callInherited instance method is able to "locate" the provider of this method up the parent widget chain and returns a function that will call the method as an instance method on its provider.

NOTES

see also the getProvider, getInherited, and setInherited instance methods

IMPLEMENTATION INFO

this feature was introduced in this module

4.6. childHtml

Returns the HTML for a child widget that can then be inserted into the HTML for the widget.

SYNTAX

childHtml = myInstance.childHtml (childPropertiesOBJ);

The childHtml method is intended primarily for use within the HTML generator (usually a JST template or an htmlt template) for a widget.

IMPLEMENTATION INFO

this feature was introduced in this module

4.7. childId

Returns the ID prefix of a child widget with the specified childNameSTR.

SYNTAX

childIdPrefixSTR = myWidget.childId (childNameSTR);

EXAMPLE

var childIdPrefix = mySlider.childId ('child');

Assuming an idPrefix of "page_slider", the example would return "page_slider_child".

NOTES

See related addChild instance method in Uize.Widget

IMPLEMENTATION INFO

this feature was introduced in this module

4.8. confirm

Lets you obtain user confirmation through a decorated HTML dialog.

SYNTAX

myWidget.confirm (paramOBJ);

PARAMS

{
  title:titleSTR,           // text to display in dialog's title bar (optional)
  message:messageSTR,       // message to display in dialog's content area
  yesHandler:yesFUNC,       // handler for user clicking "ok"
  noHandler:noFUNC,         // handler for user clicking "cancel" or close button
  callback:callbackFUNC,    // handler for user dismissing dialog (ok *or* cancel)

  // IMPLEMENTATION DEPENDENT...

  state:stateSTR,           // info, warning, error, confirm, success (optional)
  okText:okTextSTR,         // text for the ok button of the dialog (optional)
  cancelText:cancelTextSTR  // text for the cancel button of the dialog (optional)
}

4.8.1. How It Works

Strictly speaking, the parameters supported by the paramsOBJ parameter are determined by the specific implementation of confirm. Technically, what happens when the confirm instance method is called is that the widget finds the nearest parent up the parent chain that provides an implementation for the showConfirm instance method.

Typically, showConfirm is implemented at the page widget level, but it can also be overrided by parent widgets closer to the widget on which the confirm instance method is called. If no showConfirm implementation is provided, anywhere up the parent chain, then the browser's default confirm global function is used.

Because a decorated HTML implementation is asynchronous in its behavior, the call to the confirm instance method cannot expect the confirmation value to be returned to it as a result, so the confirmation logic must be coded asynchronously by providing callback handlers - even in the case where this class resorts to using the built-in confirm global function.

You can provide callback handlers for either or both of the yes and no states, using the yesHandler and noHandler parameters, respectively, or you can provide a generic handler through the callback parameter, where your callback will be called with a single parameter that represents the confirmation value.

EXAMPLE

myWidget.confirm ({
  title:'Confirm Delete',
  message:'Are you sure you would like to delete the selected items?',
  okText:'YES, DELETE',
  cancelText:'NO, DON\'T DELETE',
  yesHandler:function () {myWidget.deleteSelected ()}
});

NOTES

see also the companion inform instance method

IMPLEMENTATION INFO

this feature was introduced in this module

4.9. displayNode

Lets you display or hide the specified DOM node, using the display CSS style property.

SYNTAX

myWidget.displayNode (nodeSTRorBLOB,mustDisplayANYTYPE);

While typically a Boolean, the mustDisplayANYTYPE parameter can be of any type and the node will be displayed if it resolves to true, and hidden if it resolves to false - with the exception of undefined, when the node will be displayed (see explanation below).

VARIATIONS

myWidget.displayNode (nodeSTRorBLOB);

When no mustDisplayANYTYPE parameter is specified (or when its value is undefined), the node will be displayed.

NOTES

compare to the showNode instance method
compare to the Uize.Dom.Basics.display static method

IMPLEMENTATION INFO

this feature was introduced in this module

4.10. fire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.11. flushNodeCache

Flushes the cached reference to the specified DOM node, or all cached node references, from the widget instance's node cache.

SYNTAX

myWidget.flushNodeCache (nodeSTR);

VARIATION

myWidget.flushNodeCache ();

When no nodeSTR parameter is specified, the entire node cache for the widget instance will be flushed. This will not affect the functioning of a widget that has already been wired up, but may incur a very small performance cost the next time that operations on DOM nodes are performed.

IMPLEMENTATION INFO

this feature was introduced in this module

4.12. get

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.13. getContainer

IMPLEMENTATION INFO

this feature was introduced in this module

4.14. getHtml

IMPLEMENTATION INFO

this feature was introduced in this module

4.15. getInherited

Returns the value for the specified state property, as inherited from the widget's parent chain.

SYNTAX

inheritedANYTYPE = myWidget.getInherited (setGetPropertySTR);

If a value other than 'inherit' or undefined is set for the specified state property of the instance, then the property's value will be returned. Otherwise, this method will walk up the parent widget chain until a widget is found that has a value other than 'inherit' or undefined set for this state property. If none is found, then the value undefined will be returned.

NOTES

see also the callInherited, getProvider, and setInherited instance methods

IMPLEMENTATION INFO

this feature was introduced in this module

4.16. getNode

Returns a reference to the specified DOM node of the widget, or an array of references to the specified blob of DOM nodes.

SYNTAX

nodeOBJ = myWidget.getNode (nodeSTRorBLOB);

EXAMPLE

var sliderKnob = mySlider.getNode ('knob');

Returns the "knob" DOM node of the slider widget.

EXAMPLE

var sliderRootNode = mySlider.getNode ();

Returns the root node of the slider widget.

NOTES

The nodeSTRorBLOB parameter can be a string specifying the name of the DOM node, or an object reference to the DOM node. When a reference is specified, it is simply returned.
When the nodeSTRorBLOB parameter has a value of null, then the value null is returned.
When the nodeSTRorBLOB parameter has a value of undefined or is not specified, then the root node of the widget is returned. This has the same effect as specifying the empty string. (i.e. getNode () is equivalent to getNode (''))

IMPLEMENTATION INFO

this feature was introduced in this module

4.17. getNodeStyle

Returns the value of the specified style property (or style properties) for the specified DOM node.

SYNTAX

propertyValueSTR = myWidget.getNodeStyle (nodeSTRorOBJ,propertyNameSTR);

VARIATION

stylePropertiesOBJ = myWidget.getNodeStyle (nodeSTRorOBJ,stylePropertiesOBJ);

In order to get the values for multiple style properties in a single call, a style properties object can be specified using the stylePropertiesOBJ parameter. The value for this parameter should be an object, where each key is the name of a style property. The values for the individual properties in this object are not important - you can use any dummy values you like.

EXAMPLE

myWidget2.setNodeStyle (
  'title',
  myWidget1.getNodeStyle ('title',{borderWidth:0,borderColor:0})
);

When provided with a stylePropertiesOBJ parameter, the getNodeStyle method returns a value that is a style properties object, and this object can then be supplied to the setNodeStyle instance method. In the above example, values of the borderWidth and borderColor CSS style properties are being "copied" from the "title" DOM node of myWidget1 to the "title" DOM node of myWidget2.

NOTES

see also the companion setNodeStyle instance method
compare to the Uize.Dom.Basics.getStyle and Uize.Dom.Basics.setStyle static methods

IMPLEMENTATION INFO

this feature was introduced in this module

4.18. getNodeValue

Returns a string or boolean value, representing the value of the specified DOM node of the widget instance.

SYNTAX

nodeValueSTRorBOOL = myWidget.getNodeValue (nodeSTRorOBJ);

This method uses the Uize.Dom.Basics.getValue static method in its implementation. For more details, consult the reference for the Uize.Dom.Basics module.

NOTES

see the corresponding setNodeValue instance method
compare to the Uize.Dom.Basics.getValue static method

IMPLEMENTATION INFO

this feature was introduced in this module

4.19. getProvider

Returns a reference to the nearest widget instance up the parent widget chain that provides a value for the specified state property.

SYNTAX

providerWidgetOBJ = myWidget.getProvider (setGetPropertySTR);

If a value other than 'inherit' or undefined is set for the specified state property of the instance, then a reference to the instance will be returned. Otherwise, this method will walk up the parent widget chain until a widget is found that has a value other than 'inherit' or undefined set for this state property. If none is found, then the value undefined will be returned.

NOTES

see also the callInherited, getInherited, and setInherited instance methods

IMPLEMENTATION INFO

this feature was introduced in this module

4.20. globalizeNode

SYNTAX

myWidget.globalizeNode (nodeSTRorBLOB);

IMPLEMENTATION INFO

this feature was introduced in this module

4.21. inform

Lets you provide information to the user in a decorated HTML dialog.

SYNTAX

myWidget.inform (paramOBJ);

PARAMS

{
  title:titleSTR,           // text to display in dialog's title bar (optional)
  message:messageSTR,       // message to display in dialog's content area
  callback:callbackFUNC,    // handler for user dismissing dialog (ok *or* cancel)

  // IMPLEMENTATION DEPENDENT...

  state:stateSTR,           // info, warning, error, confirm, success (optional)
  okText:okTextSTR          // text for the ok button of the dialog (optional)
}

4.21.1. How It Works

Strictly speaking, the parameters supported by the paramsOBJ parameter are determined by the specific implementation of inform. Technically, what happens when the inform instance method is called is that the widget finds the nearest parent up the parent chain that provides an implementation for the showInform instance method.

Typically, showInform is implemented at the page widget level, but it can also be overrided by parent widgets closer to the widget on which the inform instance method is called. If no showInform implementation is provided, anywhere up the parent chain, then the browser's default alert global function is used.

Because a decorated HTML implementation is asynchronous in its behavior, the inform logic must be coded asynchronously by providing a callback handler through the callback parameter - even in the case where this class resorts to using the built-in alert global function.

EXAMPLE

myWidget.inform ({
  title:'Items Deleted',
  message:'The items that you selected have been successfully deleted.',
  okText:'OK'
  callback:function () {
    // continuation code
  }
});

NOTES

see also the companion confirm instance method
no "cancel" button is shown for information dialogs

IMPLEMENTATION INFO

this feature was introduced in this module

4.22. injectNodeHtml

Lets you inject the specified HTML markup into the specified DOM node, using the specified injection mode.

SYNTAX

myWidget.injectNodeHtml (nodeSTRorBLOB,htmlSTR,injectModeSTR);

This method uses the Uize.Dom.Basics.injectHtml static method in its implementation. For more details and for a more in-depth discussion of the supported injection modes and how they behave, consult the reference for the Uize.Dom.Basics module.

VARIATION

myWidget.injectNodeHtml (nodeSTRorBLOB,htmlSTR);

When no injectModeSTR parameter is specified, then the default injection mode 'inner bottom' will be used.

NOTES

compare to the setNodeInnerHtml instance method
compare to the Uize.Dom.Basics.injectHtml static method

IMPLEMENTATION INFO

this feature was introduced in this module

4.23. insertOrWireUi

Calls either the wireUi or insertUi instance method, depending on the value of the built state property.

SYNTAX

myWidget.insertOrWireUi ();

If built is set to true at the time that insertOrWireUi is called, then the wireUi method will be called. Otherwise, the insertUi method will be called. When you're dealing with widgets where the UI may or may not already be built, and the value of the built property is not guaranteed to be known, then the insertOrWireUi method provides a convenient conditional behavior so that you don't have to always write such conditional logic in your application or widget code.

NOTES

see the related insertUi and wireUi instance methods

IMPLEMENTATION INFO

this feature was introduced in this module

4.24. insertUi

Inserts the UI for an instance by calling the buildHtml instance method, and then wires the instance's UI by calling the wireUi method.

SYNTAX

myWidget.insertUi ();

The insertUi method always first builds the instance's UI, regardless of the value of the built state property. To conditionally build an instance's UI before wiring it, taking into account the value of the built property, use the insertOrWireUi instance method.

NOTES

see the related insertOrWireUi and wireUi instance methods

IMPLEMENTATION INFO

this feature was introduced in this module

4.25. is

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.26. isMet

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.27. kill

Overrides the kill method of the Uize.Class base class to call the kill method on all of an instance's child widgets.

SYNTAX

myWidget.kill ();

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)

4.28. localize

Returns a string value, representing the localized version of the specified resource string or function.

SYNTAX

localizedSTR = myWidget.localize (resourceIdSTR,substitutionsARRAYorOBJ);

When an array is specified for the substitutionsARRAYorOBJ parameter, the values in the array will be substituted for the tokens {0}, {1}, {2}, ..., {N}, where N is the index of the last element in the array.

EXAMPLE

myWidget.set ({localized:{welcomeMessage:'Welcome, {0} of {1}, {2}'}});
var localWelcome = myWidget.localize ('welcomeMessage',['Chris','California','USA']);

The above example would produce the result 'Welcome, Chris of California, USA'.

When an object is specified for the substitutionsARRAYorOBJ parameter, then the keys (property names) of the object are assumed to be the token names.

EXAMPLE

myWidget.set ({localized:{welcomeMessage:'Welcome, {firstName} of {state}, {country}'}});
var localWelcome = myWidget.localize (
  'welcomeMessage',
  {firstName:'Chris',state:'California',country:'USA'}
);

The above example would also produce the result 'Welcome, Chris of California, USA'.

VARIATION 1

localizedSTR = myWidget.localize (resourceIdSTR,substitutionSTRorBOOLorNUM);

When a simple type substitutionSTRorBOOLorNUM parameter is specified in place of a hash or array of multiple substitutions, then the specified simple type value will be substituted for the token {0}.

EXAMPLE

myWidget.set ({localized:{welcomeMessage:'Welcome, {0}'}});
var localWelcome = myWidget.localize ('welcomeMessage','Chris');

The above example would produce the result 'Welcome, Chris'.

VARIATION 2

localizedSTR = myWidget.localize (resourceIdSTR);

When no substitutionsARRAYorOBJ or substitutionSTRorBOOLorNUM parameter is specified, then no substitution will be performed - the localized resource string will be looked up and simply returned as is. If the localized resource is a function (see the section Function Type Resources), then it will simply be called with an undefined value as its input parameter.

EXAMPLE

myWidget.set ({localized:{welcomeMessage:'Welcome'}});
var localWelcome = myWidget.localize ('welcomeMessage');

The above example would produce the result 'Welcome'.

VARIATION 3

localizedSTR = myWidget.localize (resourceIdSTR,substitutionsANYTYPE,tokenNamingSTR);

When the optional tokenNamingSTR parameter is specified, the syntax of the tokens that will be substituted can be controlled. This facility provides a lot of flexibility in how tokens are formatted inside localized resource strings. The value specified for the tokenNamingSTR parameter should be a string containing the text 'KEY' somewhere inside it, where that segment will be replaced with the name for a given key. So, for example, a value of '[KEY]' for the tokenNamingSTR parameter would produce the token name '[firstName]' for the substitution key 'firstName'. Consider the following example...

EXAMPLE

myWidget.set ({localized:{welcomeMessage:'Welcome, [firstName] of [state], [country]'}});
var localWelcome = myWidget.localize (
  'welcomeMessage',
  {firstName:'Chris',state:'California',country:'USA'},
  '[KEY]'
);

The above example would also produce the result 'Welcome, Chris of California, USA'.

4.28.1. Providence

An important feature of the localize method is its ability to go up the parent chain of a widget to find the nearest parent widget that provides a value for the specified resource in its localized state property.

This allows localized resources to be declared with the top-most parent widget in a page - the page widget - if that is what proves most convenient for the application. Additionally, a parent widget might define a value for a localized resource which is overrided by a child widget's localized resources map.

EXAMPLE

myWidget.parent.set ({localized:{welcomeMessage:'Welcome, {0} of {1}, {2}'}});
myWidget.set ({localized:{}});
var localWelcome = myWidget.localize ('welcomeMessage',['Chris','California','USA']);

The above example would still produce the result 'Welcome, Chris of California, USA', even though the localized resource string is not declared with the myWidget instance, but its parent instead.

4.28.2. Function Type Resources

A simple yet powerful feature of the localize method is its support for function type resources.

Typically, a localized resource will be a string. In some cases, such strings will have substitution tokens and the localize method will need to be called with one or more substitution values. In exceptional cases, plain old token substitution may not be adequate and more sophisticated string construction may be necessary. In such cases, a function type resource can be used.

For a detailed discussion of this feature, complete with examples, consult the section Function Type Localized Resources of the guide JavaScript Localization.

NOTES

see also the localized state property.

IMPLEMENTATION INFO

this feature was introduced in this module

4.29. met

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.30. nodeId

Returns a string, representing the fully namespaced ID for the specified node of the widget.

SYNTAX

nodeIdSTR = myInstance.nodeId (nodeNameSTR);

The nodeId method is intended primarily for use within the HTML generator (usually a JST template) for a widget.

IMPLEMENTATION INFO

this feature was introduced in this module

4.31. onChange

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.32. once

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.33. removeChild

The removeChild instance method lets you remove a child widget from a widget.

SYNTAX

myWidget.removeChild (childWidgetSTRorOBJ);

When using this method, the child widget to remove can be specified by its name, or by an object reference to it.

NOTES

a state property matching the child widget name is marked as unmet in the addedChildren instance property
see also the addChild instance method, and the children instance property

IMPLEMENTATION INFO

this feature was introduced in this module

4.34. removeNode

Removes the specified DOM node (or nodes) from the DOM.

SYNTAX

myWidget.removeNode (nodeSTRorBLOB);

IMPLEMENTATION INFO

this feature was introduced in this module

4.35. removeUi

Unwires the UI of the widget, removes the widget's root node from the DOM, and calls this method on all the widget's child widgets.

SYNTAX

myWidget.removeUi ();

IMPLEMENTATION INFO

this feature was introduced in this module

4.36. set

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.37. setInherited

Allows us to set values for the specified state properties on the instance in the widget's parent chain from which the properties are inherited.

SYNTAX

myWidget.setInherited (setGetPropertiesOBJ);

NOTES

see also the callInherited, getProvider, and getInherited instance methods

IMPLEMENTATION INFO

this feature was introduced in this module

4.38. setNodeClipRect

Sets the clip style property of the specified DOM node (or Node Blob) of the widget instance, using the supplied rectangle coordinates.

SYNTAX

myWidget.setNodeClipRect (nodeSTRorBLOB,leftINT,topINT,rightINT,bottomINT);
compare to the Uize.Dom.Basics.setClipRect static method

IMPLEMENTATION INFO

this feature was introduced in this module

4.39. setNodeInnerHtml

Set the innerHTML property for the specified DOM node (or Node Blob) to the specified HTML string.

SYNTAX

myWidget.setNodeInnerHtml (nodeSTRorBLOB,htmlSTR);

This method uses the Uize.Dom.Basics.setInnerHtml static method in its implementation. For more details, consult the reference for the Uize.Dom.Basics module.

EXAMPLE

page.setNodeInnerHtml (
  'priceShell',
  '<span class="priceAmount">Node' + (priceInCents / 100).toFixed (2) + '</span>
);

NOTES

compare to the injectNodeHtml instance method
compare to the Uize.Dom.Basics.setInnerHtml static method

IMPLEMENTATION INFO

this feature was introduced in this module

4.40. setNodeOpacity

Sets the opacity (and, therefore, the transparency) of the specified DOM node (or nodes).

SYNTAX

myWidget.setNodeOpacity (nodeSTRorBLOB,opacityFLOATorOBJ);

The value of the opacityFLOATorOBJ parameter should be a number in the range of 0 to 1, where 0 represents completely invisible, 1 represents completely opaque, and any fractional values inbetween represent varying degrees of transparency / opacity. Alternatively, if an instance of a Uize.Class subclass is specified, then a value will be obtained by invoking the instance's valueOf Intrinsic Method.

NOTES

compare to the Uize.Dom.Basics.setOpacity static method

IMPLEMENTATION INFO

this feature was introduced in this module

4.41. setNodeProperties

Sets the specified properties for the specified DOM node (or nodes).

SYNTAX

myWidget.setNodeProperties (nodeSTRorBLOB,propertiesOBJ);

EXAMPLE

myWidget.setNodeProperties (
  'thumbnail',
  {
    src:...,
    width:...,
    height:...,
    title:...
  }
);

NOTES

compare to the Uize.Dom.Basics.setProperties static method

IMPLEMENTATION INFO

this feature was introduced in this module

4.42. setNodeStyle

Sets values for an arbitrary set of style attributes for the specified DOM node (or nodes).

SYNTAX

myWidget.setNodeStyle (nodeSTRorBLOB,propertyValueSTR);

EXAMPLE

myWidget.setNodeStyle (
  'selector',
  {
    display:'block',
    position:'absolute',
    visibility:'inherit',
    top:'100px'
  }
);

When number type values are specified for CSS style properties, those values will be converted to strings by appending the "px" unit. When string type values are specified, the unit should already be present in the value. Instances of Uize.Class subclasses can also be specified, and they will be converted to values by invoking their valueOf Intrinsic Method. For a more detailed discussion, consult the reference for the Uize.Dom.Basics.setStyle static method.

NOTES

see also the companion getNodeStyle instance method
compare to the Uize.Dom.Basics.getStyle and Uize.Dom.Basics.setStyle static methods

IMPLEMENTATION INFO

this feature was introduced in this module

4.43. setNodeValue

Sets the value of the specified DOM node (or Node Blob) of the widget instance.

SYNTAX

myWidget.setNodeValue (nodeSTRorBLOB,valueSTRorBOOLorNUM);

This method uses the Uize.Dom.Basics.setValue static method in its implementation. For more details, consult the reference for the Uize.Dom.Basics module.

NOTES

you can use the setNodeValue instance method to set values on readonly form elements
see the corresponding getNodeValue instance method
the value parameter can be an object that implements a valueOf interface (such as an instance of a Uize.Class subclass that implements the value state property)
compare to the Uize.Dom.Basics.setValue static method

IMPLEMENTATION INFO

this feature was introduced in this module

4.44. showConfirm

The implementation for a decorated confirmation dialog.

This method will be used when the confirm instance method is called. This method is typically implemented at the page widget level, although it can also be implemented by child widgets at any level on the widget tree.

NOTES

the initial value is undefined
see the confirm instance method
see also the companion showInform instance method

4.45. showInform

The implementation for a decorated inform (i.e. alert) dialog.

This method will be used when the infom instance method is called. This method is typically implemented at the page widget level, although it can also be implemented by child widgets at any level on the widget tree.

NOTES

the initial value is undefined
see the inform instance method
see also the companion showConfirm instance method

4.46. showNode

Lets you show or hide the specified DOM node, using the visibility CSS style property.

SYNTAX

myWidget.showNode (nodeSTRorBLOB,mustShowANYTYPE);

While typically a Boolean, the mustShowANYTYPE parameter can be of any type and the node will be shown if it resolves to true, and hidden if it resolves to false - with the exception of undefined, when the node will be shown (see explanation below).

VARIATIONS

myWidget.displayNode (mustShowANYTYPE);

When no mustShowANYTYPE parameter is specified (or when its value is undefined), the node will be shown.

NOTES

compare to the displayNode instance method
compare to the Uize.Dom.Basics.show static method

IMPLEMENTATION INFO

this feature was introduced in this module

4.47. toggle

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.48. unmet

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.49. unwire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.50. unwireNode

Lets you unwire one or more event handlers for the specified DOM node.

SYNTAX

myWidget.unwireNode (nodeSTRorBLOB,eventNameSTR,eventHandlerFUNC);

EXAMPLE

function clickHandler1 () {alert ('foo')}
function clickHandler2 () {alert ('bar')}

myWidget.wireNode ('','click',clickHandler1);
myWidget.wireNode ('','click',clickHandler2);

myWidget.unwireNode ('','click',clickHandler1);

The above example would unwire only the clickHandler1 handler for the click event of the myWidget instance's root node. So, after the above code has been executed, clicking on the root node of myWidget would produce only one alert dialog displaying the text "bar" (so long, foo).

VARIATION 1

myWidget.unwireNode (nodeSTRorBLOB,eventNameSTR);

When no eventHandlerFUNC parameter is specified, then all handlers wired for the specified event of the specified DOM node of the widget instance will be unwired.

EXAMPLE

myWidget.unwireNode ('','click');

The above example would unwire all handlers for the click event of the myWidget instance's root node.

VARIATION 2

myWidget.unwireNode (nodeSTRorBLOB,eventNamesToHandlersMapOBJ);

When the eventNamesToHandlersMapOBJ parameter is specified in place of the eventNameSTR and eventHandlerFUNC parameters, then this method has the effect of iterating through the event-name-to-handler mappings in the eventNamesToHandlersMapOBJ object and unwiring the handler for each mapping.

The contents of the eventNamesToHandlersMapOBJ object must be of the form...

{
  event1Name:event1HandlerFUNC,
  event2Name:event2HandlerFUNC,
  ...
  eventNName:eventNHandlerFUNC
}

EXAMPLE

function mouseoverHandler () {alert ('mouseover')}
function mouseoutHandler () {alert ('mouseout')}
function clickHandler () {alert ('click')}

myWidget.wireNode (
  '',
  {
    mouseover:mouseoverHandler,
    mouseout:mouseoutHandler,
    click:clickHandler
  }
);
myWidget.unwireNode (
  '',
  {
    mouseover:mouseoverHandler,
    mouseout:mouseoutHandler
  }
);

In the above example, handlers are being wired to the mouseover, mouseout, and click events of the widget's root node. Then the handlers for the mouseover and mouseout events are being unwired, leaving only the handler that was wired to the click event.

VARIATION 3

myWidget.unwireNode (nodeSTRorBLOB);

When no eventNameSTR or eventHandlerFUNC parameters are specified, then all handlers wired for all events of the specified DOM node of the widget instance will be unwired.

EXAMPLE

myWidget.unwireNode ('');

The above example would unwire all handlers for all events of the myWidget instance's root node.

VARIATION 4

myWidget.unwireNode ();

When no parameters are specified, then all event handlers wired for the entire widget instance will be unwired.

IMPORTANT

This method only unwires event handlers that have been wired by the widget instance on which this method is called. Event handlers that may have been wired for the same node(s) by other widget instances or application code are not unwired.

NOTES

see the companion wireNode instance method
compare to the unwireNodeEventsByMatch instance method
compare to the Uize.Dom.Basics.unwire static method of the Uize.Dom.Basics module

IMPLEMENTATION INFO

this feature was introduced in this module

4.51. unwireNodeEventsByMatch

Lets you unwire one or more event handlers for the specified DOM node, using a wiring match object.

SYNTAX

myWidget.unwireNodeEventsByMatch (nodeSTRorBLOB,wiringtMatchOBJ);

The wiringtMatchOBJ parameter is an object of the form...

{
  eventName:eventNameSTR,  // name of event to unwire (optional, all if not specified)
  handler:eventHandlerFUNC // handler to unwire (optional, all if not specified)
}

EXAMPLE

myWidget.unwireNodeEventsByMatch ('',{eventName:'click'});

The above example would unwire all handlers for the click event of the myWidget instance's root node.

VARIATION 1

myWidget.unwireNodeEventsByMatch (nodeSTRorBLOB);

When no wiringtMatchOBJ parameter is specified, all handlers wired for all events of the specified DOM node of the widget instance will be unwired.

EXAMPLE

myWidget.unwireNodeEventsByMatch ('preview');

The above example would unwire all handlers for all events of the myWidget instance's 'preview' DOM node.

VARIATION 2

myWidget.unwireNodeEventsByMatch ();

When no parameters are specified, then all event handlers wired for the entire widget instance will be unwired.

IMPORTANT

This method only unwires event handlers that have been wired by the widget instance on which this method is called. Event handlers that may have been wired for the same node(s) by other widget instances or application code are not unwired.

NOTES

see the related wireNode instance method
compare to the unwireNode instance method

IMPLEMENTATION INFO

this feature was introduced in this module

4.52. unwireUi

Unwires all the events associated to the instance and all of its child widgets. After this method has been called, the wired state property will be set to false.

SYNTAX

myWidget.unwireUi ();

NOTES

see also the wireUi instance method

IMPLEMENTATION INFO

this feature was introduced in this module

4.53. updateUi

Not implemented in this class, this method is intended to be overrided / implemented in a subclass.

SYNTAX

myWidget.updateUi ();

The updateUi method is called on the instance as the last step of this class' wireUi method implementation. The updateUi method should perform any DOM updates necessary in order that the UI correctly reflect the widget's state.

4.53.1. Child Widgets

It is generally not necessary for the implementation of this method to invoke updates on child widgets, unless the child widgets are used to represent some aspects of the widget's state and may have become out of sync with that state. Typically, state of a widget that is reflected using its child widgets is set on those child widgets whenever that state changes using private update handlers that are more granular than the updateUi method. It might be desirable in one's implementation to break granular update code out into private methods so that this code can be called for those state changes as well as from the updateUi method's implementation.

NOTES

although this method currently has no implementation in this class, it is suggested that subclasses call this method on their superclass as the last step in their implementation, as this method may someday perform other operations in this class

IMPLEMENTATION INFO

this feature was introduced in this module

4.54. valueOf

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)

IMPLEMENTATION INFO

4.55. whenever

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.56. wire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)

4.57. wireNode

Wires the specified handler function to the specified event, or the specified handlers to the specified events, of the specified DOM node (or Node Blob) of the widget instance.

SYNTAX

myWidget.wireNode (nodeSTRorBLOB,eventNameSTR,eventHandlerFUNC);

EXAMPLE

myWidget.wireNode (
  '',
  'click',
  function () {
    // do something
  }
);

In the above example, a handler is being wired to the click event of the widget's root node.

VARIATION

myWidget.wireNode (nodeSTRorBLOB,eventNamesToHandlersMapOBJ);

When the eventNamesToHandlersMapOBJ parameter is specified in place of the eventNameSTR and eventHandlerFUNC parameters, then this method has the effect of iterating through the event-name-to-handler mappings in the eventNamesToHandlersMapOBJ object and wiring the handler for each mapping.

The contents of the eventNamesToHandlersMapOBJ object must be of the form...

{
  event1Name:event1HandlerFUNC,
  event2Name:event2HandlerFUNC,
  ...
  eventNName:eventNHandlerFUNC
}

EXAMPLE

myWidget.wireNode (
  '',
  {
    mouseover:
      function () {
        // do something
      },
    mouseout:
      function () {
        // do something
      },
    click:function () {
      // do something
    }
  }
);

In the above example, handlers are being wired to the mouseover, mouseout, and click events of the widget's root node.

NOTES

see the companion unwireNode instance method
compare to the Uize.Dom.Basics.wire static method of the Uize.Dom.Basics module

IMPLEMENTATION INFO

this feature was introduced in this module

4.58. wireUi

Wires the widget's UI.

After the UI has been wired, all of the widget's child widgets are wired by calling this method on each of them. Finally, the widget's UI is updated through a call to the updateUi instance method, which also has the effect of updating the UI of all child widgets down the widget tree.

When creating a subclass of Uize.Widget, this method should be overrided according to the following structure...

_class.instanceMethods ({
  wireUi:function () {
    var m = this;
    if (!m.isWired) {

      // do a
      // whole bunch
      // of wiring

      _superclass.doMy (m,'wireUi');
    }
  }
});

...where _superclass is the superclass from which the new widget class is being subclassed.

NOTES

if the widget's UI has already been wired, this method has no effect.
see also the wired state property
see also the updateUi and unwireUi instance methods

IMPLEMENTATION INFO

this feature was introduced in this module

5. State Properties

5.1. built

A boolean, indicating whether or not a specific child widget's UI has already been built and inserted into the DOM by the time that its parent widget wires up the child widgets.

NOTES

the initial value is true

IMPLEMENTATION INFO

this feature was introduced in this module

5.2. busy

A boolean, indicating whether or not the widget is busy.

The busy state can be useful when a complex set of processes needs to be performed and user interaction with certain widgets needs to be blocked during that time. Widgets that are in a busy state should not allow user interaction. It is up to an individual widget class to provide its own implementation for the busy state.

NOTES

the initial value is false
this state property has a significantly different effect to the enabled state property

IMPLEMENTATION INFO

this feature was introduced in this module

5.3. busyInherited

A boolean, indicating whether or not the instance is busy. A widget subclass can use this state property when performing UI updates in order to reflect a busy state.

This property will be true if the busy state property is set to true, or if busy is set to 'inherit' and the value inherited from up the parent chain resolves to true. If an inherited value resolves to inherit, then this property will be set to false.

NOTES

the initial value is false
see also the busy state property
see also the getInherited instance method

IMPLEMENTATION INFO

this feature was introduced in this module

5.4. busyParentTickle

IMPLEMENTATION INFO

this feature was introduced in this module

5.5. children

IMPLEMENTATION INFO

this feature was introduced in this module

5.6. children

A special state property that provides a way to distribute widget properties to any or all of the widget's child widgets, or even child widgets of the widget's child widgets - all the way down to the deepest child widgets in the widget's widget tree.

For a detailed discussion of the children state property, consult the JavaScript Widgets guide and read through specifically the section entitled "The children State Property".

NOTES

see also the companion children instance property
see also the related parent state property

5.7. container

A string, representing the ID of a container node, or an object reference to a container node, into which the HTML for a widget should be inserted when the insertUi instance method is called.

NOTES

the initial value is undefined

IMPLEMENTATION INFO

this feature was introduced in this module

5.8. enabled

A boolean, specifying whether or not the widget is enabled.

The enabled state can be useful when a complex set of processes needs to be performed and user interaction with certain widgets needs to be blocked during that time. Widgets that are not in an enabled state (i.e. disabled) should not allow user interaction. It is up to an individual widget class to provide its own implementation for the enabled state.

NOTES

the initial value is true
this state property has a significantly different effect to the busy state property

IMPLEMENTATION INFO

this feature was introduced in this module

5.9. enabledInherited

A boolean, indicating whether or not the instance is enabled. A widget subclass can use this state property when performing UI updates in order to reflect a disabled state.

This property will be set to true if the enabled state property is set to true, or if enabled is set to 'inherit' and the inherited value resolves to either 'inherit' or true.

NOTES

the initial value is true
see also the enabled state property
see also the getInherited instance method

IMPLEMENTATION INFO

this feature was introduced in this module

5.10. enabledParentTickle

IMPLEMENTATION INFO

this feature was introduced in this module

5.11. html

A string, function, object, or boolean value, specifying the HTML that should be inserted into the document by the insertUi instance method.

5.11.1. Values Types

The following value types are supported for the html state property...

5.11.1.1. String

Lets you specify a template string for the HTML of a widget.

A string value specified for this property may contain tokens of the form [#setGetPropertyName], which will be substituted by the values of the corresponding state properties of the widget.

5.11.1.2. Function

Lets you specify a generator function for a widget's markup.

A function that you register as an HTML generator for your widget using the html state property should expect to receive one parameter, being an object containing the HTML generator input. The function should return either a string, being the generated HTML markup for the widget, or a DOM node or array of DOM nodes. While the generator function can use the values in the HTML generator input object when constructing the HTML for the widget, the string returned by the function may also contain tokens of the form [#setGetPropertyName], which will be substituted by the values of the corresponding state properties of the widget.

5.11.1.3. Object

Lets you supply a JavaScript Template Module as the HTML generator for a widget.

When specifying an object for this property, the object should contain a process property that is a generator function. That generator function should expect to receive one parameter, being an object containing the HTML generator input. The function should return a string, being the generated HTML markup for the widget. The string returned will not be processed any further and will be inserted into the document as is, so it is the reponsibility of the generator function in this case to stitch in any values it cares to from the HTML generator input.

Now, typically an object specified for the html state property will be a JavaScript Template Module, but you can supply any object - the only requirement is that it have a process property that is a generator function. Since the function type value for the html state property results in the string returned by the function being processed further with token substitution, using the object type is one way to dodge that extra processing if it's not desired - without actually having to create a full-blown JavaScript Template Module.

INSTEAD OF...

myWidget.set ({html:myWidgetHtmlGeneratorFunction});

YOU COULD USE...

myWidget.set ({html:{process:myWidgetHtmlGeneratorFunction}});

5.11.1.4. Boolean

Lets you embed a JavaScript Template inside a widget's markup, which will then be used for generating the widget's UI.

When the boolean value true is set for this property, and if the Uize.Template module is loaded, then the Uize.Widget class will attempt to find a script tag inside the container, shell, or root node of the widget with the type "text/jst" (JavaScript Template). If such a script tag is found, then its contents will be compiled by the Uize.Template module and the resulting JST module will be set on the html state property.

5.11.2. HTML Generator Input

When a generator function is called, it is supplied with an object that contains the current state of the state properties for the widget instance.

This allows the generator function to use any - or all - of the state properties when constructing the HTML for a specific instance of the widget.

SPECIAL PATH PROPERTIES

In addition to the state property values, the HTML Generator Input object also contains the two special properties pathToResources and blankGif, where pathToResources is set to the value of the Uize.pathToResources static property, and blankGif is set to the result from calling the Uize.Widget.getBlankImageUrl static method.

These special path properties allow widgets to generate HTML that references assets that are located in directories relative to the JavaScript modules that implement the widgets.

NOTES

the initial value is undefined

IMPLEMENTATION INFO

this feature was introduced in this module

5.12. idPrefix

A string, specifying the ID prefix to be used when resolving DOM nodes and child widgets to DOM node references.

NOTES

see the related idPrefixConstruction state property
the initial value is undefined

IMPLEMENTATION INFO

this feature was introduced in this module

5.13. idPrefixConstruction

A string, specifying the mode of construction of the value for the idPrefix state property.

The value of the idPrefixConstruction property is used when the value of the idPrefix property is constructed. This happens either at the time that a widget is added as a child widget of a parent widget using the addChild instance method, or when the idPrefix value of a child widget's parent widget is modified after it has already been added as a child.

VALUES

'same as parent' - When idPrefixConstruction is set to 'same as parent', the idPrefix property will be set to the value of a widget's parent widget whenever the idPrefix value needs to be constructed.
'concatenated' - When idPrefixConstruction is set to 'concatenated', the idPrefix property will be constructed using the idPrefix value of a widget's parent widget as a prefix, and using the value of the widget's name property as a suffix, with the prefix and suffix separated by a "_" (underscore) character. For example, if a button widget has the name 'selectAll', and its parent widget has the idPrefix value of 'page_collection', then the idPrefix value produced for the button widget using this idPrefixConstruction mode would be 'page_collection_selectAll'.
'explicit' - When idPrefixConstruction is set to 'explicit', an explicit value specified for a widget's idPrefix property will be used throughout the lifetime of the widget, and the idPrefix will not be otherwise derived.
undefined (the default value) - When idPrefixConstruction is set to undefined, the behavior for the value 'concatenated' will be used (i.e. the value undefined is equivalent to the value 'concatenated').

NOTES

see the related idPrefix state property
the initial value is undefined (equivalent to the value 'concatenated')

IMPLEMENTATION INFO

this feature was introduced in this module

5.14. insertionMode

A string, specifying the injection mode that should be used when inserting the HTML for a widget into the page.

This property works in conjunction with the built, container, and html state properties. If the value for the built property is true for a widget instance, then insertionMode is not applicable. But if the value for built is false, then the HTML generated using the html state property will be injected into a container node specified by the container state property (or the shell DOM node, or the root node of the widget instance, or the document's body, whichever is non-null) using the mode specified by insertionMode.

EXAMPLE

page.addChild (
  'quantitySlider',
  Uize.Widget.Bar.Slider,
  {
    html:MySiteNamespace.Templates.Slider,
    built:false,
    container:Uize.Dom.Basics.getById ('quantityUiShell'),
    insertionMode:'inner bottom'
  }
);

In the above example, an instance of the Uize.Widget.Bar.Slider class will have its HTML generated by the template module MySiteNamespace.Templates.Slider and then inserted into the container node quantityUiShell, using the 'inner bottom' insertion mode. This means that if the quantityUiShell node already contained contents, that contents will not be replaced by insertion of the widget's HTML, but the widget's HTML will be inserted at the bottom - under the existing contents.

5.14.1. Values

The possible values for the insertionMode state property are the same as the valid values for the injectModeSTR parameter of the Uize.Dom.Basics.injectHtml static method: 'inner bottom', 'inner top', 'outer bottom', 'outer top', 'inner replace', and 'outer replace'. For a more in-depth discussion of insertion modes and how they behave, consult the reference for the Uize.Dom.Basics.injectHtml static method.

If the value of the insertionMode state property is null, undefined, or an empty string, then an insertion mode is chosen automatically based upon the node that the HTML is being inserted into: 'inner replace' if a container node is specified, and 'inner bottom' into the document body if no container node is specified or if the document body is specified for the container.

NOTES

the initial value is undefined (which results in default auto behavior)
see also the built, container, and html state properties

IMPLEMENTATION INFO

this feature was introduced in this module

5.15. localized

An object which, if defined, lets you specify localized strings that can be accessed using the localized instance method.

EXAMPLE

myWidget.set ({
  localized:{welcomeMessage:'Welcome, {firstName} of {state}, {country}'}
});
var localWelcome = myWidget.localize (
  'welcomeMessage',
  {firstName:'Chris',state:'California',country:'USA'}
);

The above example would produce the result 'Welcome, Chris of California, USA'.

NOTES

the initial value is undefined
see also the localize instance method

IMPLEMENTATION INFO

this feature was introduced in this module

5.16. name

A read-only string, specifying the name of the widget if it is added as a child widget of another widget by calling the addChild instance method on that other widget.

The value of this property is set for an instance when the instance is added as a child widget of another widget instance. The value is read-only and is not intended to be set later.

NOTES

this property is read-only
the initial value is undefined

IMPLEMENTATION INFO

this feature was introduced in this module

5.17. nodeMap

An object which, if defined, lets you provide override mappings for DOM nodes. Each property's name-value pair is a single DOM node mapping, where the property name is the natural name (as implemented in the widget subclass) for the DOM node, and where the property value is the override (which can be either an alternate node name, or an actual node reference).

NOTES

the initial value is undefined

IMPLEMENTATION INFO

this feature was introduced in this module

5.18. parent

A reference to the instance's parent, if the instance has been added as a child widget of another widget by calling the addChild instance method on that other widget.

The value of this property is set for an instance when the instance is added as a child widget of another widget instance. The value is not intended to be set directly, but will be modified if the instance is removed from its parent by calling the removeChild instance method on the parent widget.

NOTES

the initial value is undefined
see also the related children instance property

IMPLEMENTATION INFO

this feature was introduced in this module

5.19. wired

A boolean, indicating whether or not the widget's UI has been wired up. This property is set to true after the wireUi instance method has been called on a widget and all its child widgets.

NOTES

the initial value is false
see also the isWired instance property

IMPLEMENTATION INFO

this feature was introduced in this module

6. Static Methods

6.1. Uize.Widget.alphastructor

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.2. Uize.Widget.declare

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.3. Uize.Widget.doMy

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.4. Uize.Widget.dualContextMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.5. Uize.Widget.dualContextProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.6. Uize.Widget.fire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.7. Uize.Widget.get

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.8. Uize.Widget.getBlankImageUrl

Returns a string, representing the relative path from the current document to the "blank.gif" image resource that is available to all Uize.Widget subclasses that may need it in generating HTML markup, or in building or manipulating DOM nodes.

SYNTAX

blankImageUrlSTR = Uize.Widget.getBlankImageUrl ();

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

6.9. Uize.Widget.instanceMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.10. Uize.Widget.instanceProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.11. Uize.Widget.mixins

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.12. Uize.Widget.omegastructor

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.13. Uize.Widget.set

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.14. Uize.Widget.singleton

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.15. Uize.Widget.spawn

Spawns a number of widgets using the specified state property values, attaches them as children to the specified parent widget, and returns the spawned widgets as an array.

SYNTAX

widgetsARRAY = Uize.Widget.spawn (propertiesOBJ,parentWidgetOBJ);

VARIATION

widgetsARRAY = Uize.Widget.spawn (propertiesOBJ);

When no parentWidgetOBJ parameter is specified, the spawned widgets are not added as children of any parent widget and are wired immediately by calling their wireUi instance method.

6.15.1. Called on Subclasses

The Uize.Widget.spawn static method is inherited by subclasses of Uize.Widget and spawns instances of the class on which it is called, so it is not typically called on the Uize.Widget class but rather on a specific widget class.

6.15.2. The propertiesOBJ Parameter

The propertiesOBJ parameter is an object, containing values for the state properties of the widget class of which instances are being spawned.

Besides the required idPrefix property (see Special Meaning of idPrefix), the propertiesOBJ parameter may contain values for any of the other state properties of the widget class on which this method is being called.

6.15.3. Special Meaning of idPrefix

The number of widgets spawned is determined by the value of the "idPrefix" property in the propertiesOBJ object.

A value for "idPrefix" must be specified, otherwise the Uize.Widget.spawn method will not work correctly. The value of this property identifies one or more DOM nodes for which the widget instances should be spawned, and may be a DOM node reference, a string representing the id of a DOM node, an array of DOM node references, or a find expression object that will be used with the Uize.Dom.Basics.find static method to find the DOM nodes.

Once the value of the "idPrefix" property has been resolved to one or more DOM nodes, an instance of the widget class on which the method is called will be created for each of the DOM nodes. For each widget instance that is created, the actual idPrefix value for the instance will be derived from the id attribute of the DOM node for which the instance is being created. For this reason, the DOM nodes represented by the "idPrefix" property should be the root nodes for the widget instances that will be spawned.

6.15.4. Child Widget Naming

When spawned widgets are added as child widgets of a specified parent widget, the names of the child widget are - if possible - derived using the value of the idPrefix state property of the parent widget and the value of the id attribute for the DOM node for which a widget instance is being spawned.

For example, if the id attribute of a DOM node for which a widget is to be spawned has the value "page_item0", and if the parent widget of the spawned widget is a page widget instance with the idPrefix value of 'page', then the spawned widget will be added as the child named "item0".

6.15.5. An Example

Let's look at an example of how the Uize.Widget.spawn static method can be used...

EXAMPLE

Uize.Widget.CollectionItem.Zooming.spawn (
  {
    idPrefix:{root:'thumbnails',tagName:'A',className:'thumbnail'},
    previewZoomUrl:function () {return this.get ('previewUrl')},
    zoomPower:2.5
  },
  page
);

In the above example, instances of the Uize.Widget.CollectionItem.Zooming widget class are being spawned - one for each of the nodes obtained by evaluating the find expression object {root:'thumbnails',tagName:'A',className:'thumbnail'}.

Besides the idPrefix value here that identifies the DOM nodes for which the Uize.Widget.CollectionItem.Zooming instances should be created, the values specified for the previewZoomUrl and zoomPower state properties of this widget class are common for all instances that are spawned. Finally, the parentWidgetOBJ parameter is used here to attach the spawned instances as children of a page widget instance.

NOTES

the widget adoption mechanism implemented in the Uize.Widget.Page class supports a declaration syntax for spawning widgets

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

6.16. Uize.Widget.stateProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.17. Uize.Widget.staticMethods

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.18. Uize.Widget.staticProperties

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.19. Uize.Widget.subclass

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.20. Uize.Widget.toggle

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.21. Uize.Widget.treeInheritedStateProperties

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

6.22. Uize.Widget.unwire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

6.23. Uize.Widget.wire

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

7. Static Properties

7.1. Uize.Widget.busyParentTickle

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

7.2. Uize.Widget.enabledParentTickle

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

7.3. Uize.Widget.isWired

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses

7.4. Uize.Widget.mBindings

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is not inherited by subclasses

7.5. Uize.Widget.moduleName

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)
this static feature is inherited by subclasses

7.6. Uize.Widget.nonInheritableStatics

IMPLEMENTATION INFO

this is an override of an inherited feature (implementation is in this module, first introduced in Uize.Class)
this static feature is not inherited by subclasses

7.7. Uize.Widget.pathToResources

Inherited from Uize.Class.

IMPLEMENTATION INFO

this is an inherited feature (implementation is in Uize.Class, first introduced in Uize.Class)
this static feature is inherited by subclasses

7.8. Uize.Widget.undefined

IMPLEMENTATION INFO

this feature was introduced in this module
this static feature is inherited by subclasses