The Uize.Class.subclass method supports a variation that lets you create a subclass, declaring multiple features by type at the time of creating a class, by supplying just a single featuresByTypeOBJ parameter.

EXAMPLE

var MySubclass = MyClass.subclass ({
  alphastructor:function () {
    // implementation here
  },
  omegastructor:function () {
    // implementation here
  },
  staticMethods:{
    staticMethod1:function () {
      // implementation here
    },
    staticMethod2:function () {
      // implementation here
    }
  },
  instanceMethods:{
    instanceMethod1:function () {
      // implementation here
    },
    instanceMethod2:function () {
      // implementation here
    }
  },
  stateProperties:{
    stateProperty1:{
      // property profile
    },
    stateProperty2:{
      // property profile
    }
  }
});

One or more features of one or more different feature types can be declared for a class after the class has already been created, by calling the Uize.Class.declare method on the class and supplying a featuresByTypeOBJ parameter.

EXAMPLE

var MyClass = Uize.Class.subclass ();

MyClass.declare ({
  alphastructor:function () {
    // implementation here
  },
  omegastructor:function () {
    // implementation here
  },
  staticMethods:{
    staticMethod1:function () {
      // implementation here
    },
    staticMethod2:function () {
      // implementation here
    }
  },
  instanceMethods:{
    instanceMethod1:function () {
      // implementation here
    },
    instanceMethod2:function () {
      // implementation here
    }
  },
  stateProperties:{
    stateProperty1:{
      // property profile
    },
    stateProperty2:{
      // property profile
    }
  }
});

The properties of the featuresByTypeOBJ object should correspond to the names of the various feature declaration methods supported by the class being subclassed.

When features are specified, categorized by type, in the featuresByTypeOBJ parameter, the Uize.Class.declare and Uize.Class.subclass methods will iterate over the properties of the object, attempting to call a static method of the name of each property encountered, on the class being subclassed, and passing the value of the property as the first parameter of the feature declaration method.

So, for example, if the Uize.Service.subclass method is called to create a service class, and if a featuresByTypeOBJ parameter is specified, and if a serviceMethods property exists within the featuresByTypeOBJ object, then the Uize.Service.serviceMethods static method will be called and the value of the serviceMethods property from the featuresByTypeOBJ object will be passed as the single parameter to the Uize.Service.serviceMethods method.

To illustrate this by example...

THIS...

var FileSystem = Uize.Service.subclass ({
  serviceMethods:{
    readFile:{
      async:false
    },
    writeFile:{
      async:false
    },
    getFiles:{
      async:false
    },
    getFolder:{
      async:false
    },
    // etc.
    // etc.
  }
});

...IS EQUIVALENT TO...

var FileSystem = Uize.Service.subclass ();

FileSystem.serviceMethods ({
  readFile:{
    async:false
  },
  writeFile:{
    async:false
  },
  getFiles:{
    async:false
  },
  getFolder:{
    async:false
  },
  // etc.
  // etc.
});

Support for the following standard properties of the features declaration object is built into the Uize.Class base class...

Because of how the features declaration object is implemented, declaring multiple features, categorized by type, inherently supports new feature types introduced in subclasses.

In addition to the standard properties of the features declaration object, certain classes may introduce class-specific feature types for which new feature declaration static methods will be introduced. These new feature types will, by design, introduce additional properties that can be specified in the features declaration object when declaring features for subclasses of those classes. For more details, see the section Class-specific Feature Types.

Because of how the features declaration object is implemented, one can also do less conventional things along with declaring features in the Uize.Class.subclass and Uize.Class.declare methods.

For example, one can effectively call the Uize.Class.set static method to override the initial values of state properties that are inherited from the base class, as shown in the following example...

INSTEAD OF...

var MySliderWidgetSubclass = Uize.Widget.Bar.Slider.subclass ({
  instanceMethods:{
    // instance methods declared here
  },
  stateProperties:{
    // state properties declared here
  }
});

MySliderWidgetSubclass.set ({
  minValue:-50,
  maxValue:50
});

