Class pvr.controller.PropertyCollectionController

Extends pvr.logging._LoggerMixin.
Provides a controller for any number of property collections in the model layer.

For each property collection, the property collection controller provides a collection of pvr.controller._PropertyController objects to maintain a binding with each property in the property collection. This binding assures that the property collection controller and its associated model objects remain in sync as directed by the configuration of their associated pvr.controller.integration.Integration objects.

Additionally, the property collection controller fires change events to notify other components of changes to attribute values that occur in either the controller or model layers. These changes are coordinated into discrete change sets that report all changes that occur as a result of a particular operation. You can call the pvr.controller.PropertyCollectionController#beginChangeSet and pvr.controller.PropertyCollectionController#endChangeSet methods to batch multiple operations into a single change set.

Each property collection provides a unique identifier that along with a property identifier can be used to uniquely reference a property. Earlier versions of this class did not support multiple property collections and binding references included only the property identifier. Since it's now possible for properties with the same property identifier to appear in multiple property collections, it's no longer possible to uniquely reference a property with only a property identifier. To support legacy applications, the concept of a default property collection was introduced. Specifically, a default property collection is a legacy property collection within which a property is expected to reside when it is referenced by only its property identifier. When attempting to resolve such property references, only default collections will be searched. Property identifiers are assumed to be unique across all default property collections. In general, default property collections should be used only when dealing with legacy applications.

Defined in: <pvr\controller\PropertyCollectionController.js>.

Constructor Summary

Constructor Attributes	Constructor Name and Description
	pvr.controller.PropertyCollectionController()

Field Summary

Field Attributes	Field Name and Description
	collections The property collections supported by this controller.
	context Indicates the context for this controller.

Method Summary

Method Attributes	Method Name and Description
	beginChangeSet() Begins the accumulation of attribute value changes into a new change set.
	bind(id, name, model, integration, isDefault) Binds this controller to a particular property collection in the model layer.
	constructor(params) Creates a pvr.controller.PropertyCollectionController object.
	endChangeSet() Completes the accumulation of attribute value changes for the current change set and queues the appropriate set of change events.
	everyPropertyController(options) Calls the specified callback function for the pvr.controller._PropertyController objects included by the options.
	forEachPropertyController(options) Processes each of the pvr.controller._PropertyController objects included by the options.
	getData(options) Returns an object that includes the values of all attributes for all properties in any of the default collections as specified by the options.
	getPropertyController(collectionId, id) Gets the specified property controller from the specified property collection.
	getPropertyControllers(options) Returns the pvr.controller._PropertyController objects included by the options.
	getSettings(options) Returns an object that includes the values of all attributes for all properties in any of the collections as specified by the options.
	isModified(after) Indicates whether the "value" attribute of any property was modified after the specified time.
	mapPropertyController(options) Creates a new array by processing the pvr.controller._PropertyController objects included by the options.
	onChange(changes) Called when processing a change set to report all changes to any property in any of the collections.
	onUpdate(changes) Called when processing a change set to report all changes to any property in any of the default collections.
	resetModified() Resets the modified state of every property.
	somePropertyController(options) Calls the specified callback function for the pvr.controller._PropertyController objects included by the options.
	unbind(id) Releases the binding of a particular property collection in the model layer.
	validate() Validates the property collections and returns an array of pvr.controller._PropertyController objects that failed validation.

Methods borrowed from class pvr.logging._LoggerMixin:: logDebug, logEntry, logError, logExit, logInfo, logWarning

Constructor Detail

pvr.controller.PropertyCollectionController()

Field Detail

{object} collections

The property collections supported by this controller.

{string} context

Indicates the context for this controller. Can be "design" or "runtime".

Method Detail

beginChangeSet()

Begins the accumulation of attribute value changes into a new change set.

You can call the pvr.controller.PropertyCollectionController#beginChangeSet and pvr.controller.PropertyCollectionController#endChangeSet methods to batch multiple operations into a single change set. Calls to these methods can be nested but must occur in pairs to ensure the proper completion of the changeset that takes place during the outermost call to the pvr.controller.PropertyCollectionController#endChangeSet method.

The following code illustrates the use of these methods to group a batch of changes into a single change set.

controller.startChangeSet();
controller.getPropertyController("collection1.prop1").set("value", "foo");
controller.getPropertyController("collection1.prop2").set("value", "bar");
controller.getPropertyController("collection2.prop1").set("hidden", true);
controller.getPropertyController("collection2.prop2").set("required", true);
controller.endChangeSet();

bind(id, name, model, integration, isDefault)

Binds this controller to a particular property collection in the model layer.

For each call to pvr.controller.PropertyCollectionController#bind there must be a matching call to pvr.controller.PropertyCollectionController#unbind.

Parameters:
id: The identifier for the property collection.
name: The display name for the property collection.
model: The associated model object.
integration: The pvr.controller.integration.Integration object that directs the binding of the controller to the model object. If not specified a default pvr.controller.integration.Integration object will be created.
isDefault: A Boolean value that indicates whether this is default property collection. This value is false by default and should generally be false unless you are dealing with a legacy application.

constructor(params)

Creates a pvr.controller.PropertyCollectionController object.

Parameters:
params: The parameters for this controller.
params.context: Indicates the context for this controller. Can be "design" or "runtime".

endChangeSet()

Completes the accumulation of attribute value changes for the current change set and queues the appropriate set of change events.

everyPropertyController(options)

Calls the specified callback function for the pvr.controller._PropertyController objects included by the options. Returns true if the callback function returns true for every pvr.controller._PropertyController object. Returns false and aborts on the first callback function that return false.

