The Uize.Widget.Collection class implements a widget for managing a collection of items, with support for managing selected state of items (including non-contiguous selection, range selection, and controls for selecting all, selecting none, and removing selected items), and methods by which application code can manipulate the collection.

1.1.1. Collection Item Widget Naming

var myCollection = page.addChild (
  'collection',
  Uize.Widget.Collection,
  {
    itemWidgetClass:Uize.Widget.CollectionItem,
    itemPropertyForItemWidgetName:'widgetName',
    items:[
      {
        widgetName:'bravingTheOnslaught',
        title:'Braving the Onslaught',
        category:'The Winter Collection'
      },
      {
        widgetName:'flockOfClouds',
        title:'Flock of Clouds',
        category:'The Photographic Orphanage'
      }
    ]
  }
);

var myCollection = page.addChild (
  'collection',
  Uize.Widget.Collection,
  {
    itemWidgetClass:Uize.Widget.CollectionItem,
    itemPropertyForItemWidgetName:null,
    itemWidgetNamePrefix:'photoItem',
    items:[
      {
        title:'Braving the Onslaught',
        category:'The Winter Collection'
      },
      {
        title:'Flock of Clouds',
        category:'The Photographic Orphanage'
      }
    ]
  }
);

There are no dedicated showcase example pages for the Uize.Widget.Collection module.

SEARCH FOR EXAMPLES

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

SEARCH

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

INHERITANCE CHAIN

Uize.Class −> Uize.Widget −> Uize.Widget.Collection

1.3.1. Features Introduced in This Module

1.3.2. Features Overridden in This Module

1.3.3. Features Inherited From Other Modules

1.3.4. Modules Directly Under This Namespace

1.3.5. Unit Tests

An instance event that is fired whenever an item becomes selected.

When this event is fired, the event object will contain an itemWidget property whose value will be a reference to the item widget for the item that has become selected.

An instance even that is fired whenever the items in the collection are modified.

An instance event that is fired when calling the remove instance method.

This event is fired immediately upon calling the remove instance method, and before calling the finishRemove hook method. When this event is fired, the event object will have the following contents...

EVENT OBJECT

{
  name         : 'Remove',                  // event name (standard event property)
  source       : collectionInstanceOBJ,     // event source (standard event property)
  itemWidgets  : itemWidgetsToRemoveARRAY,  // widgets for items being removed
  byUser       : byUserBOOL,                // whether or not user initiated remove
  finishRemove : finishRemoveCallbackFUNC   // callback, if you set handled to true
}

A handler that is wired for this event has the option of declaring that the remove request has been handled, by setting the handled property on the event object to true. If a handler does this, then the remove method will not call the finishRemove hook method after the event has been fired. Instead, it will be up to your even handler code to complete the removal of the items by calling the "finishRemove" function that is a property of the event object, when it is appropriate to do so, and supplying values for the itemWidgetsToRemoveARRAY and byUserBOOL parameters that this function accepts. Alternatively, the handler code could not call the "finishRemove" function and could, instead, remove the item widgets itself.

Among other things, this event mechanism allows specialized subclass or application code to insert an asynchronous interstitial step in the remove process, and it allows custom code to modify the list of items that will be removed.

NOTES

A node that will be used to display the total number of items in the collection.

Whenever the value of the totalItems state property changes, this node will be updated using the setNodeValue instance method of the Uize.Widget class. Because the setNodeValue method is used for displaying the value of the totalItems property, the totalItems DOM Node can be of any type supported by the setNodeValue method - it can be a div tag, a span tag, a p tag, a text input tag, a textarea tag, etc.

NOTES

A read-only array of collection item widget instances, where each collection item widget in the array corresponds to an element of the items array.

Elements of this array are typically instances of the Uize.Widget.CollectionItem class, or some subclass thereof. The contents of this array are modified as items are added to or removed from the collection, but the itemWidgets property should maintain a reference to the same array throughout the life of the collection instance. The value of this property should not be set explicitly, nor should the contents of the array be changed explicitly. Instead, methods such as the addItemWidget instance method should be used to manage the contents of the collection.

