This document provides an overview of the comprehensive feature set of the UIZE JavaScript Framework, with examples and links to further explainers.

The UIZE JavaScript Framework implements a system for class inheritance that makes subclassing and object-oriented programming possible in JavaScript.

Subclassing is very easy in the UIZE JavaScript Framework. Creating a fresh subclass is as simple as the following statement...

var MySubclass = MySuperclass.subclass ();

Once you have a subclass, you can modify it by assigning values on its prototype object, adding static methods or properties to the subclass, and registering state properties or overriding the initial values of inherited state properties. Each class that you create using the framework inherits the subclass static method, so you can easily make further subclasses of them.

The Uize.Class base class provides a mechanism for inheriting instance methods and properties assigned on a superclass' prototype, state properties registered on the superclass using the registerProperties static method, and static methods and properties assigned on the superclass. The inheritance system that is implemented in the Uize.Class base class overcomes some of the weaknesses of a superficial prototype-based approach to inheritance. As part of the foundation for developing Uize.Class subclasses, the Uize.Class base class also provides its subclasses with a state interface and an event infrastructure.

For a more in-depth discussion on class inheritance, consult the explainer JavaScript Inheritance.

The UIZE JavaScript framework implements systems to facilitate modular programming, such as dependency resolution, dynamic module loading, and more.

Modules of functionality are divided up into JavaScript modules, each of which is declared by calling the Uize.module static method. This method allows the programmer to declare the name of the module, dependencies for the module, an optional superclass for class modules, and a builder function that is to be executed once all declared dependencies are resolved. The framework implements a system for dynamically loading required modules and resolving all of a module's dependencies before building the module.

The following example illustrates an outline of a widget class module declaration, where the module name is in a different namespace from the superclass.

EXAMPLE

Uize.module ({
  name:'MyNamespace.MyWidgetClass',
  superclass:'Uize.Widget',
  required:['Uize.Node','Uize.Color'],
  builder:function (_superclass) {
    // code here to build subclass module and return a reference to it
  }
});

In the above example, the package modules Uize.Node and Uize.Color (explicit dependencies) and the namespace module MyNamespace and class module Uize.Widget (implicit dependencies) must be loaded and built before the MyNamespace.MyWidgetClass module can be built. The properties of a module declaration make it possible to implement a number of different types of modules, including subclass modules, package modules, extension modules, anonymous modules, namespace modules, and alias modules.

For a more in-depth discussion of modules, see the explainer JavaScript Modules.

The UIZE JavaScript Framework implements a system to facilitate a state-oriented approach to software design.

The state interface is provided in the form of the state properties system, where state is changed by means of the generic set instance and static methods, and state is queried by means of the generic get instance and static methods. While methods exist in many classes to modify state, an emphasis is placed on using the state properties system as the primary means for modifying state of instances. The framework encourages creating interfaces using state properties combined with internal change handlers that respond to changes in state, rather than by creating methods for effecting changes in internal state.

Features of the state properties system allow for registering properties, defining conformer functions to ensure values are conformed during setting in order to be kept valid, defining change handler functions to respond to changes in values, and registering listeners on the change events that are fired when values change.

EXAMPLE

var MyClass = Uize.Class.subclass ();

function _updateArea () {this.set ({area:this._width * this._height})}
function _preventNegatives (_value) {return _value > 0 ? _value : 0}

MyClass.registerProperties ({
  _area:'area',
  _height:{
    name:'height',
    value:10,
    conformer:_preventNegatives,
    onChange:_updateArea
  },
  _width:{
    name:'width',
    value:10,
    conformer:_preventNegatives,
    onChange:_updateArea
  }
});

