Docs For Class WFArrayController

Class WFArrayController

Description

Implements interfaces:

Iterator (internal interface)

The ArrayController class.

This is the Controller Layer object for managing arrays.

In Cocoa, the NSArrayController manages selection by index. They can do this because in the desktop world, once you've set up your array, it stays around forever. Thus when the user changes a textfield bound to the nth item in the array, it's simple to lookup the nth item and call the setValueForKey method on the nth item. However in the HTTP world (especially stateless PHP) we have to re-build or array each request. Thus, the nth item when you DREW the textfield might not be the nth item when you're pushing the new value from the text field back to the object!

So, our WFArrayController has some extra magic to help with this problem. First off, arrays in PHP are different than NSArrays in that they are a blending of an array and a dictionary. Since we always have associative arrays to work with, our WFArrayController will manage its content more as a dictionary and less as an array. Also, the selection will be managed by keeping a list of selected keys rather than indexes. What key will be used? Well, the WFArrayController also has an identifier property, which allows you to control which key(s) of the managed class is used for the selected keys. By default, the identifier property is WFArrayController::USE_ARRAY_INDEXES_AS_ID, which is a special flag to actually use numeric indexing. This way, the WFArrayController will act very similarly to a NSArrayController.

However, if you want the WFArrayController to manage your objects by ID, then you can set the identifier to another list of key(s).

see: WFKeyValueCoding
see: WFKeyValueBindingCreation
todo: Should there be a "canSelectMultiple" setting? This was if you're using it in a Master-Detail interface it'd be easier to manage the selection? In this case a combo of selectOnInsert and addObject would make it easy to managed. NO! This is an attribute of the "matrix" widget, not the controller. ArrayController should always be "on" for multiple selections.
todo: Upgrade to cocoa-compatible defaults DONE! avoidsEmptySelection TRUE - ADD this function DONE! selectsInsertedObjects TRUE - deprecate selectOnInsert, but keep func for BC. WE will keep our FALSE because it makes more sense. Something is wrong with #arrayIndexes# mode I think... see todo's (not yet implemented) preservesSelection TRUE
todo: Normalize property names. Keep naming convention; properties should read like "class property -> WFArrayController selectsInsertedObjects"

Located in /framework/WFArrayController.php (line 41)

WFObject
   |
   --WFObjectController
      |
      --WFArrayController

Class Constant Summary

ID_DELIMITER = '|'

USE_ARRAY_INDEXES_AS_ID = '#arrayIndexes#'

Variable Summary

boolean $avoidsEmptySelection

int $changeCount

array $classIdentifiers

boolean $classIdentifiersMulti

int $iteratorIndex

int $iteratorObjects

array $selectedIdentifiersHash

boolean $selectsInsertedObjects

boolean $usingIndexedMode

Method Summary

WFArrayController __construct ()

void addObject (object An $obj)

void addObjects (array $arr)

void addSelectedObject (object An $obj)

void addSelectedObjects (array $objs)

void addSelectionIdentifiers (array $idsToAdd)

integer arrangedObjectCount ()

array arrangedObjects ()

void avoidsEmptySelection ()

void changeCount ()

void classIdentifiers ()

void clearSelection ()

void cullSelectedObjects ()

void cullUnselectedObjects ()

void current ()

boolean hashIsSelected (string $hash)

string identifierHashForObject (object An $obj)

Given identifierHashForValues (mixed $id)

boolean identifierIsSelected (mixed $id)

void identifierValuesForHash ( $hash)

mixed identifierValuesForObject (object An $obj)

object The insert ()

void key ()

void next ()

object NULL objectForIdentifier (mixed $identifier)

boolean objectIsSelected (object mixed $obj)

void prepareContent ()

void removeObject (object WFObject $obj)

void removeSelectionIdentifiers (array $idsToRemove)

void rewind ()

An selectedObjects ()

object The selection ()

integer selectionCount ()

array selectionIdentifiers ()

void selectsInsertedObjects ()

void setAvoidsEmptySelection (boolean $bool)

void setClassIdentifiers (mixed $id)

void setContent (mixed $arr)

void setSelectionIdentifiers (array $idsToSelect)

void setSelectOnInsert ( $bool)