NOTES

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

An instance of Uize.Widget.Button, that is wired up so that clicking it will prompt the user to confirm that they wish to remove the selected items, and will then remove the selected items if the user agrees.

This button is disabled whenever the value of the someSelected state property is false. Put another way, this button is only enabled when the value of someSelected is true.

NOTES

An instance of Uize.Widget.Button, that is wired up to call the selectAll instance method when clicked.

This button is disabled whenever...

NOTES

An instance of Uize.Widget.Button, that is wired up to call the selectAll instance method when clicked, with the value false specified for the selectAll method's selectedBOOL parameter.

This button is disabled whenever the value of the someSelected state property is false. Put another way, this button is only enabled when the value of someSelected is true.

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

For advanced developers only, this is a subclassing hook that lets you add a button child widget with the specified name, with a specified click handler function, and whose enabled state is determined by a specified condition.

SYNTAX

buttonOBJ = myInstance.addControlButton (
  buttonNameSTR,               // name of button child widget
  clickHandlerFUNC,            // code to execute when button is clicked
  enabledWhenSTRorARRAYorFUNC  // condition under which button should be enabled
);

This method returns a reference to the button child widget created.

6.3.1. buttonNameSTR

6.3.2. clickHandlerFUNC

6.3.3. enabledWhenSTRorARRAYorFUNC

myCollection.addControlButton (
  'selectAll',
  function () {
    // code here to select all items
  },
  '!allSelected,!isEmpty'
);

VARIATION 1

buttonOBJ = myInstance.addControlButton (buttonNameSTR,eventNameSTR,enabledWhenSTRorARRAYorFUNC);

When the eventNameSTR parameter is specified in place of the clickHandlerFUNC parameter, then an event of the name specified by the eventNameSTR parameter will be fired on the button child widget.

VARIATIONS 2 & 3

buttonOBJ = myInstance.addControlButton (buttonNameSTR,clickHandlerFUNC);
buttonOBJ = myInstance.addControlButton (buttonNameSTR,eventNameSTR);

When the enabledWhenSTRorARRAYorFUNC parameter is omitted, then no enabled state management will be performed and you will have to implement your own enabled state management, if desired.

NOTES

IMPLEMENTATION INFO

Lets you add an item widget to the collection, returning a reference to the item widget added.

SYNTAX

itemWidgetOBJ = myInstance.addItemWidget (itemWidgetNameSTR,itemWidgetPropertiesOBJ);

The value of the itemWidgetNameSTR parameter should be the widget name for the item widget that will be added as a child of the collection widget. The value of this parameter can be any string, so long as it doesn't collide with the names of existing child widgets of the collection widget, including the various button widgets of the class, and other existing item widgets. A value for this parameter can be generated using the makeItemWidgetName hook method.

The value of the itemWidgetPropertiesOBJ parameter should be an object containing the values for state properties of the item widget to be created. This object will be modified by the addItemWidget method, by copying in the properties of the object returned by the getItemWidgetProperties hook method.

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

A hook method, that is intended to be overrided in a subclass' implementation and that is called to complete a remove operation begun by calling the remove instance method.

SYNTAX

myInstance.finishRemove (itemWidgetsToRemoveARRAY,byUserBOOL);

A subclass' implementation for this method should expect the two parameters itemWidgetsToRemoveARRAY and byUserBOOL, where itemWidgetsToRemoveARRAY is an array of collection item widgets for the items to be removed, and where byUserBOOL is a boolean indicating whether or not the remove was initiated by the user (as opposed to programmatically).

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Iterates through all the collection item widgets in the collection and performs the specified handler function for each item widget.

SYNTAX

myInstance.forAll (itemHandlerFUNC);

The function specified for the itemHandlerFUNC parameter should expect to receive two parameters: itemWidgetOBJ and itemNo, where itemWidgetOBJ is a reference to an item's collection item widget, and where itemNo is the item number / index for the item being processed. Your handler function can optionally omit the itemNo parameter from its definition if it doesn't need an item's index to perform its operation. If your handler function returns the special value false, then the iteration will be terminated.