Parameters:
options: The options.
options.callback: The callback function to be called for each pvr.controller._PropertyController object that meets the criteria specified by the other options. The callback should return true if the processing should continue or false to abort the processing. (required)
options.collectionId: The identifier(s) for property collections that should be included. If unspecified, then properties from all property collections are included. (optional)
options.propertyIds: An array of binding references for each property to be be included. (optional)
options.filter: A filter function that indicates which properties should be included. (optional)
options.comparator: A comparator function that provides the sort order of the properties included. (optional)

Returns:: true if the callback function returns true for every pvr.controller._PropertyController object.

forEachPropertyController(options)

Processes each of the pvr.controller._PropertyController objects included by the options.

Parameters:
options: The options.
options.callback: The callback function to be called for each pvr.controller._PropertyController object that meets the criteria specified by the other options. (required)
options.collectionId: The identifier(s) for property collections that should be included. If unspecified, then properties from all property collections are included. (optional)
options.propertyIds: An array of binding references for each property to be be included. (optional)
options.filter: A filter function that indicates which properties should be included. (optional)
options.comparator: A comparator function that provides the sort order of the properties included. (optional)

getData(options)

Returns an object that includes the values of all attributes for all properties in any of the default collections as specified by the options.

You can provide options to control which properties are included in the result. All options are supported except the callback. See pvr.controller.PropertyCollectionController#forEachPropertyController for more information about the supported options.

Parameters:
options: The options.

Deprecated:: Use the pvr.controller.PropertyCollectionController#getSettings method instead.

Returns:: The object that includes the attribute values.

getPropertyController(collectionId, id)

Gets the specified property controller from the specified property collection.

This method is overloaded to support references that include both the property collection identifier and the property identifier and for backward compatibility with solutions that provide only the property identifier. The following method signatures are supported. If the property collection identifier is not specified, then only default property collections are searched.

getPropertyController(collectionId, propertyId)
getPropertyController(bindingReference)
getPropertyController({
	collectionId: collectionId,
	id: propertyId
})
getPropertyController(propertyId)

Parameters:
collectionId: The identifier for the property collection.
id: The identifier for the property.

Returns:: The associated pvr.controller._PropertyController object.

getPropertyControllers(options)

Returns the pvr.controller._PropertyController objects included by the options.

Parameters:
options: The options.
options.collectionId: The identifier(s) for property collections that should be included. If unspecified, then properties from all property collections are included. (optional)
options.propertyIds: An array of binding references for each property to be be included. (optional)
options.filter: A filter function that indicates which properties should be included. (optional)
options.comparator: A comparator function that provides the sort order of the properties included. (optional)

Returns:: The array of pvr.controller._PropertyController objects.

getSettings(options)

Returns an object that includes the values of all attributes for all properties in any of the collections as specified by the options.

Parameters:
options: The options.

Returns:: The object that includes the attribute values.

isModified(after)

Indicates whether the "value" attribute of any property was modified after the specified time. If a time is not specified, then all changes are considered.

Parameters:
after: A JavaScript Date object providing the specified time.

Returns:: true if the "value" attribute of any property was modified.

mapPropertyController(options)

Creates a new array by processing the pvr.controller._PropertyController objects included by the options.

Parameters:
options: The options.
options.callback: The callback function to be called for each pvr.controller._PropertyController object that meets the criteria specified by the other options. The callback returns the corresponding value for the new array. (required)
options.collectionId: The identifier(s) for property collections that should be included. If unspecified, then properties from all property collections are included. (optional)
options.propertyIds: An array of binding references for each property to be be included. (optional)
options.filter: A filter function that indicates which properties should be included. (optional)
options.comparator: A comparator function that provides the sort order of the properties included. (optional)

Returns:: The new array.

onChange(changes)

Called when processing a change set to report all changes to any property in any of the collections.

You may handle this event to be notified of any changes to any property. View widgets will also handle this event to update their state.

Parameters:
changes: An object that includes all changes for each affected property.

onUpdate(changes)

Called when processing a change set to report all changes to any property in any of the default collections.

Only those properties in default collections are included.

Parameters:
changes: An object that includes all changes for each affected property.

Deprecated:: Handle the pvr.controller.PropertyCollectionController#onChange event instead.

resetModified()

Resets the modified state of every property.

somePropertyController(options)

Calls the specified callback function for the pvr.controller._PropertyController objects included by the options. Returns true and aborts on the first callback function that returns true for any pvr.controller._PropertyController object. Returns false otherwise.

Parameters:
options: The options.
options.callback: The callback function to be called for each pvr.controller._PropertyController object that meets the criteria specified by the other options. The callback should return true to abort the processing or false if the processing should continue. (required)
options.collectionId: The identifier(s) for property collections that should be included. If unspecified, then properties from all property collections are included. (optional)
options.propertyIds: An array of binding references for each property to be be included. (optional)
options.filter: A filter function that indicates which properties should be included. (optional)
options.comparator: A comparator function that provides the sort order of the properties included. (optional)

Returns:: true if the callback function returns true for any pvr.controller._PropertyController object.

unbind(id)

Releases the binding of a particular property collection in the model layer.

For each call to pvr.controller.PropertyCollectionController#bind there must be a matching call to pvr.controller.PropertyCollectionController#unbind.

Parameters:
id: The identifier for the property collection. If unspecified, then all property collections bindings are released.

validate()

Validates the property collections and returns an array of pvr.controller._PropertyController objects that failed validation.

An empty array indicates that all the property values are valid.

Returns:: The array of invalid properties.