Recurses through the arbitrarily complex object specified, calling the specified method on all values that are instances of Uize subclasses, or that are objects that have a property whose name matches the method name specified and whose value is a function.

This sounds like a mouthfull, but in a nutshell it allows the following kinds of things...

SYNTAX

Uize.callOn (objectSetARRAYorOBJ,methodSTRorFN);

EXAMPLE

function myPhantomMethod () {
  // do stuff
}

Uize.callOn (
  [instance1,instance2,instance3,instance4,instance5,instance6],myPhantomMethod
);

The above statement would be equivalent to...

function myPhantomMethod () {
  // do stuff
}

myPhantomMethod.call (instance1);
myPhantomMethod.call (instance2);
myPhantomMethod.call (instance3);
myPhantomMethod.call (instance4);
myPhantomMethod.call (instance5);
myPhantomMethod.call (instance6);

This method is most compelling when an object or array contains a dynamic set of instances on which a specific method needs to be called, or on which a specified function needs to be called as a method.

VARIATION 1

Uize.callOn (objectSetARRAYorOBJ,methodSTRorFN,argumentsARRAY);

When the optional argumentsARRAY parameter is specified, this set of arguments will be passed when calling the specified method on each of the objects in the set.

EXAMPLE

Uize.callOn (
  [instance1,instance2,instance3,instance4,instance5,instance6],'set',[{enabled:false}]
);

The above statement would be equivalent to...

instance1.set ({enabled:false});
instance2.set ({enabled:false});
instance3.set ({enabled:false});
instance4.set ({enabled:false});
instance5.set ({enabled:false});
instance6.set ({enabled:false});

VARIATION 2

Uize.callOn (instanceOBJ,methodSTRorFN);

When the instanceOBJ parameter is specified in place of the objectSetARRAYorOBJ parameter, and when the value of the instanceOBJ parameter is an instance of a Uize subclass, then the specified method will be called on that instance. If the value of instanceOBJ is null or undefined, then no action will be taken. This is a convenient way to conditionally call a method on an object reference that may be null, when you might otherwise capture a local variable in order to avoid deep dereferencing twice.

INSTEAD OF...

if (page.children.possiblyNonExistentChildWidget) {
  page.children.possiblyNonExistentChildWidget.insertUi ();
}

OR...

var childWidget = page.children.possiblyNonExistentChildWidget;
if (childWidget) childWidget.insertUi ();

USE...

Uize.callOn (page.children.possiblyNonExistentChildWidget,'insertUi');

Returns a string, that is the specified source string with its first letter capitalized.

SYNTAX

firstCharCapitalizedSTR = Uize.capFirstChar (sourceSTR);

Using this method on the value 'width' would produce the result 'Width'. This method is useful when concatenating one string to another, and where it is desirable for the new concatenated string to be camelCase. Consider the following example...

EXAMPLE

_classPrototype.displayPropertyValue = function (_propertyName) {
  this.setNodeValue (
    'valueOf' + _class.capFirstChar (_propertyName),
    this.get (_propertyName)
  );
};

In the above example, the instance method displayPropertyValue is being defined for a hypothetical widget class. This method accepts a string parameter, being the name of a set-get property whose value should be displayed in the page in an implied node of the widget, and where the implied node's name is constructed from the prefix 'valueOf' and the name of the set-get property with its first letter capitalized. Using this method to display the value of a width set-get property, the value of this property would be displayed in the implied node named valueOfWidth.

NOTES

Returns an identical clone of the specified source object.

SYNTAX

clonedObjectOBJ = Uize.clone (objectToCloneOJ);

An object that is cloned from a source object using this method will not be conjoined to the source object.

Spawning an exact copy of an object is not as simple as copying that object's properties over to a new object. That simple approach works fine if the source object is simple and only contains properties with simple string or number types. But, if the source object contains properties that are references to other objects, then the simple approach will give rise to a clone that is not 100% discrete from its source. So, subsequent manipulations within the depths of the clone's structure may be reflected in the source object. The Uize.clone method makes sure to recurse the structure of the source object and create identical new data objects within the clone that match those in the source.

The Uize.clone method supports cloning values of the following types...

When you clone a value that is an instance of the String, Boolean, or Number objects, you get a new instance having the same value as the source - not a simple type of that value. For example, in JavaScript, 5 is not the same as new Number (5). So, when you use Uize.clone to clone new Number (5), you get a new Number instance with the value 5.

NOTES

Returns a number, being the result of constraining the specified number within the specified lower and upper limits.

SYNTAX

constrainedValueNUM = Uize.constrain (valueNUM,lowerLimitNUM,upperLimitNUM);

It is acceptable for the value of the lowerLimitNUM parameter to be greater than the value of the upperLimitNUM parameter, and the value of the valueNUM parameter will still be constrained within the specified range - even if the lower and upper limits are swapped. So, for example, the statement Uize.constrain (percent,0,100) would be equivalent to Uize.constrain (percent,100,0).

TIP

While there is no dedicated method to test whether a number falls within a given range, you can accomplish that pretty easily using the Uize.constrain method, by testing whether or not the constrained value is the same as the original, as in...

if (valueToTest != Uize.constrain (valueToTest,lowerLimit,upperLimit)) {
  // handle case of valueToTest being outside of valid range
}

Lets you copy properties into a target object from a source object.

SYNTAX

referenceToTargetOBJ = MyClass.copyInto (targetOBJ,sourceOBJ);

After the property values from sourceOBJ have been copied into targetOBJ, a reference to targetOBJ is returned as the result of the method. This behavior is provided as a convenience, so that this method can be used in larger expressions where the copy is done in place and then the modified target object can be used further (similar in spirit to the in-place increment operator).