EXAMPLE

var itemUserIsOver;
myCollection.forAll (
  function (itemWidget) {
    if (itemWidget.get ('over')) {
      itemUserIsOver = itemWidget;
      return false;
    }
  }
)

In the above example, the forAll method is being used to iterate through the item widgets in the collection to find the one (if any) that the user is currently mousing over. If the item handler function finds an item that the user is over, where the value of the item widget's over state property is true, then the handler sets the itemUserIsOver variable to this item widget and then returns the special value false, indicating to the forAll iterator that it should break out of the iteration (after all, the item handler function can't use the break statement to accomplish that in this case).

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

For advanced developers only, this is a subclassing hook that lets you override the default use of the itemWidgetProperties state property in the addItemWidget instance method.

SYNTAX

itemWidgetPropertiesOBJ = myInstance.getItemWidgetProperties ();

The implementation of this method by this base class simply returns a reference to the itemWidgetProperties state property. By overriding this method in a subclass, you can provide your own logic for generating the item widget properties that will be used when adding item widgets in the addItemWidget instance method. One thing you can do with your own override of this method is to stitch in additional properties at the time of adding an item widget. You can look for an example of this in the implementation of the Uize.Widget.Collection.Dynamic class.

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Returns an array, being the values of the specified properties "bucket" property for the specified items.

SYNTAX

propertyValuesARRAY = myInstance.getPropertyForItems (propertyNameSTR,itemWidgetsARRAY);

Items in the collection are represented by item widgets, and each item widget for an item should have a properties state property, which serves as a "bucket" for additional item data. The getPropertyForItems method lets you get an array of the values for a specific property in this properties "bucket" for all of the specified items, where the items are specified by an array containing item widgets that correspond to items in the collection.

6.24.1. For All Items

var productIds = myCollection.getPropertyForItems ('productId',myCollection.itemWidgets);

6.24.2. An Example

var myCollection = page.addChild (
  'collection',
  Uize.Widget.Collection,
  {
    itemWidgetClass:Uize.Widget.CollectionItem,
    items:[
      {
        title:'A Lighted Spot',
        properties:{
          productId:'228277244419896914',
          category:'Trees Among Us'
        }
      },
      {
        title:'Braving the Onslaught',
        properties:{
          productId:'228109666540948246',
          category:'The Winter Collection'
        }
      },
      {
        title:'Companion to a Sunset',
        properties:{
          productId:'228745103279879745',
          category:'The Sunset Collection'
        }
      }
    ]
  }
);

var productIds = myCollection.getPropertyForItems ('productId',myCollection.itemWidgets);

['228277244419896914','228109666540948246','228745103279879745']

6.24.3. Getting All Properties

var productIds = myCollection.getPropertyForItems (null,myCollection.itemWidgets);

[
  {
    productId:'228277244419896914',
    category:'Trees Among Us'
  },
  {
    productId:'228109666540948246',
    category:'The Winter Collection'
  },
  {
    productId:'228745103279879745',
    category:'The Sunset Collection'
  }
]

NOTES

IMPLEMENTATION INFO

Returns an array, being the values of the specified properties "bucket" property for the selected items.

SYNTAX

propertyValuesARRAY = myInstance.getPropertyForSelected (propertyNameSTR);

Using this method is equivalent to using the getPropertyForItems instance method and using the getSelected instance method to get an array of just the selected item widgets to specify for the getPropertyForItems method's itemWidgetsARRAY parameter. For example, the statement myCollection.getPropertyForSelected ('productId') would be equivalent to the statement myCollection.getPropertyForItems ('productId',myCollection.getSelected ()).

Because the getPropertyForSelected method uses the getPropertyForItems method for its implementation, you can consult the reference for the getPropertyForItems method for more detail on how the getPropertyForSelected method behaves.

VARIATION

propertyValuesARRAY = myInstance.getPropertyForSelected (propertyNameSTR,allIfNoneBOOL);