USE...

var MySliderWidgetSubclass = Uize.Widget.Bar.Slider.subclass ({
  instanceMethods:{
    // instance methods declared here
  },
  stateProperties:{
    // state properties declared here
  },
  set:{
    minValue:-50,
    maxValue:50
  }
});

The alphastructor can be declared for a class when the class is created, by using the optional featuresByTypeOBJ parameter when calling the Uize.Class.subclass static method.

The features declaration object should contain an alphastructor property whose value should be the alphastructor function.

EXAMPLE

var MyClass = Uize.Class.subclass ({
  alphastructor:function () {
    // implementation of alphastructor
  }
});

The alphastructor can be declared for a class after the class has already been created, by calling the MyClass.declare method on the class.

The features declaration object passed to the MyClass.declare method should contain an alphastructor property whose value should be the alphastructor function.

EXAMPLE

MyClass.declare ({
  alphastructor:function () {
    // implementation of alphastructor
  }
});

The alphastructor can be declared for a class after the class has already been created, by calling the MyClass.alphastructor method on the class.

When calling the MyClass.alphastructor method, it should be passed a single function parameter that is the alphastructor function.

EXAMPLE

MyClass.alphastructor (
  function () {
    // implementation of alphastructor
  }
);

The omegastructor can be declared for a class when the class is created, by using the optional featuresByTypeOBJ parameter when calling the Uize.Class.subclass static method.

The features declaration object should contain an omegastructor property whose value should be the omegastructor function.

EXAMPLE

var MyClass = Uize.Class.subclass ({
  omegastructor:function () {
    // implementation of omegastructor
  }
});

The omegastructor can be declared for a class after the class has already been created, by calling the MyClass.declare method on the class.

The features declaration object passed to the MyClass.declare method should contain an omegastructor property whose value should be the omegastructor function.

EXAMPLE

MyClass.declare ({
  omegastructor:function () {
    // implementation of omegastructor
  }
});

The omegastructor can be declared for a class after the class has already been created, by calling the MyClass.omegastructor method on the class.

When calling the MyClass.omegastructor method, it should be passed a single function parameter that is the omegastructor function.

EXAMPLE

MyClass.omegastructor (
  function () {
    // implementation of omegastructor
  }
);

Instance methods can be declared for a class when the class is created, by using the optional featuresByTypeOBJ parameter when calling the Uize.Class.subclass static method.

The features declaration object should contain an instanceMethods property whose value should be an object containing mappings of instance method names to implementation functions.

EXAMPLE

var MyClass = Uize.Class.subclass ({
  instanceMethods:{
    foo:function () {
      // implementation of foo instance method
    },
    bar:function () {
      // implementation of bar instance method
    }
  }
});

Instance methods can be declared for a class after the class has already been created, by calling the MyClass.declare method on the class.

The features declaration object passed to the MyClass.declare method should contain an instanceMethods property whose value should be an object containing mappings of instance method names to implementation functions.

EXAMPLE

MyClass.declare ({
  instanceMethods:{
    foo:function () {
      // implementation of foo instance method
    },
    bar:function () {
      // implementation of bar instance method
    }
  }
});

Instance methods can be declared for a class after the class has already been created, by calling the MyClass.instanceMethods method on the class.

When calling the MyClass.instanceMethods method, an instance methods declaration object should be provided, containing mappings of instance method names to implementation functions.

EXAMPLE

MyClass.instanceMethods ({
  foo:function () {
    // implementation of foo instance method
  },
  bar:function () {
    // implementation of bar instance method
  }
});

Instance properties can be declared for a class when the class is created, by using the optional featuresByTypeOBJ parameter when calling the Uize.Class.subclass static method.

The features declaration object should contain an instanceProperties property whose value should be an object containing mappings of instance property names to initial values.

EXAMPLE

var MyClass = Uize.Class.subclass ({
  instanceProperties:{
    foo:'bar',
    baz:'qux'
  }
});

Instance properties can be declared for a class after the class has already been created, by calling the MyClass.declare method on the class.