void setSelectsInsertedObjects (boolean $bool)

void usingIndexedMode ()

void valid ()

Variables

boolean $avoidsEmptySelection (line 69)

var: TRUE If you want there to always be at least one selected object. Will always keep at least one object selected unless there are no arranged objects.
access: protected

int $changeCount (line 83)

var: An integer which increments with each change. Used by WFDynamic to see if it needs to re-call createWidgets. Eventually will be replaced by observing.
access: protected

array $classIdentifiers (line 49)

var: An array of identifier key(s) to use on the managed class. By default, this is array(WFArrayController::USE_ARRAY_INDEXES_AS_ID). Will be array(id) or array(id1,id2).
access: protected

boolean $classIdentifiersMulti (line 61)

var: Does the controlled class use mutli-key ids?
access: protected

int $iteratorIndex (line 74)

var: Iterator index, for the Iterator interface.
access: protected

int $iteratorObjects (line 78)

var: Iterator object list, for the Iterator interface.
access: protected

array $selectedIdentifiersHash (line 57)

var: An array of all selected Identifiers. Format is [idHash] => 1. This prevents accidentally having the same selection in the list twice.
access: protected

boolean $selectsInsertedObjects (line 65)

var: TRUE if all objects should be added to the selection upon adding them to the content. This is useful if you want all objects to be selected by default.
access: protected

boolean $usingIndexedMode (line 53)

var: Are we using WFArrayController::USE_ARRAY_INDEXES_AS_ID?
access: protected

Inherited Variables

Inherited from WFObjectController

WFObjectController::$automaticallyPreparesContent
WFObjectController::$class
WFObjectController::$content
WFObjectController::$decorators

Methods

Constructor __construct (line 85)

WFArrayController __construct ()

Redefinition of:

WFObjectController::__construct()

addObject (line 401)

Add an object to the array.

throws: If the object is not of the class managed by our controller.

void addObject (object An $obj)

object An $obj: object, must be of proper class.

addObjects (line 439)

Add multiple objects to the array.

throws: If any object is not of the class managed by our controller.

void addObjects (array $arr)

array $arr: Array of objects, must be of proper class.

addSelectedObject (line 673)

Add the passed object to the selection, if it exists in our array.

NOTE that this does NOT add the object to the arrayController's content, simply marks the passed object as selected.

throws: If any object is not of the class managed by our controller.

void addSelectedObject (object An $obj)

object An $obj: object of the class we manage.

addSelectedObjects (line 658)

Add the passed objects to the selection, if each exists in our array.

Simply calls addSelectedObject for each item in the passed array.

NOTE that this does NOT add the object to the arrayController's content, simply marks the passed object as selected.

throws: If any object is not of the class managed by our controller.

void addSelectedObjects (array $objs)

array $objs: An array of objects of the class we manage.

addSelectionIdentifiers (line 606)

Add the passed ids to the selected list.

throws: WFException if the passed parameter is not an array.

void addSelectionIdentifiers (array $idsToAdd)

array $idsToAdd: An array of ids: array(1,2). The ids, if they are multi-key ids, should be passed as array(array(1,2),array(1,3)).

arrangedObjectCount (line 595)

Get the count of the managed objects.

return: The number of items.

integer arrangedObjectCount ()

arrangedObjects (line 474)

Get all of the objects managed by this controller.

return: An array (numerically indexed, not by classIdentifier) of all of the objects we're managing.

array arrangedObjects ()

avoidsEmptySelection (line 136)

void avoidsEmptySelection ()

changeCount (line 98)

void changeCount ()

classIdentifiers (line 141)

void classIdentifiers ()

clearSelection (line 554)

Clear all selected items.

void clearSelection ()

cullSelectedObjects (line 373)

Remove all selected objects from the array controller.

throws: WFException

void cullSelectedObjects ()

cullUnselectedObjects (line 386)

Remove all unselected objects from the array controller.

throws: WFException

void cullUnselectedObjects ()

current (line 733)

Iterator interface for WFArrayController.

void current ()

Implementation of:

Iterator::current

hashIsSelected (line 524)

Determine if an object is currently selected based on its hash.

return: TRUE if selected, FALSE otherwise.

boolean hashIsSelected (string $hash)