When the value true is specified for the optional allIfNoneBOOL parameter, then the getPropertyForSelected method will return an array of the values of the specified properties "bucket" property for all items in the collection when no items are selected.

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Returns an array of the selected collection items, where each element of the array is an object reference to a selected item's collection item widget.

SYNTAX

itemWidgetsARRAY = myInstance.getSelected ();

The elements of the returned selected items array are in the order of the items in itemWidgets array.

VARIATION

itemWidgetsARRAY = myInstance.getSelected (allIfNoneBOOL);

When the optional allIfNoneBOOL parameter is specified, you can control whether or not all the item widgets in the collection should be returned when none are selected. This may be useful for certain operations that should operate on all items when a selection has not been made.

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

This is a hook method, overrideable by subclasses, which checks to see if the widget being added through widget adoption is a collection item

SYNTAX

bool = myInstance.isCollectionItem (itemWidget);

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Widget, but introduced in Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

For advanced developers only, this is a subclassing hook that lets you obtain a generated name for a new item widget that is to be added.

SYNTAX

itemWidgetNameSTR = myInstance.makeItemWidgetName (itemOBJ);

This method is not intended to be overrided by a subclass, but is intended instead to be used as part of the implementation of a subclass method that adds items to the collection. The method will be called first in order to generate a widget name for the item widget about to be added, and the generated name will then be used when adding the new item widget.

The itemOBJ parameter can be used to supply a reference to the properties "bucket" for additional item data. When an object is specified for the itemOBJ parameter, and when the itemPropertyForItemWidgetName state property is set to a non-empty string, and when the value of the property in the itemOBJ object specified by the itemPropertyForItemWidgetName property is a non-empty string, then that property will be returned as the item widget name. Otherwise, the item widget name will be generated by concatenating the value of the itemWidgetNamePrefix state property with a dynamically generated and automatically incremented uniquifier value.

VARIATION

itemWidgetNameSTR = myInstance.makeItemWidgetName ();

When the itemOBJ parameter is not specified, then the makeItemWidgetName method will behave as though the value null were specified for this parameter (see above).

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Lets you initiate removal of the specified set of items from the collection.

SYNTAX

myInstance.remove (itemWidgetsToRemoveARRAY,byUserBOOL);

The items to be removed by this method should be specified in the itemWidgetsToRemoveARRAY parameter, where the value of this parameter should be an array of item widgets corresponding to the items to be removed. This method should be called with the value true specified for the byUserBOOL method when the remove operation is initiated by the user, such as when the user clicks on a remove button in the UI.

When this method is called, the method first fires the Remove instance event. If a handler is wired to handle this event and sets the handled property on the event object to true, then the remove method will do nothing after the event has been fired. If, on the other hand, the handled property of the event object is not set to true, then the remove method will call the finishRemove instance method after the event has been fired. The finishRemove method is a hook method that provides a subclass of Uize.Widget.Collection the ability to implement a custom items remover method.

VARIATION

myInstance.remove (itemWidgetsToRemoveARRAY);

When the byUserBOOL parameter is omitted, or its value is undefined or null, then its value is defaulted to false.

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Selects all collection item widgets in the collection.

SYNTAX

myInstance.selectAll ();

Calling this method has the effect of setting the value of the selected state property of all collection item widgets to true. Calling this method will also result in the values of the allSelected, oneSelected, someSelected, and totalSelected state properties being updated, upon which some of these properties may change value.

VARIATION 1

myInstance.selectAll (selectedBOOL);

When the optional selectedBOOL parameter is specified, the desired selected state for all the collection items in the collection can be specified. Specifying the value true for the selectedBOOL parameter is equivalent to calling this method without specifying a parameter, and specifying the value false is equivalent to calling the selectNone instance method.

VARIATION 2

myInstance.selectAll (selectedBOOL,toExcludeItemWidgetOBJ);

When the optional toExcludeItemWidgetOBJ parameter is specified, then an object reference can be specified for a collection item widget whose selected state should not be modified by calling the selectAll method. This allows us to select all but or deselect all but a specific item in the collection.