The features declaration object passed to the MyClass.declare method should contain an instanceProperties property whose value should be an object containing mappings of instance property names to initial values.

EXAMPLE

MyClass.declare ({
  instanceProperties:{
    foo:'bar',
    baz:'qux'
  }
});

Instance properties can be declared for a class after the class has already been created, by calling the MyClass.instanceProperties method on the class.

When calling the MyClass.instanceProperties method, an instance properties declaration object should be provided, containing mappings of instance property names to initial values.

EXAMPLE

MyClass.instanceProperties ({
  foo:'bar',
  baz:'qux'
});

Static methods can be declared for a class when the class is created, by using the optional featuresByTypeOBJ parameter when calling the Uize.Class.subclass static method.

The features declaration object should contain an staticMethods property whose value should be an object containing mappings of static method names to implementation functions.

EXAMPLE

var MyClass = Uize.Class.subclass ({
  staticMethods:{
    foo:function () {
      // implementation of foo static method
    },
    bar:function () {
      // implementation of bar static method
    }
  }
});

Static methods can be declared for a class after the class has already been created, by calling the MyClass.declare method on the class.

The features declaration object passed to the MyClass.declare method should contain an staticMethods property whose value should be an object containing mappings of static method names to implementation functions.

EXAMPLE

MyClass.declare ({
  staticMethods:{
    foo:function () {
      // implementation of foo static method
    },
    bar:function () {
      // implementation of bar static method
    }
  }
});

Static methods can be declared for a class after the class has already been created, by calling the MyClass.staticMethods method on the class.

When calling the MyClass.staticMethods method, a static methods declaration object should be provided, containing mappings of static method names to implementation functions.

EXAMPLE

MyClass.staticMethods ({
  foo:function () {
    // implementation of foo static method
  },
  bar:function () {
    // implementation of bar static method
  }
});

Static properties can be declared for a class when the class is created, by using the optional featuresByTypeOBJ parameter when calling the Uize.Class.subclass static method.

The features declaration object should contain a staticProperties property whose value should be an object containing mappings of static property names to initial values.

EXAMPLE

var MyClass = Uize.Class.subclass ({
  staticProperties:{
    foo:'bar',
    baz:'qux'
  }
});

Static properties can be declared for a class after the class has already been created, by calling the MyClass.declare method on the class.

The features declaration object passed to the MyClass.declare method should contain a staticProperties property whose value should be an object containing mappings of static property names to initial values.

EXAMPLE

MyClass.declare ({
  staticProperties:{
    foo:'bar',
    baz:'qux'
  }
});

Static properties can be declared for a class after the class has already been created, by calling the MyClass.staticProperties method on the class.

When calling the MyClass.staticProperties method, a static properties declaration object should be provided, containing mappings of static property names to initial values.

EXAMPLE

MyClass.staticProperties ({
  foo:'bar',
  baz:'qux'
});

State properties can be declared for a class when the class is created, by using the optional featuresByTypeOBJ parameter when calling the Uize.Class.subclass static method.

The features declaration object should contain a stateProperties property whose value should be an object containing mappings of state property names to property profiles.

EXAMPLE

var MyClass = Uize.Class.subclass ({
  stateProperties:{
    width:{
      conformer:function (value) {return Uize.constrain (value,1,50)},
      value:10
    },
    height:{
      conformer:function (value) {return Uize.constrain (value,1,50)},
      value:10
    }
  }
});

State properties can be declared for a class after the class has already been created, by calling the MyClass.declare method on the class.

The features declaration object passed to the MyClass.declare method should contain a stateProperties property whose value should be an object containing mappings of state property names to property profiles.

EXAMPLE

MyClass.declare ({
  stateProperties:{
    width:{
      conformer:function (value) {return Uize.constrain (value,1,50)},
      value:10
    },
    height:{
      conformer:function (value) {return Uize.constrain (value,1,50)},
      value:10
    }
  }
});

State properties can be declared for a class after the class has already been created, by calling the MyClass.stateProperties method on the class.

