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.

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

SEARCH FOR EXAMPLES

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

SEARCH

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

1.3.3. Features Inherited From Other Modules

1.3.4. Modules Directly Under This Namespace

1.3.5. Unit Tests

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

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

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

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

3.2.2. The Special children state Property

NOTES

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

IMPLEMENTATION INFO

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

myInstance.addChildren (childrenOBJ);

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'
  }
});

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

myInstance.addChildren (childrenOBJ,commonPropertiesOBJ);

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

4.2.3. More Concise

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'
  }
);

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

NOTES

IMPLEMENTATION INFO

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

_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 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

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

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

IMPLEMENTATION INFO

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

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

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

Inherited from Uize.Class.

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

SYNTAX

myWidget.globalizeNode (nodeSTRorBLOB);

IMPLEMENTATION INFO

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

EXAMPLE

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

NOTES

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

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

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

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

4.28.2. Function Type Resources

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

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

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

SYNTAX

myWidget.removeNode (nodeSTRorBLOB);

IMPLEMENTATION INFO

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

Inherited from Uize.Class.

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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);

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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 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

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

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

NOTES

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

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

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

IMPLEMENTATION INFO

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

myWidget.set ({html:myWidgetHtmlGeneratorFunction});

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

5.11.2. HTML Generator Input

NOTES

IMPLEMENTATION INFO

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

NOTES

IMPLEMENTATION INFO

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

NOTES

IMPLEMENTATION INFO

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

NOTES

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

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

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

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

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

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

6.15.2. The propertiesOBJ Parameter

6.15.3. Special Meaning of idPrefix

6.15.4. Child Widget Naming

6.15.5. An Example

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

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

IMPLEMENTATION INFO