NOTES

IMPLEMENTATION INFO

Deselects all collection item widgets in the collection.

SYNTAX

myInstance.selectNone ();

Calling this method has the effect of setting the value of the selected state property of all collection item widgets to false, and is equivalent to calling the selectAll instance method and specifying the value false for the selectedBOOL parameter. Calling this method will also result in the values of the allSelected, oneSelected, someSelected, and totalSelected state properties being updated, upon which some of these properties may change value.

NOTES

IMPLEMENTATION INFO

Selects all collection item widgets in the specified range - from the one specified item widget to the other specified item widget.

SYNTAX

myInstance.selectRange (itemWidgetAOBJ,itemWidgetBOBJ);

Calling this method has the effect of setting the value of the selected state property of all collection item widgets within the specified range to true, and all collection item widgets outside of the specified range to false. The range is specified by the itemWidgetAOBJ and itemWidgetBOBJ parameters, and is inclusive of the two item widgets that are specified by these parameters. The order of the range bounds is unimportant - the item specified by itemWidgetAOBJ can be before or after the item specified by itemWidgetBOBJ in the itemWidgets array.

Calling this method will result in the values of the allSelected, oneSelected, someSelected, and totalSelected state properties being updated, upon which some of these properties may change value. Calling this method will have no effect if the values of either - or both - of the itemWidgetAOBJ or itemWidgetBOBJ parameters is null or undefined, or if the value of the selectionMode state property is 'single' and the values of the itemWidgetAOBJ and itemWidgetBOBJ parameters are not identical (i.e. you can only select a range of one item when selectionMode is set to 'single', and trying to select a range of more than one item will result in no action).

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

A hook allowing subclasses to post-process new item widgets

SYNTAX

myInstance.wireItemWidget (itemWidgetOBJ);

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

A localizable string, that will be displayed as the message in a confirmation dialog when the user chooses to remove a single item from the collection.

NOTES

A localizable string, that will be displayed as the message in a confirmation dialog when the user chooses to remove multiple items from the collection.

NOTES

A localizable string, that will be displayed as the title of a confirmation dialog when the user chooses to remove a single item from the collection.

NOTES

A localizable string, that will be displayed as the title of a confirmation dialog when the user chooses to remove multiple items from the collection.

NOTES

A read-only boolean, indicating whether or not all the items in the collection are selected.

Whenever the value of the totalSelected state property changes, the value of this property will be updated to be kept current and correct. Whenever the value of this property is true, the value of the someSelected state property will also be true.

The Changed.allSelected instance event can be wired in order to maintain enabled state of any UI elements whose enabled state is affected by whether or not all items are selected. For example, whenever this property is set to true, the selectAll child widget will be disabled. Conversely, whenever allSelected is set to false, the selectAll child widget will be enabled (provided that the isEmpty state property is not set to true).

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

A read-only boolean, indicating whether or not the collection is empty (i.e. has no items).

Whenever the value of the totalItems state property changes, the value of the isEmpty state property will be updated to be kept current and correct. When the isEmpty property is set to true, then the selectAll Child Widget will be disabled.

NOTES

IMPLEMENTATION INFO

A string, specifying the name of a property in an item's properties object that should be used as the name of the item's widget in the collection.

For a detailed discussion, see the section Explicit Naming of Collection Item Widgets.

NOTES

IMPLEMENTATION INFO

