Class DataTree

Description

The DataTree:: class provides a common abstracted interface into the various backends for the Horde DataTree system.

A piece of data is just a title that is saved in the page for the null driver or can be saved in a database to be accessed from everywhere. Every stored object must have a different name (inside each groupid).

Required values for $params:

   'group' -- Define each group of objects we want to build.

Copyright 1999-2009 The Horde Project (http://www.horde.org/)

See the enclosed file COPYING for license information (LGPL). If you did not receive this file, see http://www.fsf.org/copyleft/lgpl.html.

Located in /DataTree/DataTree.php (line 48)


	
			
Direct descendents
Class Description
 class DataTree_null The DataTree_null:: class provides a dummy implementation of the DataTree:: API; no data will last beyond a single page request.
 class DataTree_sql The DataTree_sql:: class provides an SQL implementation of the Horde DataTree system.
Variable Summary
 array $_data
 array $_nameMap
 array $_params
 array $_sortHash
Method Summary
 static string getShortName (string $name)
 DataTree DataTree ([array $params = array()])
 TODO add (mixed $object, [boolean $id_as_name = false])
 integer count ([string $startleaf = DATATREE_ROOT])
 TODO countByAttributes (array $criteria, [string $parent = DATATREE_ROOT], [boolean $allLevels = true], [string $restrict = 'name'])
 string encodeName (string $name)
 boolean exists (mixed $object)
 DataTree &factory (mixed $driver, [array $params = null])
 mixed get (constant $format, [string $startleaf = DATATREE_ROOT], [boolean $reload = false], [string $rootname = DATATREE_ROOT], [integer $maxdepth = -1], [boolean $loadTree = false], [string $sortby_name = null], [string $sortby_key = null], [integer $direction = 0])
 array getAttributes (integer $cid)
 TODO getByAttributes (array $criteria, [string $parent = DATATREE_ROOT], [boolean $allLevels = true], [string $restrict = 'name'], [integer $from = 0], [integer $count = 0], [string $sortby_name = null], [string $sortby_key = null], [integer $direction = 0])
 mixed getById (constant $format, [string $startleaf = DATATREE_ROOT], [boolean $reload = false], [string $rootname = DATATREE_ROOT], [integer $maxdepth = -1])
 TODO getData (integer $cid)
 mixed getGroups ()
 string getId (mixed $name)
 string getName (integer $id)
 integer getNumberOfChildren ([mixed $parent = DATATREE_ROOT])
 TODO &getObject (string $object, [string $class = 'DataTreeObject'])
 TODO &getObjectById (integer $id, [string $class = 'DataTreeObject'])
 TODO &getObjects (array $ids, [string $class = 'DataTreeObject'])
 mixed getOrder (mixed $child)
 mixed getParam (string $param)
 mixed getParent (mixed $child)
 mixed getParentById (integer $childId)
 string|PEAR_Error getParentIdString (mixed $object)
 array getParentList (integer $childId, [array $parents = array()])
 mixed getParents (mixed $child, [boolean $getids = false])
 array getSortedTree (string $root, [boolean $loadTree = false], [string $sortby_name = null], [string $sortby_key = null], [integer $direction = 0])
 mixed move (mixed $object, [string $newparent = null])
 TODO remove (string $object, [boolean $force = false])
 TODO removeUserData (string $user)
 mixed rename (mixed $old_object, string $new_object_name)
 TODO reorder ( $parents, [mixed $order = null], [integer $cid = null], string $parent)
 TODO set (array $data, [string $charset = null])
 TODO setOrder (integer $id, integer $order)
 DataTree &singleton (mixed $driver, [array $params = null])
 array sortByAttributes (array $unordered_ids, [array $sortby_name = null], [array $sortby_key = null], [array $direction = 0])
 string sortHash (string $root, [string $sortby_name = null], [string $sortby_key = null], [integer $direction = 0])
 TODO updateData (DataTree $object)
 TODO _add (string $name, integer $id, integer $pid, [integer $order = ''])
 integer _cmp (array $a, array $b)
 integer _cmpSorted (array $a, array $b)
 TODO _defineObjectClass (array $attributes)
 array _extractOneLevel ([string $leaf = DATATREE_ROOT])
 void _reorder (string $pid, [mixed $order = null], [integer $cid = null])
Variables
array $_data = array() (line 56)

Array of all data: indexed by id. The format is: array(id => 'name' => name, 'parent' => parent).

array $_nameMap = array() (line 64)

A hash that can be used to map a full object name (parent:child:object) to that object's unique ID.

array $_params = array() (line 78)

Hash containing connection parameters.

array $_sortHash = null (line 71)

Actual attribute sorting hash.

Methods
static getShortName (line 1081)

Get the short name of an object, returns only the last portion of the full name. For display purposes only.

  • return: The object's short name.
static string getShortName (string $name)
  • string $name: The name of the object.
Constructor DataTree (line 88)

Constructor.

DataTree DataTree ([array $params = array()])
  • array $params: A hash containing any additional configuration or connection parameters a subclass might need. We always need 'group', a string that defines the prefix for each set of hierarchical data.
add (line 1132)

Adds an object.

  • abstract:
TODO add (mixed $object, [boolean $id_as_name = false])
  • mixed $object: The object to add (string or DataTreeObject).
  • boolean $id_as_name: True or false to indicate if object ID is to be used as object name. Used in situations where there is no available unique input for object name.

Redefined in descendants as:
count (line 558)

Counts objects.

  • return: The number of the objects below $startleaf.
integer count ([string $startleaf = DATATREE_ROOT])
  • string $startleaf: The name of the leaf from which we start counting.
countByAttributes (line 1197)

Returns the number of objects matching a set of attribute criteria.

  • see: buildAttributeQuery()
  • abstract:
TODO countByAttributes (array $criteria, [string $parent = DATATREE_ROOT], [boolean $allLevels = true], [string $restrict = 'name'])
  • array $criteria: The array of criteria.
  • string $parent: The parent node to start searching from.
  • boolean $allLevels: Return all levels, or just the direct children of $parent? Defaults to all levels.
  • string $restrict: Only return attributes with the same attribute_name or attribute_id.

Redefined in descendants as:
encodeName (line 1066)

Replace all occurences of ':' in an object name with '.'.

  • return: The encoded name.
string encodeName (string $name)
  • string $name: The name of the object.
exists (line 946)

Check if an object exists or not. The root element DATATREE_ROOT always exists.

  • return: True if the object exists, false otherwise.
boolean exists (mixed $object)
  • mixed $object: The name of the object.
factory (line 1335)

Attempts to return a concrete DataTree instance based on $driver.

  • return: The newly created concrete DataTree instance, or false on an error.
DataTree &factory (mixed $driver, [array $params = null])
  • mixed $driver: The type of concrete DataTree subclass to return. This is based on the storage driver ($driver). The code is dynamically included. If $driver is an array, then we will look in $driver[0]/lib/DataTree/ for the subclass implementation named $driver[1].php.
  • array $params: A hash containing any additional configuration or connection parameters a subclass might need. Here, we need 'group' = a string that defines top-level groups of objects.
get (line 501)

Export a list of objects.

  • return: The tree representation of the objects, or a PEAR_Error on failure.
mixed get (constant $format, [string $startleaf = DATATREE_ROOT], [boolean $reload = false], [string $rootname = DATATREE_ROOT], [integer $maxdepth = -1], [boolean $loadTree = false], [string $sortby_name = null], [string $sortby_key = null], [integer $direction = 0])
  • constant $format: Format of the export
  • string $startleaf: The name of the leaf from which we start the export tree.
  • boolean $reload: Re-load the requested chunk? Defaults to false (only what is currently loaded).
  • string $rootname: The label to use for the root element. Defaults to DATATREE_ROOT.
  • integer $maxdepth: The maximum number of levels to return. Defaults to DATATREE_ROOT, which is no limit.
  • boolean $loadTree: Load a tree starting at $root, or just the requested level and direct parents? Defaults to single level.
  • string $sortby_name: Attribute name to use for sorting.
  • string $sortby_key: Attribute key to use for sorting.
  • integer $direction: Sort direction:
    1. - ascending
    2. - descending
getAttributes (line 1176)

Retrieve data for an object from the horde_datatree_attributes table.

  • return: A hash of attributes, or a multi-level hash of object ids => their attributes.
  • abstract:
array getAttributes (integer $cid)
  • integer $cid: | array $cid The object id to fetch, or an array of object ids.

Redefined in descendants as:
getByAttributes (line 1226)

Returns a set of object ids based on a set of attribute criteria.

  • see: buildAttributeQuery()
  • abstract:
TODO getByAttributes (array $criteria, [string $parent = DATATREE_ROOT], [boolean $allLevels = true], [string $restrict = 'name'], [integer $from = 0], [integer $count = 0], [string $sortby_name = null], [string $sortby_key = null], [integer $direction = 0])
  • array $criteria: The array of criteria.
  • string $parent: The parent node to start searching from.
  • boolean $allLevels: Return all levels, or just the direct children of $parent? Defaults to all levels.
  • string $restrict: Only return attributes with the same attribute_name or attribute_id.
  • integer $from: The object to start to fetching
  • integer $count: The number of objects to fetch
  • string $sortby_name: Attribute name to use for sorting.
  • string $sortby_key: Attribute key to use for sorting.
  • integer $direction: Sort direction:
    1. - ascending
    2. - descending

Redefined in descendants as:
getById (line 601)

Export a list of objects just like get() above, but uses an object id to fetch the list of objects.

  • return: The tree representation of the objects, or a PEAR_Error on failure.
mixed getById (constant $format, [string $startleaf = DATATREE_ROOT], [boolean $reload = false], [string $rootname = DATATREE_ROOT], [integer $maxdepth = -1])
  • constant $format: Format of the export.
  • string $startleaf: The id of the leaf from which we start the export tree.
  • boolean $reload: Reload the requested chunk? Defaults to false (only what is currently loaded).
  • string $rootname: The label to use for the root element. Defaults to DATATREE_ROOT.
  • integer $maxdepth: The maximum number of levels to return Defaults to -1, which is no limit.
getData (line 647)

Retrieve data for an object from the datatree_data field.

  • abstract:
TODO getData (integer $cid)
  • integer $cid: The object id to fetch, or an array of object ids.

Redefined in descendants as:
getGroups (line 633)

Returns a list of all groups (root nodes) of the data tree.

  • return: The group IDs or PEAR_Error on error.
  • abstract:
mixed getGroups ()

Redefined in descendants as:
getId (line 1007)

Get the id of an object from its name.

string getId (mixed $name)
  • mixed $name: Either the object, an array containing the path elements, or the object name for which to look up the id.
getName (line 977)

Get the name of an object from its id.

  • return: TODO
string getName (integer $id)
  • integer $id: The id for which to look up the name.
getNumberOfChildren (line 927)

Get the number of children an object has, only counting immediate children, not grandchildren, etc.

integer getNumberOfChildren ([mixed $parent = DATATREE_ROOT])
  • mixed $parent: Either the object or the name for which to count the children, defaults to the root (DATATREE_ROOT).
getObject (line 336)

Returns a DataTreeObject (or subclass) object of the data in the object defined by $object.

TODO &getObject (string $object, [string $class = 'DataTreeObject'])
  • string $object: The object to fetch: 'parent:sub-parent:name'.
  • string $class: Subclass of DataTreeObject to use. Defaults to DataTreeObject. Null forces the driver to look into the attributes table to determine the subclass to use. If none is found it uses DataTreeObject.
getObjectById (line 365)

Returns a DataTreeObject (or subclass) object of the data in the object with the ID $id.

TODO &getObjectById (integer $id, [string $class = 'DataTreeObject'])
  • integer $id: An object id.
  • string $class: Subclass of DataTreeObject to use. Defaults to DataTreeObject. Null forces the driver to look into the attributes table to determine the subclass to use. If none is found it uses DataTreeObject.
getObjects (line 434)

Returns an array of DataTreeObject (or subclass) objects corresponding to the objects in $ids, with the object names as the keys of the array.

TODO &getObjects (array $ids, [string $class = 'DataTreeObject'])
  • array $ids: An array of object ids.
  • string $class: Subclass of DataTreeObject to use. Defaults to DataTreeObject. Null forces the driver to look into the attributes table to determine the subclass to use. If none is found it uses DataTreeObject.
getOrder (line 1043)

Get the order position of an object.

  • return: The object's order position or a PEAR error on failure.
mixed getOrder (mixed $child)
  • mixed $child: Either the object or the name.
getParam (line 100)

Returns a parameter of this DataTree instance.

  • return: The parameter's value or null if it doesn't exist.
mixed getParam (string $param)
  • string $param: The parameter to return.
getParent (line 811)

Returns a child's direct parent ID.

  • return: The unique ID of the parent or PEAR_Error on error.
mixed getParent (mixed $child)
  • mixed $child: Either the object, an array containing the path elements, or the object name for which to look up the parent's ID.
getParentById (line 830)

Get a $child's direct parent ID.

  • return: The unique ID of the parent or PEAR_Error on error.
mixed getParentById (integer $childId)
  • integer $childId: Get the parent of this object.
getParentIdString (line 901)

Get a parent ID string (id:cid format) for the specified object.

  • return: The ID "path" to the parent object or PEAR_Error on failure.
string|PEAR_Error getParentIdString (mixed $object)
  • mixed $object: The object to return a parent string for.
getParentList (line 878)

Get a list of parents all the way up to the root object for $child.

  • return: A flat list of all of the parents of $child, hashed in $id => $name format.
array getParentList (integer $childId, [array $parents = array()])
  • integer $childId: The id of the child.
  • array $parents: The array, as we build it up.
getParents (line 848)

Get a list of parents all the way up to the root object for $child.

  • return: [child] [parent] in a tree format or PEAR_Error.
mixed getParents (mixed $child, [boolean $getids = false])
  • mixed $child: The name of the child
  • boolean $getids: If true, return parent IDs; otherwise, return names.
getSortedTree (line 1112)

Returns a tree sorted by the specified attribute name and/or key.

  • return: TODO
  • abstract:
  • since: Horde 3.1
array getSortedTree (string $root, [boolean $loadTree = false], [string $sortby_name = null], [string $sortby_key = null], [integer $direction = 0])
  • string $root: Which portion of the tree to sort. Defaults to all of it.
  • boolean $loadTree: Sort the tree starting at $root, or just the requested level and direct parents? Defaults to single level.
  • string $sortby_name: Attribute name to use for sorting.
  • string $sortby_key: Attribute key to use for sorting.
  • integer $direction: Sort direction:
    1. - ascending
    2. - descending

Redefined in descendants as:
move (line 162)

Move an object to a new parent.

  • return: True on success, PEAR_Error on error.
mixed move (mixed $object, [string $newparent = null])
  • mixed $object: The object to move.
  • string $newparent: The new parent object. Defaults to the root.

Redefined in descendants as:
remove (line 113)

Removes an object.

TODO remove (string $object, [boolean $force = false])
  • string $object: The object to remove.
  • boolean $force: Force removal of every child object?

Redefined in descendants as:
removeUserData (line 149)

Removes all DataTree objects owned by a certain user.

  • abstract:
TODO removeUserData (string $user)
  • string $user: A user name.
rename (line 191)

Change an object's name.

  • return: True on success, PEAR_Error on error.
mixed rename (mixed $old_object, string $new_object_name)
  • mixed $old_object: The old object.
  • string $new_object_name: The new object name.

Redefined in descendants as:
reorder (line 228)

Changes the order of the children of an object.

  • abstract:
TODO reorder ( $parents, [mixed $order = null], [integer $cid = null], string $parent)
  • string $parent: The full id path of the parent object.
  • mixed $order: If an array it specifies the new positions for all child objects. If an integer and $cid is specified, the position where the child specified by $cid is inserted. If $cid is not specified, the position gets deleted, causing the following positions to shift up.
  • integer $cid: See $order.
  • $parents

Redefined in descendants as:
set (line 661)

Import a list of objects. Used by drivers to populate the internal $_data array.

TODO set (array $data, [string $charset = null])
  • array $data: The data to import.
  • string $charset: The charset to convert the object name from.
setOrder (line 285)

Explicitly set the order for a datatree object.

  • abstract:
TODO setOrder (integer $id, integer $order)
  • integer $id: The datatree object id to change.
  • integer $order: The new order.

Redefined in descendants as:
singleton (line 1385)

Attempts to return a reference to a concrete DataTree instance based on $driver.

It will only create a new instance if no DataTree instance with the same parameters currently exists.

This should be used if multiple DataTree sources (and, thus, multiple DataTree instances) are required.

This method must be invoked as: $var = &DataTree::singleton();

  • return: The concrete DataTree reference, or false on an error.
DataTree &singleton (mixed $driver, [array $params = null])
  • mixed $driver: Type of concrete DataTree subclass to return, based on storage driver ($driver). The code is dynamically included. If $driver is an array, then look in $driver[0]/lib/DataTree/ for subclass implementation named $driver[1].php.
  • array $params: A hash containing any additional configuration or connection parameters a subclass might need.
sortByAttributes (line 1249)

Sorts IDs by attribute values. IDs without attributes will be added to the end of the sorted list.

  • return: Sorted ids.
  • abstract:
array sortByAttributes (array $unordered_ids, [array $sortby_name = null], [array $sortby_key = null], [array $direction = 0])
  • array $unordered_ids: Array of ids to sort.
  • array $sortby_name: Attribute name to use for sorting.
  • array $sortby_key: Attribute key to use for sorting.
  • array $direction: Sort direction:
    1. - ascending
    2. - descending

Redefined in descendants as:
sortHash (line 578)

Create attribute sort hash

  • return: The sort hash.
  • since: Horde 3.1
string sortHash (string $root, [string $sortby_name = null], [string $sortby_key = null], [integer $direction = 0])
  • string $root: The name of the leaf from which we start the export tree.
  • string $sortby_name: Attribute name to use for sorting.
  • string $sortby_key: Attribute key to use for sorting.
  • integer $direction: Sort direction:
    1. - ascending
    2. - descending
updateData (line 1265)

Update the data in an object. Does not change the object's parent or name, just serialized data or attributes.

  • abstract:
TODO updateData (DataTree $object)

Redefined in descendants as:
  • DataTree_null::updateData() : Update the data in an object. Does not change the object's parent or name, just serialized data.
  • DataTree_sql::updateData() : Update the data in an object. Does not change the object's parent or name, just serialized data or attributes.
_add (line 1151)

Add an object.

  • private:
  • access: protected
TODO _add (string $name, integer $id, integer $pid, [integer $order = ''])
  • string $name: The short object name.
  • integer $id: The new object's unique ID.
  • integer $pid: The unique ID of the object's parent.
  • integer $order: The ordering data for the object.
_cmp (line 1286)

Sort two objects by their order field, and if that is the same, alphabetically (case insensitive) by name.

You never call this function; it's used in uasort() calls. Do NOT use usort(); you'll lose key => value associations.

  • return: 1 if $a should be first, -1 if $b should be first,
    1. if they are entirely equal.
  • private:
integer _cmp (array $a, array $b)
  • array $a: The first object
  • array $b: The second object
_cmpSorted (line 1314)

Sorts two objects by their sorter hash field.

You never call this function; it's used in uasort() calls. Do NOT use usort(); you'll lose key => value associations.

  • return: 1 if $a should be first, -1 if $b should be first,
    1. if they are entirely equal.
  • private:
  • since: Horde 3.1
integer _cmpSorted (array $a, array $b)
  • array $a: The first object
  • array $b: The second object
_defineObjectClass (line 298)

Dynamically determines the object class.

TODO _defineObjectClass (array $attributes)
  • array $attributes: The set of attributes that contain the class information. Defaults to DataTreeObject.
_extractOneLevel (line 718)

Extract one level of data for a parent leaf, sorted first by their order and then by name. This function is a way to get a collection of $leaf's children.

  • return: TODO
array _extractOneLevel ([string $leaf = DATATREE_ROOT])
  • string $leaf: Name of the parent from which to start.
_reorder (line 245)

Change order of children of an object.

void _reorder (string $pid, [mixed $order = null], [integer $cid = null])
  • string $pid: The parent object id string path.
  • mixed $order: Specific new order position or an array containing the new positions for the given parent.
  • integer $cid: If provided indicates insertion of a new child to the parent to avoid incrementing it when shifting up all other children's order. If not provided indicates deletion, so shift all other positions down one.

Documentation generated on Sun, 30 Jan 2011 05:16:25 +0000 by phpDocumentor 1.4.3