When calling the MyClass.stateProperties method, a state properties declaration object should be provided, containing mappings of state property names to property profiles.

EXAMPLE

MyClass.stateProperties ({
  width:{
    conformer:function (value) {return Uize.constrain (value,1,50)},
    value:10
  },
  height:{
    conformer:function (value) {return Uize.constrain (value,1,50)},
    value:10
  }
});

Dual context methods can be declared for a class when the class is created, by using the optional featuresByTypeOBJ parameter when calling the Uize.Class.subclass static method.

The features declaration object should contain an dualContextMethods property whose value should be an object containing mappings of dual context method names to implementation functions.

EXAMPLE

var MyClass = Uize.Class.subclass ({
  dualContextMethods:{
    foo:function () {
      // implementation of foo dual context method
    },
    bar:function () {
      // implementation of bar dual context method
    }
  }
});

Dual context methods can be declared for a class after the class has already been created, by calling the MyClass.declare method on the class.

The features declaration object passed to the MyClass.declare method should contain an dualContextMethods property whose value should be an object containing mappings of dual context method names to implementation functions.

EXAMPLE

MyClass.declare ({
  dualContextMethods:{
    foo:function () {
      // implementation of foo dual context method
    },
    bar:function () {
      // implementation of bar dual context method
    }
  }
});

Dual context methods can be declared for a class after the class has already been created, by calling the MyClass.dualContextMethods method on the class.

When calling the MyClass.dualContextMethods method, a dual context methods declaration object should be provided, containing mappings of dual context method names to implementation functions.

EXAMPLE

MyClass.dualContextMethods ({
  foo:function () {
    // implementation of foo dual context method
  },
  bar:function () {
    // implementation of foo dual context method
  }
});

Dual context properties can be declared for a class when the class is created, by using the optional featuresByTypeOBJ parameter when calling the Uize.Class.subclass static method.

The features declaration object should contain an dualContextProperties property whose value should be an object containing mappings of dual context property names to initial values.

EXAMPLE

var MyClass = Uize.Class.subclass ({
  dualContextProperties:{
    foo:'bar',
    baz:'qux'
  }
});

Dual context properties can be declared for a class after the class has already been created, by calling the MyClass.declare method on the class.

The features declaration object passed to the MyClass.declare method should contain an dualContextProperties property whose value should be an object containing mappings of dual context property names to initial values.

EXAMPLE

MyClass.declare ({
  dualContextProperties:{
    foo:'bar',
    baz:'qux'
  }
});

Dual context properties can be declared for a class after the class has already been created, by calling the MyClass.dualContextProperties method on the class.

When calling the MyClass.dualContextProperties method, a dual context properties declaration object should be provided, containing mappings of dual context property names to initial values.

EXAMPLE

MyClass.dualContextProperties ({
  foo:'bar',
  baz:'qux'
});

.

.

Overriding instance methods and properties of a superclass is easy. It's just a matter of re-assigning.

EXAMPLE

var MyClass = Uize.Class.subclass ({      // create a class with an instance method
  instanceMethods:{
    foo:function () {alert ('bar')}
  }
});

var MySubclass = MyClass.subclass ({      // create subclass and override inherited instance method
  instanceMethods:{
    foo:function () {
      alert ('foo');
      MyClass.doMy (this,'foo');  // call superclass' version of foo instance method
    }
  }
});

var myClassInstance = new MyClass;        // create an instance of the class
myClassInstance.foo ();                   // call foo method on instance of class

var mySubclassInstance = new MySubclass;  // create an instance of the subclass
mySubclassInstance.foo ();                // call foo method on instance of subclass

In this example, the foo instance method of the subclass has been overrided so that it first alerts the text "foo" and then calls the foo method implementation from the superclass and alerts the text "bar".

Typically, the code that implements the methods of a subclass is near (or in the same scope as) the code that creates the subclass, so the subclass knows its superclass. When you start digging into subclass modules, you will encounter this reference to the superclass in the form of the _superclass variable (named such by convention).