A boolean, specifying whether or not a Remove event fired by a selected collection item (as a result of the user clicking the item's remove button) should act on the rest of the selected items.

In certain applications, it might seem more appropriate for clicking the remove button of an individual collection item in a selection of collection items to remove all items in the current selection. In such cases, the itemRemoveActsOnSelection property can be set to true.

Even when this property is set to true, removing an individual collection item will not remove all selected items if the item being removed is not in the selection - if it is an unselected item, then only that item will be removed. So, essentially, when itemRemoveActsOnSelection is set to true, a single selected item becomes a proxy for the entire selection for a remove initiated on the item.

NOTES

IMPLEMENTATION INFO

An object reference, specifying the Uize.Widget.CollectionItem subclass that should be used for creating item widget instances.

In some cases, the Uize.Widget.CollectionItem base class may be adequate. In other cases, however, one may wish the item widgets to have more than just the most basic functionality. In such cases, one can create one's own collection item widget class and then specify this class as the value of the itemWidgetClass property when creating the collection instance.

NOTES

IMPLEMENTATION INFO

A string, specifying a prefix that should be used in collection item widget names when automatic widget naming is employed.

For a detailed discussion, see the section Automatic Naming of Collection Item Widgets.

NOTES

IMPLEMENTATION INFO

An object reference, specifying the values for any state properties that are common for all collection item widgets that are created by this class.

The Uize.Widget.Collection class will use this property when creating new collection item widget instances as child widgets. Consider the following example...

EXAMPLE

var myCollection = page.addChild (
  'collection',
  Uize.Widget.Collection,
  {
    itemWidgetClass:Uize.Widget.CollectionItem,
    itemPropertyForItemWidgetName:'widgetName',
    itemWidgetProperties:{previewClickAction:'Select'},
    items:[
      {
        widgetName:'bravingTheOnslaught',
        title:'Braving the Onslaught',
        category:'The Winter Collection'
      },
      {
        widgetName:'flockOfClouds',
        title:'Flock of Clouds',
        category:'The Photographic Orphanage'
      }
    ]
  }
);

In the above example, we're setting the itemWidgetProperties state property to the value {previewClickAction:'Select'}. This means that the two collection item child widgets that are created will both have their previewClickAction state property set to the value 'Select', which means that clicking on them will change their selected state.

NOTES

IMPLEMENTATION INFO

An array of objects, representing the item data corresponding to the items in the collection.

Each element of the items array should be an object, which serves as a "bucket" for additional data for an item. When a collection item widget is created for an item in the items array, the element from the items array is used as the value of the item widget's properties state property.

Whenever the value of the items property is changed, the following actions will be taken...

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

A read-only boolean, indicating whether or not just one item is selected.

Whenever the value of the totalSelected state property changes, the value of this property will be updated to be kept current and correct. Whenever the value of this property is true, the value of the someSelected state property will also be true.

The Changed.oneSelected instance event can be wired in order to maintain enabled state of any UI elements that trigger action on a single item and that are, therefore, not applicable when more than one item or no items are selected, but where it is still desirable to permit multiple selection for the sake of other actions that can operate on more than one item.

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

A string, specifying the mode ('single' or 'multi') for selecting items in the collection.

NOTES

IMPLEMENTATION INFO

A read-only boolean, indicating whether or not there are any items selected.

Whenever the value of the totalSelected state property changes, the value of this property will be updated to be kept current and correct. The value of this property will be true when the value of the oneSelected state property is true.

The Changed.someSelected instance event can be wired in order to maintain enabled state of any UI elements that trigger action on a selection and that are, therefore, not applicable when no items are selected. For example, whenever this property is set to true, the selectNone child widget will be enabled. Conversely, whenever someSelected is set to false, the selectNone child widget will be disabled.

NOTES

IMPLEMENTATION INFO

A read-only integer, indicating the total number of items in the collection.

Whenever the total number of items in the collection changes, either as a result of adding new items or removing items, the value of the isEmpty state property will be updated to be kept current and correct, and the totalItems DOM Node will be updated to reflect the new number of items in the collection.

NOTES

IMPLEMENTATION INFO

An read-only integer, indicating the total number of items that are selected.

Whenever the selection is changed, either by the user or programmatically, the value of this property will be updated. Whenever its value changes, the values of the oneSelected, someSelected, and allSelected state properties will be updated to be kept current and correct.

NOTES

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

Inherited from Uize.Widget.

IMPLEMENTATION INFO

IMPLEMENTATION INFO

IMPLEMENTATION INFO

Inherited from Uize.Class.

IMPLEMENTATION INFO

IMPLEMENTATION INFO