EXAMPLE

var
  targetObject = {
    foo:'How unoriginal!'
  },
  sourceObject = {
    bar:'Indeed!'
  }
;

MyClass.copyInto (targetObject,sourceObject);

In the above example, after the code has been executed, targetObject will have both foo and bar properties while sourceObject will remain unchanged.

Of course, the JavaScript language allows in-place creation of anonymous objects using what's termed the "literal syntax", so you could also add properties to an object as shown in the example below...

var targetObject = {
  foo:'How unoriginal!'
};

MyClass.copyInto (targetObject,{bar:'Indeed!'});

VARIATION

referenceToTargetOBJ = MyClass.copyInto (targetOBJ,source1OBJ,source2OBJ,...);

The Uize.copyInto static method accepts an arbitrary number of parameters, so you can conveniently copy more than one source object into the target object.

All parameters after the targetOBJ parameter that are objects will have their properties copied into the target object, in the order in which those parameters appear in the arguments list (ie. left to right), so properties from source objects earlier in the list will be overwritten by values for those same properties from source objects later in the list.

EXAMPLE

var
  targetObject = {},
  sourceObject1 = {foo:'bar',hi:1},
  sourceObject2 = {bye:1,foo:'BAR'}
;
Uize.copyInto (targetObject,sourceObject1,sourceObject2);

In the above example, the targetObject variable will be an object with the contents {foo:'BAR',hi:1,bye:1}.

NOTES

Returns the first record in the specified records array whose contents is a superset of the contents of the specified match object. If no matching record can be found, then this method will return the value null.

SYNTAX

recordOBJ = Uize.findRecord (recordsARRAY,matchOBJ);

This method uses the Uize.findRecordNo static method in its implementation, so consult the reference for that method for further details and for an example.

NOTES

Returns an integer, indicating the index in the specified records array of the first record whose contents is a superset of the contents of the specified match object. If no matching record can be found, then this method will return the value -1.

SYNTAX

recordNoINT = Uize.findRecordNo (recordsARRAY,matchOBJ);

EXAMPLE

var
  fruits = [
    {
      type:'Apple',
      variety:'Braeburn',
      color:'red'
    },
    {
      type:'Orange',
      variety:'Navel',
      color:'orange'
    },
    {
      type:'Apple',
      variety:'Granny Smith',
      color:'green'
    },
    {
      type:'Apple',
      variety:'Red Delicious',
      color:'red'
    }
  ],
  greenAppleRecordNo = Uize.findRecordNo (fruits,{type:'Apple',variety:'Granny Smith'})
;

In the above example, the variable greenAppleRecordNo will have the value 2.

NOTES

Lets you fire a static event for the class.

SYNTAX

eventOBJ = MyClass.fire (eventNameSTR);

VARIATION

MyClass.fire (eventOBJ);

When an object is specified instead of a string value, then extra event properties can be bundled with the event and will then be available to all handlers that are executed. When using this form, the eventOBJ object must have a name property that specifies the name of the event being fired.

NOTES

Lets you query the initial value for one of the class's set-get properties.

SYNTAX

propertyValueANYTYPE = Uize.get (propertyNameSTR);

VARIATIONS

propertyValuesOBJ = Uize.get (propertyNamesARRAY);

When a propertyNamesARRAY parameter is specified in place of the propertyNameSTR parameter, the values for the class set-get properties specified in the array will be populated into an object and returned. So, for example Uize.Widget.get (['enabled','busy','built']) would return a result like {enabled:'inherit',busy:'inherit',built:true}.

allPropertyValuesOBJ = Uize.get ();

When no parameter is specified, the Uize.get static method will return an object containing values for all the registered set-get properties of the class.

NOTES

Returns a string value, being an ID that is globally unique in the current window context.

When an instance of a Uize subclass is created, its instanceId instance property is set to a value returned by this method. This method may also be useful in the implementations of subclasses, in situations where it is necessary to stash something in a context shared by different modules of code that need to be able to interoperate without conflicts.

Returns a string, representing the relative path from the current document to the folder containing the specified JavaScript library.

SYNTAX

pathToLibrarySTR = MyClass.getPathToLibrary (libraryFilenameSTR);

Whereas the Uize.pathToResources static property specifies the relative path to the folder containing the "Uize.js" JavaScript library, this method can be used to find the relative path to a different JavaScript library that is being sourced into the document. This can be useful when the JavaScript library implementing a Uize subclass does not reside in the same folder alongside the "Uize.js" file.

This method is useful in the implementation of Uize subclasses that may wish to, in their implementation, make use of image and other support resources located inside the folder that contains the class's JavaScript library. By using this method, a subclass's implementation does not need to know whether or not the document using it is being loaded through HTTP or from the local file system and does not need to impose extra requirements on developers regarding where its JavaScript library is located in relation to documents using it.

NOTES

A method that lets you eval code in the global scope.

SYNTAX

evalResultANYTYPE = Uize.globalEval (codeToEvalSTR);

A risk with careless use of JavaScript's eval function from deep within the nested functions of your code is that you may not be intending to have the code evaluated within the scope of your deep function.

It could be a benefit to the code you're eval'ing that it has access to the scope of the function in which you're eval'ing it. It may also be a curse in two respects: 1) the code being eval'ed may unexpectedly conflict with identifiers in your function's scope, and 2) function closures within the code being eval'ed will hang on to your function's scope state (with "interesting" memory usage implications).

The Uize.globalEval method lets you guarantee that code you wish to be eval'ed in the global scope is eval'ed in the global scope.

Returns an integer, indicating the index in the specified array of the first occurrence of the specified value. If the value is not found in the array, then this method will return the value -1.