var myClassInstance1 = new MyClass;
alert (myClassInstance1.get ('area'); // alerts 100 (width and height are defaulted to 10)

var myClassInstance2 = new MyClass ({width:100,height:-50});
alert (myClassInstance2.get ('area'); // alerts 0 (negative height is conformed to 0)

var myClassInstance3 = new MyClass ({width:5,height:5});
alert (myClassInstance3.get ('area'); // alerts 25 (explicit values set in constructor)

var myClassInstance4 = new MyClass ({width:5});
myClassInstance4.set ({height:5});
alert (myClassInstance4.get ('area'); // alerts 25 (width set in constructor, height after)

In the above example, a subclass called MyClass is created. The registerProperties static method is called on this class to register the three state properties area, height, and width. A conformer is defined for both the height and width properties that ensures that values cannot be set below zero. Moreover, a change handler is registered for both height and width that updates the value of the area property to be the product of the two. A few different instances of MyClass are created, illustrating how the state properties mechanism behaves under different conditions.

For a more in-depth discussion on state properties, consult the explainer State Properties.

The JavaScript language does not provide a built-in system for event-driven programming, so the UIZE JavaScript Framework provides an event system.

Such events can be dispatched (or "fired") from anywhere in the code in an ad hoc fashion, and listenable events do not need to be registered formally. Multiple handlers can be registered for the same event. Handlers can be registered for events that are never fired, without ill effects. Conversely, events can be dispatched that are never listened for, without ill effects.

EXAMPLE

var myWidget = Uize.Widget ();
myWidget.wire (
  'My Arbitrary Event',
  function (event) {alert (event.message)}
);
myWidget.fire ({name:'My Arbitrary Event',message:'Hello, world!'});

In the above example, an instance of the Uize.Widget class is created, a handler is registered on an arbitrarily named event ('My Arbitrary Event'), and then the fire instance method is called on the widget in order to fire that event. The event object contains an additional message property, whose value is alerted in the handler that was registered for the event.

The event system implemented by the UIZE JavaScript Framework is orthogonal to the event model of Web browsers that is provided as part of the standardized Document Object Model, and can be used outside of the context of Web browsers and other host environments for the JavaScript language that may implement their own proprietary event systems. As an example of this, the framework's event system can be utilized within Windows Script Host by scripts that use the Uize.Class base class.

The Uize.Class base class provides a convenient infrastructure for supporting both static and instance events. Events can conveniently be fired for a class or an instance of a class, and methods are provided to every class that subclasses the Uize.Class base class to allow code to manage the registering and unregistering of event handlers for static and instance events. This provides all Uize.Class subclasses with a consistent event model.

For a more in-depth discussion on events, consult the explainer JavaScript Event System.

The UIZE JavaScript Framework provides features to enable Web applications to more easily perform asynchronous communication with a Web server, a technique that is often referred to broadly as Ajax.

The Uize.Comm base class provides a foundation for supporting asynchronous communication regardless of the mechanism employed, which could be a hidden iframe, the XMLHttpRequest object, or script tags (see AJAST). This base class provides a caching mechanism for requests, a queueing mechanism in order to sequence successive asynchronous requests through a single communication object, and a standard interface for issuing requests. Various subclasses of the Uize.Comm base class implement support for different communication mechanisms.

EXAMPLE

Uize.Comm.Ajax ().request ({
  url:[
    '/service/search',
    {
      productFilter:'movies',
      genre:'comedy',
      sort:'popular',
      results:100
    }
  ],
  returnType:'json',
  callback:function (searchResults) {
    // do something with the search results
  }
});

In the above example, an instance of the Uize.Comm.Ajax class is created and immediately used to perform an asynchronous request to a hypothetical search service using the XMLHttpRequest object. The anonymous function specified for the callback property is executed once the request has successfully executed, and the result from the server is passed as a parameter to the callback function as a JSON object.

For a more in-depth discussion of AJAX programming, consult the reference for the Uize.Comm base class.

While a design goal of the UIZE JavaScript Framework is to support multiple different host environments that support the JavaScript language, a key application of the framework is to facilitate the development of Rich Internet Applications that run with a web browser as the host environment for client-side functionality.

As such, there exist a number of modules designed specifically to assist with inspection of and manipulation of a Web page's Document Object Model. Among other things, these modules provide static methods for: iterating across a range HTML elements and performing operations on each, finding a set of HTML elements by means of a match expression, getting and setting Cascading Style Sheet (CSS) style properties, insertion of HTML markup, management of DOM event listeners, and querying and modifying coordinates.

EXAMPLE

Uize.Node.setStyle (
  ['myNode1','myNode2','myNode3'],
  {
    width:'100px',
    height:'20px',
    backgroundColor:'#000',
    fontFamily:'Times'
  }
);

The above example demonstrates how the Uize.Node.setStyle static method of the Uize.Node module is used to set the width, height, backgroundColor, and fontFamily CSS style properties for the three nodes with the ids "myNode1", "myNode2", and "myNode3".

For a more in-depth discussion of DOM manipulation, consult the reference for the Uize.Node module.

A number of compatibility issues arise when developing applications that must run on a variety of different Web browsers.

The UIZE JavaScript Framework implements some abstractions to help with cross-browser development, such as abstracting the differences between how DOM events are implemented, or how opacity is supported in CSS. Most of these abstractions are implemented in the Uize.Node module.

EXAMPLE

Uize.Node.wire ('myNode','click',function () {alert ('You clicked me')});

The above example shows how the Uize.Node.wire static method of the Uize.Node module is used to wire a handler function to the click event of a DOM node with the id "myNode". The Uize.Node.wire method abstracts differences between the event systems of different browsers so that application developers don't need to conditionalize their code.

The UIZE JavaScript Framework provides a system to facilitate the development of behavioral logic for widgets that can be embedded in HTML pages.

Functionality that can be inherited by widget classes is implemented in the Uize.Widget base class. The framework's widget system allows widgets to be arranged in a hierarchical tree structure, where each widget can have one parent widget and any number of child widgets. In this relationship, parent widgets can provide services to child widgets on their tree, and child widgets can inherit state from widgets higher up in the parent chain.

Examples of widgets include: buttons, sliders for selecting continuous values, progress bars, calendar / date pickers, color pickers, sortable collections, tabbed interfaces, modal dialogs, slide shows, data table sorters, tree list controls, and hierarchical menus.

For a more in-depth discussion of UIZE's widget framework, consult the explainer JavaScript Widgets.

The UIZE JavaScript Framework offers its fair share of features that can be "stitched on" to a page's markup, without the page's knowledge or deliberate consent.

In the world of Web application development, there is a legitimate place for features that are implemented through the technique of progressive enhancement (sometimes referred to as unobtrusive JavaScript, or graceful degradation). Making tables sortable is a great example of how one can "stitch on" an enhanced user experience, without requiring much cooperation from the application development side of things. Other examples of progressive enhancement features provided in the framework are the lightweight image preview user interaction provided by the Uize.Widget.ThumbZoom widget class, and the ability of the Uize.Widget.Tree.Menu widget (and other subclasses of the Uize.Widget.Tree base class) to extract a hierarchical tree data structure from nested lists.

The UIZE JavaScript Framework provides facilities (in Uize.Widget) to ease i18n (internationalization) and L10n (localization) of JavaScript code.

The localized state property allows an arbitrary number of localized string templates to be specified in an object hash, and these string templates are then available to the widget and all its child widgets. The localize instance method allows a string template to be retrieved and will process the string, as necessary, to replace substitution tokens with dynamic data.

EXAMPLE

myWidget = Uize.Widget ({
  localized:{welcomeMessage:'Welcome, {firstName} of {state}, {country}'}
});
alert (
  myWidget.localize (
    'welcomeMessage',
    {firstName:'Chris',state:'California',country:'USA'}
  )
);

In the above example, an instance of the Uize.Widget class is created, specifying a localized hash that contains just one localized string template named welcomeMessage. This string contains the substitution tokens {firstName}, {state}, and {country}. The localize instance method is called on the widget instance, with parameters specifying the name of the localized string to retrieve and dynamic data that should be substituted into its tokens. The result is then displayed to the user with the alert statement. Typically, localization will occur inside the implementation for a widget class, so this example is purely for illustrating the syntax.

TIP: To aid in internationalizing legacy code, a script is provided that can be run in Windows Script Host and that will recurse through the folders of a Web site project in order to compile a report of all the string literals contained inside JavaScript files, using a heuristic algorithm to bucket them according to their likelihood of being internationalizable strings (see JavaScript Build Scripts).

For a more in-depth discussion of internationalization and localization, consult the explainer JavaScript Localization.

The UIZE JavaScript Framework implements a system for templating that allows the JavaScript language to be leveraged within templates, such templates being referred to as JavaScript templates.

This system allows for the use of programmatic logic and JavaScript control structures within a template for the purpose of rendering a result document. The template engine is implemented in the Uize.Template module, which provides a means for compiling a source template into a more performant JavaScript function. Once compiled into JavaScript functions, JavaScript templates can be used to generate text output for a variety of purposes, including, for example, the generation of HTML markup for widgets, the generation of complete HTML documents as part of a Web project build process, and the generation of RSS documents from a data source.

EXAMPLE

var helloWorldTemplate = Uize.Template.compile (
  '<% for (var i = 0; i < input.repeats; i++) { %>' +
  '<p><% .message %></p>\n' +
  '<% } %>'
);

var myTemplateOutput = helloWorldTemplate ({repeats:5,message:'Hello World !'});

/* myTemplateOutput will now have the value...

<p>Hello World !</p>
<p>Hello World !</p>
<p>Hello World !</p>
<p>Hello World !</p>
<p>Hello World !</p>

*/

In the above example, a JavaScript template in a string literal is being compiled to a JavaScript function, and then that function is being called with input data that is supplied to the template function. The result is assigned to a variable.

In practice, JavaScript templates are contained inside separate files with the extension .jst in order that the template source not be subject to a further level of escaping within JavaScript string literals. JavaScript template files can be compiled into JavaScript modules with the use of JavaScript build scripts, and such modules can then be required as dependencies and treated as regular JavaScript modules. Alternatively, JavaScript template source can be embedded in non-visible elements of a Web page, such as a hidden textarea tag or a script tag with a mime type of text/jst, and then retrieved and compiled by client code when the document loads.

For a more in-depth discussion, consult the explainer JavaScript Templates.

The UIZE JavaScript Framework provides powerful features to support slick animation effects, with easing, bounce, elasticity, pulsing, and much more.

Effects and animation in the UIZE JavaScript Framework are achieved through use of a suite of associated modules. The Uize.Fade module provides the underpinnings of time-based animation and compound value interpolation, the Uize.Fade.xFactory extension module extends the Uize.Fade class with factory methods for creating, starting, and managing fades in a fade pool, and the Uize.Fx module provides static methods for initiating fades of CSS style properties.

EXAMPLE

// fade from thin border/thick padding to thick border/thin padding over 1/4 second
Uize.Fx.fadeStyle ('myNode',{borderWidth:1,padding:20},{borderWidth:20,padding:1},250);

// fade from current colors to white text on black background over two seconds
Uize.Fx.fadeStyle ('myNode',null,{color:'#fff',backgroundColor:'#000'},2000);

// fade font size from 30px back to current size over a half second
Uize.Fx.fadeStyle ('myNode',{fontSize:30},null,500);

To add some pizazz to animations, the UIZE JavaScript Framework provides the Uize.Curve, Uize.Curve.Mod, and Uize.Curve.Rubber modules that let you stray from the bland world of linear animations and into an exotic world of animations driven by arbitrary curve functions, with built-in support for easing curves as well as curves that emulate the complex properties of motion, letting you achieve effects like bounce, springiness, wobble, elasticity, etc. Beyond the built-ins, you have the freedom to roll your own curve functions in order to achieve some of the craziest motion effects you could imagine.

For a more in-depth discussion, consult the explainer JavaScript Animation and Effects.

The UIZE JavaScript Framework implements a system for building HTML from documentation that is written in a Wikitext like format called Simple Doc.

Document structure in this format is controlled through indentation, much like program structure can be governed by indentation in the Python programming language. A documentation builder script is provided that can run in Windows Script Host. This build script can recurse through all the folders of a Web site project, building HTML files from all Simple Doc files it finds, and extracting Simple Doc formatted documentation from specially flagged comments inside JavaScript module files and synthesizing these Simple Doc fragments together into Simple Doc documents for conversion into HTML documentation files.

The following example shows the documentation for the to instance method of the Uize.Color module. Notice how the documentation comment is indicated with the question mark immediately following the comment begin characters /*.

EXAMPLE

/*?
  Instance Methods
    to
      Returns the current color of the instance, encoded to the specified format.

      SYNTAX
      .........................................
      encodedColor = colorOBJ.to (encodingSTR);
      .........................................

      The =encodingSTR= parameter supports a wide variety of different `Color Encodings`.

      EXAMPLES
      .............................................................................
      var fuchsia = Uize.Color ('fuchsia');
      fuchsia.to ('color');       // produces a new Uize.Color object
      fuchsia.to ('hex');         // produces 'ff00ff'
      fuchsia.to ('#hex');        // produces '#ff00ff'
      fuchsia.to ('name');        // produces 'fuchsia'
      fuchsia.to ('RGB array');   // produces [255,0,255]
      fuchsia.to ('RGB int');     // produces 16711935
      fuchsia.to ('RGB object');  // produces {red:255,green:0,blue:255}
      fuchsia.to ('RGB string');  // produces 'rgb(255,0,255)'
      fuchsia.to ('HSL array');   // produces [300,100,50]
      fuchsia.to ('HSL object');  // produces {hue:300,saturation:100,lightness:50}
      fuchsia.to ('HSL string');  // produces 'hsl(300,100,50)'
      .............................................................................

      NOTES
      - see the related =Uize.Color.to= static method
*/

For a more in-depth discussion of this documentation system, consult the explainer JavaScript Documentation System.

The UIZE JavaScript Framework provides a system for scrunching (minifying) JavaScript code - primarily to reduce its size, but also to obfuscate it.

While the network bandwidth that is used to transfer JavaScript code to the client can be reduced in order to reduce transfer time through the use of HTTP compression methods such as gzip, further code size reduction as well as a degree of code obfuscation can be achieved with the use of the Scruncher, a code minification utility that is provided as part of the UIZE JavaScript Framework. This utility can be accessed for individual use through a Web page interface, but can be more conveniently utilized as part of a build script that recurses through the folders of a Web site project and generates compressed and obfuscated code from all the JavaScript files it encounters.

Among the operations that are performed by the Scruncher are:

Obfuscation that is provided by the Scruncher is an artifact of the code compression process, and the Scruncher is not designed to provide robust obfuscation.

The two examples below show first an extract of JavaScript code, and second the compressed and obfuscated form of that code. Notice how, in the compressed version of the code, private identifiers that were prefixed with an underscore in the source code have been reduced down to enumerated forms (eg. _a, _b, _c). For the sake of readability in this example, the LineCompacting setting is turned off for the compressed code.

SOURCE CODE

/*ScruncherSettings Mappings="=" LineCompacting="FALSE"*/

_package.toAbsolute = function (_baseUrl,_url) {
  if (_package.from (_url).fullDomain) return _url;
    // return early with URL to resolve against base, if URL is absolute

  var _result = _baseUrl.slice (0,_baseUrl.search (/[\/\\][^\/\\]*$/) + 1);
    // remove everything after the last slash, but keep the last slash
  while (_url) {
    var
      _slashPos = (_url.search (/[\/\\]/) + 1 || _url.length + 1) - 1,
      _folderName = _url.slice (0,_slashPos)
    ;
    _result = _folderName == '..'
      ? _result.slice (0,_result.search (/[\/\\][^\/\\]*[\/\\]$/) + 1) // remove end folder
      : _result + _folderName + _url.charAt (_slashPos)
    ;
    _url = _url.slice (_slashPos + 1);
  }
  return _result;
};

SCRUNCHED CODE

_a.toAbsolute=function(_b,_c){
if(_a.from(_c).fullDomain)return _c;
var _d=_b.slice(0,_b.search(/[\/\\][^\/\\]*$/)+1);
while(_c){
var
 _e=(_c.search(/[\/\\]/)+1||_c.length+1)-1,
_f=_c.slice(0,_e)
;
_d=_f=='..'
?_d.slice(0,_d.search(/[\/\\][^\/\\]*[\/\\]$/)+1)
:_d+_f+_c.charAt(_e)
;
_c=_c.slice(_e+1);
}
return _d;};

For a more in-depth discussion of the Scruncher code compression system, consult the explainer All About Scrunching.

The UIZE JavaScript Framework provides a system for developing build scripts that can be run by Windows Scripting Host, for automating build tasks.

Several build scripts are included with the framework, performing such tasks as:

For a more in-depth discussion of the build script system, consult the explainer JavaScript Build Scripts.

17.1. Working with JSON

17.2. Working with Strings

alert (
  Uize.String.repeat ('-',70) + '\n' +
  Uize.String.repeat ('Hello, world! ',5) + '\n' +
  Uize.String.repeat ('=',70)
);

----------------------------------------------------------------------
Hello, world! Hello, world! Hello, world! Hello, world! Hello, world!
======================================================================

17.3. Working with URLs

17.4. Working with Dates

17.5. Working with Colors

Uize.Fx.fadeStyle (
  'myNodeId',
  {borderColor:'cornflowerblue',backgroundColor:[255,255,0]},
  {borderColor:Uize.Color.random (),backgroundColor:'hsv(300,100%,100%)'}
);

17.6. Working with Data Structures