Overriding static methods and properties of a superclass is easy. It's just a matter of re-assigning.

EXAMPLE

var MyClass = Uize.Class.subclass ({  // create a class with a static method
  staticMethods:{
    myStaticMethod:function () {alert ('foo')}
  }
});

var MySubclass = MyClass.subclass ({  // create subclass, overriding inherited static method
  staticMethods:{
    myStaticMethod:function () {alert ('bar')}
  }
});

myClass.myStaticMethod ();            // call myStaticMethod on MyClass
mySubclass.myStaticMethod ();         // call myStaticMethod on MySubclass

In this example, MySubclass is a subclass of MyClass, and both classes have a static method myStaticMethod. By subclassing MyClass, MySubclass inherits the implementation of myStaticMethod from MyClass. Re-assigning the myStaticMethod property of MySubclass overrides the inherited implementation without affecting MyClass. So, calling myStaticMethod on MyClass will product the text "foo" in an alert dialog, while calling myStaticMethod on MySubclass will product the text "bar" in an alert dialog.

8.1.2.1. Calling a Subclass Version of a Static Method

var MyClass = Uize.Class.subclass ({
  instanceMethods:{
    myInstanceMethod:function () {
      this.Class.myStaticMethod (); // call myStaticMethod static method on subclass
    }
  }
});

var MyClass = Uize.Class.subclass ({      // create a class
  staticMethods:{
    myStaticMethod:function () {
      alert ('MyClass');
    }
  },
  instanceMethods:{
    myInstanceMethod:function () {
      this.Class.myStaticMethod ();
    }
  }
});

var MySubclass = MyClass.subclass ({      // subclass the class, overriding static method
  staticMethods:{
    myStaticMethod:function () {
      alert ('MySubclass');
    }
  }
});

var mySubclassInstance = new MySubclass;  // create instance of MySubclass
mySubclassInstance.myInstanceMethod ();   // call myInstanceMethod

MyClass.myStaticMethod = function () {
  this.myOtherStaticMethod ();
};

MyClass = Uize.Class.subclass ({         // create a class with two static methods
  staticMethods:{
    myStaticMethod:function () {
      this.myOtherStaticMethod ();
    },
    myOtherStaticMethod:function () {
      alert ('MyClass');
    }
  }
});

MySubclass = MyClass.subclass ({         // create subclass, overriding inherited static method
  staticMethods:{
    myOtherStaticMethod:function () {
      alert ('MySubclass');
    }
  }
});

MySubclass.myStaticMethod ();            // call inherited static method

The initial value for a state property inherited from a superclass can be overrided by calling the MyClass.set static method that is inherited from the Uize.Class base class.

The initial value for a state property is declared by specifying the value property in the profile for the state property, as follows...

EXAMPLE

var MyClass = Uize.Class.subclass ({   // create a class with a foo state property
  stateProperties:{
    _foo:{
      name:'foo',
      onChange:function () {
        // code to handle a change in foo's value
      },
      value:'bar'
    }
  }
});

var _myClassInstance = new MyClass;    // create instance of MyClass
alert (_myClassInstance.get ('foo'));  // alert value of foo state property

In the above example, the text "bar" will be displayed in the alert dialog.

Now, the initial value for the foo state property inherited from MyClass can be overrided in a subclass, as follows...

EXAMPLE

var MyClass = Uize.Class.subclass ({   // create a class with a foo state property
  stateProperties:{
    _foo:{
      name:'foo',
      onChange:function () {
        // code to handle a change in foo's value
      },
      value:'bar'
    }
  }
});

var MySubclass = MyClass.subclass ({   // subclass the class, overriding initial value for foo
  set:{foo:'NOT BAR'}
});

var _mySubclassInstance = new MySubclass;  // create instance of MySubclass
alert (_mySubclassInstance.get ('foo'));   // alert value of foo state property