SYNTAX

indexINT = Uize.indexIn (sourceARRAY,valueANYTYPE);

VARIATION

indexINT = Uize.indexIn (sourceARRAY,valueANYTYPE,fromEndBOOL);

By default, this method searches for the specified value by scanning forwards through the array from the beginning. When the value true is specified for the optional fromEndBOOL parameter, then this method will search for the specified value by scanning backwards through the array from the end.

EXAMPLE

Uize.indexIn (['foo','bar','foo','bar','foo','bar'],'bar');       // returns 1
Uize.indexIn (['foo','bar','foo','bar','foo','bar'],'bar',true);  // returns 5

VARIATION

indexINT = Uize.indexIn (sourceARRAY,valueANYTYPE,fromEndBOOL,strictEqualityBOOL);

By default, this method tests for a match using strict equality. When the value false is specified for the optional strictEqualityBOOL parameter, then this method will test for a match using loose equality (ie. where the string value '1' would be considered equal to the number value 1).

EXAMPLE

Uize.indexIn ([0,1,2,3,4,5],'3');              // returns -1
Uize.indexIn ([0,1,2,3,4,5],'3',false,false);  // returns 3

NOTES

Returns a boolean, indicating whether or not the specified value is an instance of the JavaScript Array class.

SYNTAX

isArrayBOOL = Uize.isArray (possibleArrayANYTYPE);

This method is a useful abstraction to deal with the fact that the instanceof Array test fails on arrays that are passed across frames/windows. The method returns true if the instanceof Array test passes, or if the specified value is an object and has a property named splice that is a function (the splice method is unique to arrays and its name is unique enough that the likelihood of an object having this property and it being a function is quite low).

NOTES

Returns a boolean, indicating whether or not the specified value can be found within the specified array.

SYNTAX

isInBOOL = Uize.isIn (sourceARRAY,valueANYTYPE);

VARIATION

isInBOOL = Uize.isIn (sourceARRAY,valueANYTYPE,strictEqualityBOOL);

By default, this method tests for a match using strict equality. When the value false is specified for the optional strictEqualityBOOL parameter, then this method will test for a match using loose equality (ie. where the string value '1' would be considered equal to the number value 1).

EXAMPLE

Uize.isIn ([0,1,2,3,4,5],'3');              // returns false
Uize.isIn ([0,1,2,3,4,5],'3',false,false);  // returns true

NOTES

Returns a boolean, indicating whether or not the parameter passed is a reference to an object instance or to a class.

SYNTAX

isInstanceBOOL = MyClass.isInstance (instanceOrClassOBJ);

This method can be useful when implementing methods that may be called on a class as well as on an instance of a class.

Returns a boolean, indicating whether or not the specified value is a number.

SYNTAX

isNumberBOOL = Uize.isNumber (possibleNumberANYTYPE);

This method is a useful abstraction to deal with the fact that the division of zero by zero in JavaScript yields a special kind of value know as NaN. Unfortunately, in the implementation of this special value, the result chosen for when the typeof operator is applied to it is 'number' (ie. =typeof NaN 'number' yields true). Go figure. This method checks that both the type of the parameter is 'number' and also that the parameter is not NaN.

Lets you declare a module in the UIZE JavaScript Framework.

SYNTAX

Uize.module ({
  name:moduleNameSTR,           // omit for anonymous modules
  superclass:superclassNameSTR, // omit for package modules, or if host is superclass
  required:modulesSTRorARRAY,   // omit when only host and superclass are required
  builder:builderFUNC           // omit for library modules and namespace modules
});

For an in-depth discussion of modules, consult the explainer JavaScript Modules.

NOTES

Returns an object, that is the specified key and value, paired up together in the same object.

SYNTAX

keyValueOBJ = Uize.pairUp (keySTRorNUM,valueANYTYPE);

EXAMPLE 1

Uize.pairUp ('foo','bar');  // returns the object {foo:'bar'}
Uize.pairUp (0,'zero');     // returns the object {0:'zero'}
Uize.pairUp (1,true);       // returns the object {1:true}

The Uize.pairUp method is useful when an object needs to be created from a key/value pair, where the key name is either dynamically generated in an expression or is supplied via a parameter. Using the Uize.pairUp method can collapse three statements into a single statement, as follows...

INSTEAD OF

var object = {};
object [key] = value;
doSomethingWithAnObject (object);

USE...

doSomethingWithAnObject (Uize.pairUp (key,value));

Let's consider a real world example...

EXAMPLE 2

function fadeNodeBorderColor (node,edge,startColor,endColor) {
  var styleProperty = 'border' + edge + 'Color';
  Uize.Fx.fadeStyle (
    node,
    Uize.pairUp (styleProperty,startColor),
    Uize.pairUp (styleProperty,endColor),
    1000
  );
}

In the above example, a function is being defined that will fade the border color of the specified edge of the specified node, from the specified start color to the specified end color. The value of the edge property needs to determine which style property needs to be faded. Now, we're using the Uize.Fx.fadeStyle static method of the Uize.Fx module to perform the border color animation. This method can fade values for one or more style properties, and the start and end values for the style properties are specified in style property objects. Here we need to create start and end style objects where the style property to be faded is dynamically generated using the edge parameter. As you will see from the code, the Uize.pairUp method does this for us nicely.

Returns a boolean, indicating whether or not the specified record's contents is a superset of the contents of the specified match object.

SYNTAX

isMatchBOOL = Uize.recordMatches (recordOBJ,matchOBJ);

EXAMPLE

Uize.recordMatches (
  {
    firstName:'Jack',
    lastName:'Lerchner',
    department:'engineering',
    jobTitle:'UI Engineer',
    status:'contract'
  }
  {jobTitle:'UI Engineer',status:'fulltime'}
);