string $hash: The hash for the object (from {$link identifierHashForObject}).

identifierHashForObject (line 264)

Get a single string ID key for the passed object.

return: A string with the unique identifier hash for the passed object.

string identifierHashForObject (object An $obj)

object An $obj: object instance of the class managed by this instance of WFArrayController.

identifierHashForValues (line 208)

Convert the passed id or id list into a single-string-id-key.

return: an array, will return a string containing all Identifiers joined by WFArrayController::ID_DELIMITER. Given a string or integer, will just return the string (this is the usual case for single-key ids).

Given identifierHashForValues (mixed $id)

mixed $id: ID information, either an array or a string/integer.

identifierIsSelected (line 197)

Is the given identifier selected in the array?

throws: object WFException

boolean identifierIsSelected (mixed $id)

mixed $id: ID information, either an array or a string/integer.

identifierValuesForHash (line 221)

void identifierValuesForHash ( $hash)

$hash

identifierValuesForObject (line 239)

Get an array of the values for the classIdentifiers for the object.

return: If multi-key, return an array of values for the classIdentifiers of our object, in order. If single-key, returns the value.
throws: If usingIndexedMode or the object is not of the class managed by our controller.

mixed identifierValuesForObject (object An $obj)

object An $obj: object of the class managed by our WFArrayController.

insert (line 304)

Insert a new instance of the managed class at the end of the contentArray.

NOTE: insert() requires that the value of WFArrayController::$class is a class, not an interface.

return: new object.

object The insert ()

key (line 741)

Iterator interface for WFArrayController.

void key ()

Implementation of:

Iterator::key

next (line 725)

Iterator interface for WFArrayController.

void next ()

Implementation of:

Iterator::next

objectForIdentifier (line 288)

Get the object specified by the passed identifier.

return: if the object doesn't exist, the object otherwise.

object NULL objectForIdentifier (mixed $identifier)

mixed $identifier: The identifier for the object to retrieve. A single ID or array(id1, id2).

objectIsSelected (line 505)

Determine if an object is currently selected.

This is a convenient and fast way to determine if an object is selected in the array controller. Useful if you're iterating the "arrangedObjects" and want to see if an item is selected.

return: TRUE if selected, FALSE otherwise.
throws: If the passed item is not an object, or not an object that is managed by this array controller instance.

boolean objectIsSelected (object mixed $obj)

object mixed $obj: The object to test. Should be of the same class as managed by this arrayController instance.

prepareContent (line 273)

Prepare the controller's content.

Basically, this will make sure that the array contains an instance. If one doesn't, a new instance of the class will be created and added to the array.

access: protected

void prepareContent ()

Redefinition of:

WFObjectController::prepareContent(): Prepare the controller's content.

removeObject (line 324)

Remove the passed object from the array.

Also obvioulsy removes the item from the selection.

NOTE: presently this works in non-indexed mode only.

NOTE: UNTESTED!!!

throws: WFException For various circumstances like invalid parameter, couldn't find object, etc.

void removeObject (object WFObject $obj)

object WFObject $obj: An object of the proper class managed by the array controller.

removeSelectionIdentifiers (line 631)

Remove the passed objects from the arrayController's selection.

see: WFArrayController::identifierHashForObject(), WFArrayController::identifierHashForValues()
throws: WFException if the passed parameter is not an array.

void removeSelectionIdentifiers (array $idsToRemove)

array $idsToRemove: An array of hashes of the objects to be removed: array(1,2). Hashes are string for both single and multi-key arrays.

rewind (line 708)

Iterator interface for WFArrayController.

void rewind ()

Implementation of:

Iterator::rewind

selectedObjects (line 485)

Get an array with the selected objects.

return: array containing the selected objects, or an empty array if there is no selection.

An selectedObjects ()

Redefinition of:

WFObjectController::selectedObjects(): Get an array with the selected objects.

selection (line 695)

Get the selected object, or NULL if no objects are selected.

return: seleted object, if there is one object selected; NULL if there is no selection, and throws an exception if there are multiple items selected.
throws: WFException If multiple objects are selected.

object The selection ()

Redefinition of:

WFObjectController::selection()

selectionCount (line 586)

Get the count of the selection.

return: The number of selected items.

integer selectionCount ()