In this example, we have now created a subclass of MyClass named MySubclass. The new subclass inherits the foo state property, along with its initial value of 'bar' that is declared in MyClass. When creating the MySubclass subclass, we use the set declaration to change the initial value of this state property to 'NOT BAR'. This is equivalent to calling MySubclass.set, but we can tuck it neatly into the subclassing statement. Now, the fresh instance of MySubclass that is created, named _mySubclassInstance, will have the initial value 'NOT BAR' for its foo state property, and the alert dialog will display this text.

The MyClass.nonInheritableStatics static property is a lookup object, automatically created for a class, in which you can register the static features (methods or properties) of the class that should not be inherited when that class is subclassed.

Each property of the MyClass.nonInheritableStatics lookup object represents a single static feature of the class that should not be inherited by subclasses, where the name of each property should be the name of a static feature (excluding the module name), and the value of each property should be a truthy value (such as true, 1, 'foo', [], {}, etc.). After a class has been created, non-inheritable statics can be registered for that class by assigning properties to the class' MyClass.nonInheritableStatics static property, as shown in the example below...

EXAMPLE

MyClass = Uize.Class.subclass ({
  staticMethods:{
    someUtilityFunction:function () {
      // do something of great utility
    }
  }
});
MyClass.nonInheritableStatics.someUtilityFunction = 1;

MyClassSubclass = MyClass.subclass ();
alert (MyClassSubclass.someUtilityFunction); // alerts the text "undefined"

In the above example, the MyClass.someUtilityFunction static method of the class MyClass has been registered as a non-inheritable static. This is done by the statement MyClass.nonInheritableStatics.someUtilityFunction = 1. Now, when the MyClassSubclass class is created by calling the MyClass.subclass method, the new subclass that is created does not get the someUtilityFunction static feature. Therefore, the alert statement displays the text "undefined" in the alert dialog.

9.2.1.1. nonInheritableStatics is a Non-inheritable Static

All types of static features of a class can be registered as non-inheritable - methods as well as properties.

Registering static properties as non-inheritable is accomplished in the same way as for static methods. Consider the following example...

EXAMPLE

MyClass = Uize.Class.subclass ({
  staticProperties:{
    someStaticProperty:'foo'
  }
});
MyClass.nonInheritableStatics.someStaticProperty = 1;

MyClassSubclass = MyClass.subclass ();
alert (MyClassSubclass.someStaticProperty); // alerts the text "undefined"

In the above example, the alert dialog would display the text "undefined", because the MyClass.someStaticProperty static property of the class MyClass has been registered as non-inheritable, so it is not inherited by the MyClassSubclass class that is created by subclassing MyClass.

A good case for making a static method non-inheritable is if it is really just a utility function that happens to be stashed in a class' namespace.

Static methods that are really just utility or helper functions don't care about the context on which they are called. They just happen to be called on a class as a context because they are assigned as properties on a class.

Take, for example, the Uize.Fade.celeration static method of the Uize.Fade class. You may be calling it on the Uize.Fade context, but this utility function's implementation doesn't even reference the this keyword - it just doesn't care about the context on which it is called. You could, in fact, assign this static method to a local variable and then call it using that local variable, and it would behave in just the same way as if it were being called on the class. Consider the following example...

EXAMPLE

var celeration = Uize.Fade.celeration;
alert (celeration (.5,.5) (.3));  // alerts the text ".18"

In the above example, our local variable celeration is a function reference. When that local variable is used to call the function in order to generate an acceleration/deceleration curve function, everything works just fine. The alert statement alerts the result of calling the generated curve function with the progress amount of .3, yielding the curve-adjusted blend amount of .18. Because the Uize.Fade.celeration static method doesn't operate on a Uize.Fade subclass or need a Uize.Fade subclass as its context when it is called, there's no compelling reason for it to be inheritable, and so it is not.

Whenever a static method or property is intended to be unique to its class context, and it is also desirable for that method or property to be inherited by subclasses, then it should not be registered as non-inheritable.