In the above example, the expression would produce the result false, because the value of the status property in the matchOBJ parameter does not match the value for that property in the recordOBJ parameter.

NOTES

Lets you register properties for the class.

SYNTAX

MyClass.registerProperties (propertiesDefinitionOBJ);

The object specified in propertiesDefinitionOBJ parameter must conform to a specific structure. Each property of this object represents a property to be registered for the class, where the property name specifies the internal name to be used for the class property and the property's string value specifies the class property's public name. As an alternative to a string value, the property's value can be an object whose name property specifies the class property's public name and where an optional onChange property specifies a handler function that should be executed every time the value of the class property changes. This is all best illustrated with an example...

EXAMPLE

MyClass.registerProperties (
  {
    _propertylName:'property1Name',
    _property2Name:'property2Name',
    _property3Name:{
      name:'property3Name',
      onChange:function () {
        // code to be performed when the value of this property changes
      }
    }
  }
);

NOTES

Lets you set the initial value for one of the class's set-get properties.

SYNTAX

Uize.set (propertiesOBJ);

EXAMPLE

Uize.set (
  {
    property1Name:'property1Value',
    property2Name:'property2Value',
    property3Name:'property4Value'
  }
);

VARIATION

Uize.set (propertyNameSTR,propertyValueANYTYPE);

A variation that accepts the two parameters propertyNameSTR and propertyValueANYTYPE makes it possible to use an expression or the value of a variable for specifying the name of the property to set. There is no appreciable difference in performance between using the propertiesOBJ form and the two parameter form when setting the value for a single set-get property, so the two parameter form is primarily a convenience for setting the value for a dynamically selected property.

EXAMPLE

_class.increment = function (_propertyName,_amount) {
  this.set (_propertyName,this.get (_propertyName) + _amount);
}

In the above example, a generic incrementer static method is being implemented. It receives a _propertyName parameter that specifies the set-get property to increment, and it passes the value of this parameter as the first parameter in the call to the set method.

NOTES

Lets you subclass the Uize class or any subclass of the Uize class.

SYNTAX

MyClass = Uize.subclass (subclassConstructorFN);

Consider the following example...

EXAMPLE

MyClass = Uize.subclass (
  function () {
    this.foo = 'How unoriginal!';
  }
);

MySubclass = MyClass.subclass (
  function () {
    this.bar = this.foo + ' Indeed!';
  }
);

In the above example, MySubclass is a subclass of MyClass, which is in turn a subclass of Uize. Now, when an instance of MySubSubclass gets created, the constructor of MyClass and then the constructor of MySubSubclass will be executed in the initialization of the instance, and the instance will have both foo and bar properties, where the bar property will have a value of "How unoriginal! Indeed!".

Lets you substitute the specified set of properties into the specified string.

SYNTAX

resultSTR = MyClass.substituteInto (sourceSTR,substitutionsARRAYorOBJ);