selectionIdentifiers (line 566)

Return a list of the IDs of all selected objects.

return: An array of identifier values for all selected objects. If your classIdentifiers is a single item, then it will be an array of values: array(1,2). If your classIdentifiers is multi-key, then it will be an array of arrays: array( array(1,2), array(1,3) )

array selectionIdentifiers ()

selectsInsertedObjects (line 113)

void selectsInsertedObjects ()

setAvoidsEmptySelection (line 131)

If true, the array controller will always make sure that there is at least one object selected, as long as the array controller isn't empty.

void setAvoidsEmptySelection (boolean $bool)

boolean $bool

setClassIdentifiers (line 161)

Set the id key(s) used to generate Identifiers for the managed objects.

For instance, if the WFArrayController's class is Person, maybe you'd pass 'uid'. If the WFArrayController's class is MyTwoColumnPKObject, you'd pass array('col1', 'col2').

NOTE: calling this function resets the selection to EMPTY since the previous id's are no longer valid.

void setClassIdentifiers (mixed $id)

mixed $id: The ID key(s) to use. If it's an array, it should be an array of strings. The managed object should be KVC compliant for the passed keys. If it's a string, the managed object should be KVC compliant for that key.

setContent (line 455)

Pass an array of objects to use for this array.

Simply clears the current content and selection, then calls addObjects.

throws: If any object is not of the class managed by our controller.

void setContent (mixed $arr)

mixed $arr: Array or object - An array of objects of the proper class. Or an object of the proper class. If you pass an object the entire contents of the WFArrayController will be replaced with that single object.

Redefinition of:

WFObjectController::setContent(): Set the content managed by this controller instance.

setSelectionIdentifiers (line 540)

Set the selected items of the array.

Note: this will CLEAR the existing setting, and only the passed ids will be selected. To ADD to a selection, addSelectionIdentifiers.

void setSelectionIdentifiers (array $idsToSelect)

array $idsToSelect: An array of ids: array(1,2). The ids, if they are multi-key ids, should be passed as array(array(1,2), array(1,3)).

setSelectOnInsert (line 121)

deprecated: Use setSelectsInsertedObjects

void setSelectOnInsert ( $bool)

$bool

setSelectsInsertedObjects (line 108)

If true, the array controller will automatically add all objects inserted to the selection.

void setSelectsInsertedObjects (boolean $bool)

boolean $bool

usingIndexedMode (line 146)

void usingIndexedMode ()

valid (line 717)

Iterator interface for WFArrayController.

void valid ()

Implementation of:

Iterator::valid

Inherited Methods

Inherited From WFObjectController

WFObjectController::__construct()
WFObjectController::checkObjectClass()
WFObjectController::content()
WFObjectController::decorateObject()
WFObjectController::prepareContent()
WFObjectController::selectedObjects()
WFObjectController::selection()
WFObjectController::setAutomaticallyPreparesContent()
WFObjectController::setClass()
WFObjectController::setContent()
WFObjectController::setDecorator()
WFObjectController::setDecorators()
WFObjectController::undecorateObject()

Inherited From WFObject

WFObject::__construct()
WFObject::exposedProperties()
WFObject::getClass()
WFObject::keyPathToTargetAndKey()
WFObject::setValueForKey()
WFObject::setValueForKeyPath()
WFObject::setValuesForKeys()
WFObject::validatedSetValueForKey()
WFObject::validatedSetValueForKeyPath()
WFObject::validateObject()
WFObject::validateValueForKey()
WFObject::validateValueForKeyPath()
WFObject::valueForKey()
WFObject::valueForKeyPath()
WFObject::valueForStaticKey()
WFObject::valueForStaticKeyPath()
WFObject::valueForTargetAndKeyPath()
WFObject::valueForUndefinedKey()
WFObject::valueForUndefinedStaticKey()
WFObject::valuesForKeyPaths()
WFObject::valuesForKeys()
WFObject::_valueForStaticKey()
WFObject::__toString()

Class Constants

ID_DELIMITER = '|' (line 44)

USE_ARRAY_INDEXES_AS_ID = '#arrayIndexes#' (line 43)

Documentation generated on Thu, 14 May 2009 16:19:45 -0400 by phpDocumentor 1.4.2