Examples of some static methods in the Uize.Class base class that are inheritable are the Uize.Class.set, Uize.Class.get, Uize.Class.toggle, Uize.Class.fire, Uize.Class.wire, Uize.Class.subclass, and Uize.Class.stateProperties methods. All of these methods act on the class context. So, for example, calling Uize.Class.subclass is different to calling Uize.Widget.subclass. The Uize.Class.subclass method, which is inherited by all Uize.Class subclasses, uses the context of the class on which it is called. Calling the Uize.Class.subclass method returns a subclass of Uize.Class, while calling the Uize.Widget.subclass method returns a subclass of Uize.Widget - even though both of these methods reference the same function for their implementation (in other words, the statement alert (Uize.Class.subclass == Uize.Widget.subclass) would alert the text "true").

All static features of modules of the UIZE JavaScript Framework are noted as being either inheritable or non-inheritable in the reference documentation for those features.

The inheritability of the static features of a module is noted in the IMPLEMENTATION INFO notes of the reference documentation for the features in the module's reference. So, for example, if you went to the reference documentation for the Uize.Class.set static method of the Uize.Class base class, you would see it noted that the feature is inherited by subclasses. In contrast, if you went to the reference documentation for the Uize.Fade.blendValues static method of the Uize.Fade class, you would see it noted that the feature is not inherited by subclasses.

Because singleton support is implemented in the Uize.Class base class, a singleton for any Uize.Class subclass can be created by calling the singleton static method on the class.

EXAMPLE

var fileSystem = Uize.Services.FileSystem.singleton ();

In the above example, the Uize.Services.FileSystem class is a subclass of the Uize.Service class, which is itself a subclass of the Uize.Class base class. Therefore, a singleton can be created using the Uize.Services.FileSystem.singleton static method that is inherited from Uize.Class.

As expected with singletons, multiple separate calls to the singleton static method will return a reference to the same singleton.

EXAMPLE

var
  fileSystemSingleton1 = Uize.Services.FileSystem.singleton (),
  fileSystemSingleton2 = Uize.Services.FileSystem.singleton ()
;
alert (fileSystemSingleton1 === fileSystemSingleton2);  // alerts "true"

In the above example, both the fileSystemSingleton1 and fileSystemSingleton2 variables are set to be a singleton of the Uize.Services.FileSystem class. Therefore, when their values are compared using a strict equality, they are found to be equal.

A typical and compelling use case for the singleton feature is with service classes, where one typically wants to share a single instance of a service class amongst multiple disparate users of the service.

In the case of service classes, one may instantiate and set up the singleton of a service in the environment (which will likely be a Web page for services that are to run in Web applications). Then, in other code that is to run in the environment and use the service, the singleton of the service can simply be obtained and used - the service doesn't need to be initialized by all the users because the same shared singleton of the service class is initialized and set up in the environment.

As a convenience, the singleton static method provides a way to optionally create singletons in a custom scope.

A scope for a singleton of a class is specified using the optional scopeSTR parameter, as follows...

EXAMPLE

var fileSystemForBuildScripts = Uize.Services.FileSystem.singleton ('buildScripts');

In the above example, a singleton of the Uize.Services.FileSystem class is being created in a scope we have decided to call "buildScripts". Now, any other build script code that wants to get a reference to this singleton can perform the same operation, specifying 'buildScripts' as the value for the scopeSTR parameter. With this kind of arrangement, other code can now use the same Uize.Services.FileSystem service class in a different scope. In different scopes, the different singletons may be set up with different service adapters and initialized differently to perform different I/O.

9.3.4.1. A Single Singleton Per Scope

var
  fileSystemInScopeA = Uize.Services.FileSystem.singleton ('scopeA'),
  fileSystemInScopeB = Uize.Services.FileSystem.singleton ('scopeB')
;
alert (fileSystemInScopeA === fileSystemInScopeB);  // alerts "false"

9.3.4.2. Designing Classes to Support Singleton Scope

9.3.4.3. Singleton Scope is Globalish

A singleton can be created with an initial state by specifying the optional propertiesOBJ second parameter.

EXAMPLE

var fileSystemForBuildScripts = Uize.Services.FileSystem.singleton ('',{defaultEncoding:'utf8'});