The string specified by the sourceSTR parameter should contain token markup so that the properties of the object specified in the substitutionsARRAYorOBJ parameter can be correctly substituted into the string. For each of the properties to substitute, the string should contain a token of the form [#propertyName] (unless you use the optional tokenNamingSTR parameter for configurable token formats). Each substitution token for a property will be replaced with the property's value.

EXAMPLE 1

MyClass.substituteInto (
  '[#foo] [#bar]',
  {foo:'How unoriginal!',bar:'Indeed!'}
);

In the above example, the method will return the value 'How unoriginal! Indeed!'.

EXAMPLE 2

MyClass.substituteInto (
  'An [#fruit]. Oh, an [#fruit]!! Please, give me an [#fruit].',
  {fruit:'apple'}
);

If there are multiple tokens for the same property, then that property will be substituted multiple times. So, in the above example, the method will return the value 'An apple. Oh, an apple!! Please, give me an apple.'.

EXAMPLE 3

MyClass.substituteInto (
  'An orange. Oh, an orange!! Please, give me an orange.',
  {fruit:'apple'}
);

If there are no substitution tokens for a property, then that property will not be substituted. So, in the above example, the method will return the value 'An orange. Oh, an orange!! Please, give me an orange.'.

EXAMPLE 4

MyClass.substituteInto (
  'An [#fruit]. Oh, an [#fruit]!! Please, give me an [#fruit].',
  {vegetable:'artichoke'}
);

Substitution tokens for which there are no properties will be left in the string (they will not be blanked out). So, in the above example, the method will return the value 'An [#fruit]. Oh, an [#fruit]!! Please, give me an [#fruit].'.

EXAMPLE 5

MyClass.substituteInto (
  'This is a case of comparing [#fruit] to [#FRUIT].',
  {fruit:'apples',FRUIT:'oranges'}
);

Substitution tokens are case-sensitive. So, in the above example, the token [#fruit] is distinct from the token [#FRUIT]. Our substitution values object in this case has a value for both the fruit and FRUIT properties, and the method call will return the value 'This is a case of comparing apples to oranges.'.

VARIATION

resultSTR = MyClass.substituteInto (sourceSTR,substitutionsARRAYorOBJ,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 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 1

MyClass.substituteInto (
  'Welcome, [firstName] of [state], [country]',
  {firstName:'Chris',state:'California',country:'USA'},
  '[KEY]'
);

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

EXAMPLE 2

MyClass.substituteInto (
  'Welcome, [0] of [1], [2]',
  ['Chris','California','USA'],
  '[KEY]'
);

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

NOTES

Returns a string, providing summary info for the class on which the method is called.

SYNTAX

classSummarySTR = MyClass.toString ();

The string returned by this method provides a summary that includes the class' name and the state of its set-get properties. Among other things, this method provides a convenient and lightweight way to gather information about Uize subclasses during debugging and troubleshooting. The Uize.toString static intrinsic method is invoked automatically in certain contexts in order to convert a class reference to a string form, such as when alerting a class using the alert global function.

EXAMPLE

alert (page.children.slider.Class);

In the above example, if the page widget has a slider child widget that is an instance of the class Uize.Widget.Bar.Slider, then the output of the alert statement could look something like...

EXAMPLE OUTPUT

[class Uize.Widget.Bar.Slider]

built : true
busy : inherit
busyInherited : false
confirm : undefined
container : undefined
decimalPlacesToDisplay : undefined
enabled : inherit
enabledInherited : true
html : undefined
idPrefix : undefined
idPrefixConstruction : undefined
inDrag : false
increments : 1
inform : undefined
insertionMode: undefined
localized : undefined
maxValidValue : undefined
maxValue : 100
minValidValue : undefined
minValue : 0
name : undefined
nodeMap : undefined
orientation : vertical
parent : undefined
restTime : 250
scaleFunc : [object Function]
value : 0
valueFunc : [object Function]
wired : false

In certain contexts, providing a reference to a Uize subclass as a parameter to some method will result in the Uize.valueOf static intrinsic method of that class being invoked in order to coerce it to a simple value. If it is your desire to have the class summary be used rather than the class' value, then you should explicitly call the Uize.toString static intrinsic method, as follows...

EXAMPLE

Uize.Node.setInnerHtml ('classSummaryForDebug',page.children.slider.Class.toString ());
Uize.Node.setInnerHtml ('classCurrentValue',page.children.slider.Class);

In this example, the classSummaryForDebug node will contain the summary info for the Uize.Widget.Bar.Slider class, while the classCurrentValue node will just show the class' current value.

NOTES

Toggles the value of the specified boolean static set-get property.

SYNTAX

toggledValueBOOL = Uize.toggle (propertyNameSTR);

The Uize.toggle static method is provided purely as a convenience. The following two statements are equivalent...

Uize.toggle ('myProperty');
Uize.set ({myProperty:!Uize.get ('myProperty')});

As you can see, using the Uize.toggle method produces more concise code.

Lets you remove a handler previously wired to a static event, or handlers wired for multiple static events.

SYNTAX

MyClass.unwire (eventNameSTR,eventHandlerSTRorFNorOBJ);

VARIATION 1

MyClass.unwire (eventNameSTR);

When no eventHandlerSTRorFNorOBJ parameter is specified, then all handlers registered for the event specified in the eventNameSTR parameter will be removed.

VARIATION 2

MyClass.unwire (eventNamesToHandlersMapOBJ);

When only a single eventNamesToHandlersMapOBJ parameter is specified, then event handlers for multiple events can be specified using an object hash. This variation is provided as a convenience and has the effect of iteratively calling the Uize.unwire static method for each event-name-to-handler mapping in the eventNamesToHandlersMapOBJ object.

NOTES

Returns the value of the class' value set-get property.

SYNTAX

classValueANYTYPE = MyClass.valueOf ();

The Uize.valueOf static intrinsic method is invoked automatically in certain contexts in order to convert a class to a value, such as when using a class reference in an expression (eg. Uize.Widget.Bar.Slider + 0). This static method is implemented primarily to provide parity with the valueOf Intrinsic Method. Its behavior is largely equivalent to that of the instance method, excepting that it applies to the static value of the value set-get property.

NOTES

Lets you wire a handler for a static event of the class, or handlers for multiple static events.

SYNTAX

MyClass.wire (eventNameSTR,eventHandlerSTRorFNorOBJ);

Event handlers registered using this method will handle events fired for the class using the Uize.fire static method, and not those events fired using the fire instance method. A Uize subclass may not provide any static events, so you should consult the reference documentation for a class to learn more about its suite of events. Handlers specified by the eventHandlerSTRorFNorOBJ parameter may be of string, function, or object type.

VARIATION

MyClass.wire (eventNamesToHandlersMapOBJ);

When only a single eventNamesToHandlersMapOBJ parameter is specified, then event handlers for multiple events can be specified using an object hash. This variation is provided as a convenience and has the effect of iteratively calling the Uize.wire static method for each event-name-to-handler mapping in the eventNamesToHandlersMapOBJ object.

SPECIAL VALUES

NOTES

A reference to the class's constructor.

You can use this to interrogate an object instance to see if it is of a certain class, as illustrated in the following example...

EXAMPLE

if (myInstance.Class == Uize.Widget.Bar.Slider) {
  // do something for sliders
} else if (myInstance.Class == Uize.Widget.Tree.Menu) {
  // do something for tree menus
} else if (myInstance.Class == Uize.Widget.ImageWipe) {
  // do something for wipes
}

The above example is admittedly a little abstract. It is hard to imagine the exact scenario that may come up where some code is handed object instances where their class will not be known. But, when such a case comes up, the Class property has got your back.

An automatically generated name, that can be used as a means of identifying the specific instance in other code.

When designing JavaScript classes, it is sometimes necessary in the class's implementation to set intervals, timeouts, or the event handlers of HTML nodes that make up an instance's user interface, so that they execute methods of the instance. Sometimes this must be done by generating JavaScript code that is to be interpreted. This generated code must, therefore, be able to reference its instance using a global identifier, because the code will be executed in a global context.

If the constructor of your class uses the automatically generated value of an instance's instanceId property to assign a global reference to the instance, with a statement like window [_this.instanceId] = _this, then the instanceId property can be used when generating JavaScript code that is to execute methods on the instance. Consider the following example...

MyClass.prototype.click = function () {
  // do something when the button is clicked
};

MyClass.prototype.insertButton = function () {
  document.writeln (
    ''
  );
};

In the above example, we see a segment of the implementation for a Uize subclass named MyClass. The insertButton instance method is writing HTML into the document, and the input tag that is created has an onclick attribute that registers an event handler that will execute the click method of that instance when clicked. That's because the global identifier by the name stored in the instanceId property is a reference to the instance.

NOTES

Lets you fire an event for an instance of the class.

SYNTAX

eventOBJ = myInstance.fire (eventNameSTR);

VARIATION

eventOBJ = myInstance.fire (eventOBJ);

When an object is specified instead of a string value, then extra event properties can be bundled with the event and will then be available to all handlers that are executed. When using this form, the eventOBJ object must have a name property that specifies the name of the event being fired.

NOTES

Lets you query the value of one of an instance's set-get properties.

SYNTAX

propertyValueANYTYPE = myInstance.get (propertyNameSTR);

VARIATIONS

propertyValuesOBJ = myInstance.get (propertyNamesARRAY);

When a propertyNamesARRAY parameter is specified in place of the propertyNameSTR parameter, the values for the instance set-get properties specified in the array will be populated into an object and returned. So, for example mySlider.get (['minValue','maxValue','value']) would return a result like {minValue:0,maxValue:100,value:57}.

allPropertyValuesOBJ = myInstance.get ();

When no parameter is specified, the get instance method will return an object containing values for all the set-get properties of the instance. For one thing, this variation makes it easy to create a new instance of a class with the same state as an existing instance.

EXAMPLE

copyOfMyFade = new Uize.Fade (myFade.get ());

In this example, an instance of the class Uize.Fade is being created by passing the constructor all the set-get property values obtained from the myFade instance using the get method. The new instance created will then have the same state as the myFade instance.

NOTES

Nulls out the global variable (or property of the window object) of the name instanceId.

This method may be useful if global (or window object level) references are made to instances of a class, usually for the purpose of group management, or the implementation of certain kinds of state exclusivity amongst instances of a class. This method is also intended to be overrided by subclasses where additional destructor style code may be desired.

Lets you set one or more of an instance's set-get properties.

SYNTAX

myInstance.set (propertiesOBJ);

EXAMPLE

myInstance.set (
  {
    property1Name:'property1Value',
    property2Name:'property2Value',
    property3Name:'property4Value'
  }
);

VARIATION

myInstance.set (propertyNameSTR,propertyValueANYTYPE);

A variation that accepts the two parameters propertyNameSTR and propertyValueANYTYPE makes it possible to use an expression or the value of a variable for specifying the name of the property to set. There is no appreciable difference in performance between using the propertiesOBJ form and the two parameter form when setting the value for a single set-get property, so the two parameter form is primarily a convenience for setting the value for a dynamically selected property.

EXAMPLE

_classPrototype.increment = function (_propertyName,_amount) {
  this.set (_propertyName,this.get (_propertyName) + _amount);
}

In the above example, a generic incrementer instance method is being implemented. It receives a _propertyName parameter that specifies the set-get property to increment, and it passes the value of this parameter as the first parameter in the call to the set method.

NOTES

Returns a string, providing summary info for the instance on which the method is called.

SYNTAX

instanceSummarySTR = myInstance.toString ();

The string returned by this method provides a summary that includes the instance's class name and the state of its set-get properties. Among other things, this method provides a convenient and lightweight way to gather information about instances of Uize subclasses during debugging and troubleshooting. The toString Intrinsic Method is invoked automatically in certain contexts in order to convert an object to a string form, such as when alerting an object using the alert global function.

EXAMPLE

alert (page.children.slider);

In the above example, if the page widget has a slider child widget that is an instance of the class Uize.Widget.Bar.Slider, then the output of the alert statement could look something like...

EXAMPLE OUTPUT

[object Uize.Widget.Bar.Slider]

built : true
busy : inherit
busyInherited : false
confirm : undefined
container : undefined
decimalPlacesToDisplay : undefined
enabled : inherit
enabledInherited : true
html : undefined
idPrefix : page_slider
idPrefixConstruction : concatenated
inDrag : false
increments : 1
inform : undefined
insertionMode: undefined
localized : undefined
maxValidValue : undefined
maxValue : 200
minValidValue : undefined
minValue : 0
name : slider
nodeMap : undefined
orientation : vertical
parent : [class UizeDotCom.Page.Example]
restTime : 250
scaleFunc : [object Function]
value : 0
valueFunc : [object Function]
wired : true

In certain contexts, providing a reference to a Uize subclass instance as a parameter to some method will result in the valueOf Intrinsic Method of that instance being invoked in order to coerce it to a simple value. If it is your desire to have the instance summary be used rather than the instance's value, then you should explicitly call the toString Intrinsic Method, as follows...

EXAMPLE

Uize.Node.setInnerHtml ('sliderWidgetSummaryForDebug',page.children.slider.toString ());
Uize.Node.setInnerHtml ('sliderWidgetCurrentValue',page.children.slider);

In this example, the sliderWidgetSummaryForDebug node will contain the summary info for the instance, while the sliderWidgetCurrentValue node will just show the slider widget's current value.

NOTES

Toggles the value of the specified boolean instance set-get property.

SYNTAX

toggledValueBOOL = myInstance.toggle (propertyNameSTR);

The toggle instance method is provided purely as a convenience. The following two statements are equivalent...

myInstance.toggle ('myProperty');
myInstance.set ({myProperty:!myInstance.get ('myProperty')});

As you can see, using the toggle method produces more concise code.

Lets you remove a handler previously wired to an instance event, or handlers wired for multiple instance events.

SYNTAX

myInstance.unwire (eventNameSTR,eventHandlerSTRorFNorOBJ);

VARIATION 1

myInstance.unwire (eventNameSTR);

When no eventHandlerSTRorFNorOBJ parameter is specified, then all handlers registered for the event specified in the eventNameSTR parameter will be removed.

VARIATION 2

myInstance.unwire (eventNamesToHandlersMapOBJ);

When only a single eventNamesToHandlersMapOBJ parameter is specified, then event handlers for multiple events can be specified using an object hash. This variation is provided as a convenience and has the effect of iteratively calling the unwire instance method for each event-name-to-handler mapping in the eventNamesToHandlersMapOBJ object.

NOTES

Returns the value of the instance's value set-get property.

SYNTAX

instanceValueANYTYPE = myInstance.valueOf ();

The valueOf Intrinsic Method is invoked automatically in certain contexts in order to convert an object to a value, such as when using an object reference in an expression.

EXAMPLE

var markedUpPrice = price * (1 + page.children.markupPercentSlider / 100);

In the above example, the page widget has a slider child widget that is an instance of the class Uize.Widget.Bar.Slider and that lets the user choose a markup percentage between 0 and 100. In the above expression, the slider widget is being divided by 100. Rather than giving you a hundred really tiny slider widgets (not all that useful), JavaScript automatically invokes the valueOf Intrinsic Method. The Uize implementation of this instance method results in the slider's current value being returned so that it can then be used in the expression.

The following three statements are equivalent...

markedUpPrice = price * (1 + page.children.markupPercentSlider.get ('value') / 100);
markedUpPrice = price * (1 + page.children.markupPercentSlider.valueOf () / 100);
markedUpPrice = price * (1 + page.children.markupPercentSlider / 100);

In certain contexts, providing a reference to a Uize subclass instance as a parameter to some method will result in the toString Intrinsic Method of that instance being invoked in order to resolve it to a string value. If it is your desire to have the value used rather than the instance summary, then you should explicitly call the valueOf Intrinsic Method, as follows...

EXAMPLE

alert (page.children.markupPercentSlider.valueOf ());

In this example, the current value of the markupPercentSlider widget will be displayed in the alert dialog, rather than the instance summary. You can also use shortcuts, as follows...

COERCE TO NUMBER

alert (+page.children.markupPercentSlider);

COERCE TO STRING

alert (page.children.titleTextInputWidget + '');

Both of the above examples will cause JavaScript to invoke the valueOf Intrinsic Method rather than the toString Intrinsic Method, but the first will coerce the value to a number type, while the second will coerce the value to a string type.

NOTES

Lets you wire a handler for a specific instance event, or handlers for multiple instance events.

SYNTAX

myInstance.wire (eventNameSTR,eventHandlerSTRorFNorOBJ);

Event handlers registered using this method will handle events fired for the instance using the fire instance method, and not those events fired using the Uize.fire static method. A Uize subclass may not provide any instance events, so you should consult the reference documentation for a class to learn more about its suite of events. Handlers specified by the eventHandlerSTRorFNorOBJ parameter may be of string, function, or object type.

EXAMPLE

mySlider.wire (
  'Changed.value',
  function () {Uize.Node.setValue ('valueField',mySlider)}
);

VARIATION

myInstance.wire (eventNamesToHandlersMapOBJ);

When only a single eventNamesToHandlersMapOBJ parameter is specified, then event handlers for multiple events can be specified using an object hash. This variation is provided as a convenience and has the effect of iteratively calling the wire instance method for each event-name-to-handler mapping in the eventNamesToHandlersMapOBJ object.

EXAMPLE

mySlider.wire ({
  'Changed.value':
    function () {Uize.Node.setValue ('valueField',mySlider)},
  'Changed.maxValue':
    function () {Uize.Node.setValue ('maxValueField',mySlider.get ('maxValue'))},
  'Changed.minValue':
    function () {Uize.Node.setValue ('minValueField',mySlider.get ('minValue'))}
});

SPECIAL VALUES

NOTES

All of the instance and static methods for adding and removing event handlers allow handlers to be specified in a number of different ways.

5.1.1. Function Type Handlers

5.1.2. String Type Handlers

5.1.3. Object Type Handlers

myWidget.children.someButton.wire ('Click',myWidget);

myWidget.children.someButton.unwire ('Click',myWidget);

5.1.4. Value for Removing Must Match Value Used for Adding

An object, specifying handlers for multiple events using event-name-to-handler mappings, where the key of each property is an event name and the value of each property is an event's corresponding handler.

The contents of this object should be of the form...

{
  event1Name:event1HandlerSTRorFNorOBJ,
  event2Name:event2HandlerSTRorFNorOBJ,
  ...
  eventNName:eventNHandlerSTRorFNorOBJ
}

The value for each property in this object should conform to the eventHandlerSTRorFNorOBJ parameter type.

The Changed.* instance event is a wildcard event that is fired whenever one or more set-get properties change value as a result of a call to the set instance method.

This event will only be fired once for all set-get properties that have changed value during a call to the set method. The event object for this event will contain a properties property, which is an object indicating which set-get properties have changed value, being a mapping between the public names of set-get properties that have changed and their new values.

NOTES

The Uize base class implements a generalized mechanism for firing events when the values of set-get properties are changed.

This means that for any set-get property that is registered through the Uize.registerProperties static method, a handler can be registered for a change in the value of that property without having to write any additional code to fire an event.

6.2.1. Event Naming

6.2.2. Property Aliases

function handleColorChange () {
  // do stuff
}
myColorWidget.wire ('Changed.color',handleColorChange);
myColorWidget.unwire ('Changed.hexRgb',handleColorChange);

6.2.3. Must Use the set Method

6.2.4. Only On Change, Not Every Set

NOTES

A function, representing custom module loader code that should be invoked in order to dynamically loading JavaScript modules.

EXAMPLE

Uize.moduleLoader = function (_moduleToLoad,_callback) {
  _this._commObject.request ({
    url:[_this.get ('env').service + 'getjs',{filename:_moduleToLoad + '.js'}],
    returnType:'json',
    requestMethod:'GET',
    callback:_callback
  });
};

For an in-depth discussion of modules, consult the explainer JavaScript Modules.

NOTES

A function, that should accept a module name as a parameter and that should return a string value, being the URL path from where that module can be loaded.

This property provides you with the flexibility to have different types of modules load from different locations. A classic example would be loading modules of the UIZE JavaScript Framework from a shared CDN (Content Delivery Network) location, while loading modules that are in your own Web site's namespace from the same machine that serves the pages. Consider the following example...

EXAMPLE

Uize.moduleUrlResolver = function (_moduleName) {
  return (
    moduleName.indexOf ('MyDomain.') == 0
      ? '/js/' + _moduleName + '.js'
      : 'http://www.some-cdn.com/uize-js/' + _moduleName + '.js'
};

In the above example, a custom module URL resolver is being specified. It looks at the module name, determines if the module name is in the namespace for the Web site (MyDomain in this example), and returns a root relative URL. Otherwise, assuming that all other modules are part of the UIZE JavaScript Framework and are stored on a CDN, it returns a URL for where the module would be located on that CDN Web site.

The module URL returned by your function will be used by the built-in Uize.moduleLoader module loader function. If you override the built-in module loader by specifying your own value for the Uize.moduleLoader static property, then the value of the Uize.moduleUrlResolver property will only be applicable if your custom module loader accesses this property. Similarly, the built-in Uize.moduleUrlResolver function uses the Uize.moduleUrlTemplate static property. So, if you supply your own custom module URL resolver by setting the value of the Uize.moduleUrlResolver property, then it is your choice as to whether or not you use the value of the Uize.moduleUrlTemplate property.

For an in-depth discussion of modules, consult the explainer JavaScript Modules.

NOTES

A string, representing a template to be used when generating URLs for loading JavaScript modules dynamically.

EXAMPLE

Uize.moduleUrlTemplate = 'http://www.somedomain.com/js/[#modulePath]';

For an in-depth discussion of modules, consult the explainer JavaScript Modules.

NOTES

A string, representing the relative path from the current document to the folder containing the Uize class's JavaScript library.

This property is useful in the implementation of Uize subclasses that are to reside in the same folder alongside the Uize class's JavaScript file and that may wish to, in their implementation, make use of image and other support resources located inside that folder.

By using this property, a subclass's implementation does not need to know whether or not the document using it is being loaded through HTTP or from the local file system and does not need to impose extra requirements on developers regarding where its JavaScript library is located in relation to documents using it.

This static method has been deprecated in favor of the more versatile and more concisely named Uize.wire static method.

INSTEAD OF...

MyClass.addEventHandler (eventNameSTR,eventHandlerSTRorFN);

USE...

MyClass.wire (eventNameSTR,eventHandlerSTRorFN);

This static method has been deprecated in favor of the more versatile and more concisely named wire static method.

INSTEAD OF...

MyClass.addEventHandlers (eventNamesToHandlersMapOBJ);

USE...

MyClass.wire (eventNamesToHandlersMapOBJ);

This static method has been deprecated in favor of the more concisely named Uize.fire static method.

INSTEAD OF...

MyClass.fireEvent (eventNameSTRorOBJ);

USE...

MyClass.fire (eventNameSTRorOBJ);

This static method has been deprecated in favor of the more versatile and more concisely named Uize.unwire static method.

INSTEAD OF...

MyClass.removeEventHandler (eventNameSTR,eventHandlerSTRorFN);

USE...

MyClass.unwire (eventNameSTR,eventHandlerSTRorFN);

This static method has been deprecated in favor of the more versatile and more concisely named Uize.unwire static method.

INSTEAD OF...

MyClass.removeEventHandlers (eventNamesToHandlersMapOBJ);

USE...

MyClass.unwire (eventNamesToHandlersMapOBJ);

This instance method has been deprecated in favor of the more versatile and more concisely named wire instance method.

INSTEAD OF...

myInstance.addEventHandler (eventNameSTR,eventHandlerSTRorFN);

USE...

myInstance.wire (eventNameSTR,eventHandlerSTRorFN);

This instance method has been deprecated in favor of the more versatile and more concisely named wire instance method.

INSTEAD OF...

myInstance.addEventHandlers (eventNamesToHandlersMapOBJ);

USE...

myInstance.wire (eventNamesToHandlersMapOBJ);

This instance method has been deprecated in favor of the more concisely named fire instance method.

INSTEAD OF...

myInstance.fireEvent (eventNameSTRorOBJ);

USE...

myInstance.fire (eventNameSTRorOBJ);

This instance method has been deprecated in favor of the more versatile and more concisely named unwire instance method.

INSTEAD OF...

myInstance.removeEventHandler (eventNameSTR,eventHandlerSTRorFN);

USE...

myInstance.unwire (eventNameSTR,eventHandlerSTRorFN);

This instance method has been deprecated in favor of the more versatile and more concisely named unwire instance method.

INSTEAD OF...

myInstance.removeEventHandlers (eventNamesToHandlersMapOBJ);

USE...

myInstance.unwire (eventNamesToHandlersMapOBJ);