In the above example, a singleton is being created for the Uize.Services.FileSystem class. Because the first parameter of the singleton method is the singleton scope, if we want to use the default scope we need to specify an empty string. The second parameter is the state for the singleton, where the value is an object that will be passed to the constructor of the class if the singleton has not yet been created for the scope, or used in a call to the set method if the singleton already exists in the scope.

While there are a few compelling use cases for singletons, one should nevertheless use the singleton feature sparingly and with caution.

The very advantage of singletons, which is that they can be shared by disparate pieces of code, can also become a disadvantage. Singletons can be regarded as being, in effect, globals in the scope of the class on which they are created, or the singleton scope in which they are created. This consequence brings with it the kinds of drawbacks that globals have more generally.

Singletons aren't as egregious as global variables, and the singleton scope facility goes some way to alleviating the globalish nature of singletons. Nevertheless, before resorting to using singletons, consider first if there are other alternatives. In UIZE, you will find singletons mostly advocated for use with service classes.

Because the Uize.Class base class utilizes the "no new" mechanism, one can create instances of any Uize.Class subclass either using the new operator or not.

EXAMPLE

// this works
var mySlider1 = new Uize.Widget.Bar.Slider ({minValue:0,maxValue:100,value:50});

// Look ma, no "new"!!!
var mySlider2 = Uize.Widget.Bar.Slider ({minValue:0,maxValue:100,value:50});

Because of the way in which the "no new" mechanism is implemented in the Uize.Class base class, any class that is derived from a Uize.Class base class using the subclass method gets the same benefit, including classes that you create for your own applications.

This means, for example, that any widget class you create by subclassing the Uize.Widget class will get the same benefit. Consider the following example...

EXAMPLE

// we create a widget class
var MyWidgetClass = Uize.Widget.subclass ();

// this works
var myWidgetClassInstance1 = new MyWidgetClass ();

// Look ma, no "new"!!!
var myWidgetClassInstance2 = MyWidgetClass ();

The "no new" mechanism, that is implemented in the Uize.noNew static method, has been applied to various other Uize objects (such as the Uize.Color object) that are lightweight objects rather than full Uize.Class subclasses.

So, for example, one can create instances of the Uize.Color object or the Uize.Str.Builder object without needing to use the new operator. Consider the following example...

EXAMPLE

// this works
var fuchsia = new Uize.Color ('#ff0fff');

// Look ma, no "new"!!!
var olive = Uize.Color ('#808000');

An object constructor that supports the "no new" mechanism can easily be created using the Uize.noNew static method.

In cases where you're creating Uize.Class subclasses, you don't need to worry about the Uize.noNew method because the "no new" mechanism is built right into the Uize.Class base class, so all Uize classes get the benefit. However, in cases where you're defining your own lightweight objects, you can use the Uize.noNew method to create an object constructor where the new operator is optional. Consider the following example...

EXAMPLE

// define the Food object
var Food = Uize.noNew (
  function (name,type) {
    this.name = name;
    this.type = type;
  }
);

// create an instance of Food using the new operator
var apple = new Food ('apple','fruit');
alert (apple.type);  // alerts the text "fruit"

// create an instance of Food without using the new operator
var rice = Food ('rice','grain');
alert (rice.type);  // alerts the text "grain"

What you'll notice from the above example is that the Uize.noNew method is quite simple - it takes a single parameter, which is the constructor function that initializes the new instance. This means that you can easily take an existing object constructor function and upgrade it to one that supports the "no new" mechanism by wrapping it inside a call to the Uize.noNew method, which then returns a wrapper constructor that becomes your new object constructor. Consider the following before-and-after example...

BEFORE

// must always use "new" with this constructor
function Food (name,type) {
  this.name = name;
  this.type = type;
}

AFTER

// "new" is optional with this constructor
var Food = Uize.noNew (
  function (name,type) {
    this.name = name;
    this.type = type;
  }
);

Notice that you need to assign the result of the Uize.noNew method call, and so your original constructor function no longer should have the name.