From 965b8e9641a746076fe10a7afc5086d6020afc4f Mon Sep 17 00:00:00 2001 From: mark_story Date: Sun, 8 Mar 2009 17:12:30 +0000 Subject: [PATCH] Updating doc blocks on tree behavior. git-svn-id: https://svn.cakephp.org/repo/branches/1.2.x.x@8081 3807eeeb-6ff5-0310-8944-8be069107fe0 --- cake/libs/model/behaviors/tree.php | 52 +++++++++++++++++------------- 1 file changed, 30 insertions(+), 22 deletions(-) diff --git a/cake/libs/model/behaviors/tree.php b/cake/libs/model/behaviors/tree.php index 515fa3f3bd5..9d379368fb8 100644 --- a/cake/libs/model/behaviors/tree.php +++ b/cake/libs/model/behaviors/tree.php @@ -25,10 +25,11 @@ * @license http://www.opensource.org/licenses/mit-license.php The MIT License */ /** - * Short description for file - * - * Long description for file + * Tree Behavior. * + * Enables a model object to act as a node-based tree. Using Modified Preorder Tree Traversal + * + * @see http://en.wikipedia.org/wiki/Tree_traversal * @package cake * @subpackage cake.cake.libs.model.behaviors */ @@ -52,8 +53,8 @@ class TreeBehavior extends ModelBehavior { /** * Initiate Tree behavior * - * @param object $Model - * @param array $config + * @param object $Model instance of model + * @param array $config array of configuration settings. * @return void * @access public */ @@ -77,7 +78,7 @@ function setup(&$Model, $config = array()) { * Overriden to transparently manage setting the lft and rght fields if and only if the parent field is included in the * parameters to be saved. * - * @param AppModel $Model + * @param AppModel $Model Model instance. * @param boolean $created indicates whether the node just saved was created or updated * @return boolean true on success, false on failure * @access public @@ -98,7 +99,7 @@ function afterSave(&$Model, $created) { * * Will delete the current node and all children using the deleteAll method and sync the table * - * @param AppModel $Model + * @param AppModel $Model Model instance * @return boolean true to continue, false to abort the delete * @access public */ @@ -130,7 +131,7 @@ function beforeDelete(&$Model) { * this method bypassing the setParent logic. * * @since 1.2 - * @param AppModel $Model + * @param AppModel $Model Model instance * @return boolean true to continue, false to abort the save * @access public */ @@ -201,7 +202,7 @@ function beforeSave(&$Model) { * If the direct parameter is set to true, only the direct children are counted (based upon the parent_id field) * If false is passed for the id parameter, all top level nodes are counted, or all nodes are counted. * - * @param AppModel $Model + * @param AppModel $Model Model instance * @param mixed $id The ID of the record to read or false to read all top level nodes * @param boolean $direct whether to count direct, or all, children * @return integer number of child nodes @@ -241,7 +242,7 @@ function childcount(&$Model, $id = null, $direct = false) { * If the direct parameter is set to true, only the direct children are returned (based upon the parent_id field) * If false is passed for the id parameter, top level, or all (depending on direct parameter appropriate) are counted. * - * @param AppModel $Model + * @param AppModel $Model Model instance * @param mixed $id The ID of the record to read * @param boolean $direct whether to return only the direct, or all, children * @param mixed $fields Either a single string of a field name, or an array of field names @@ -299,7 +300,7 @@ function children(&$Model, $id = null, $direct = false, $fields = null, $order = /** * A convenience method for returning a hierarchical array used for HTML select boxes * - * @param AppModel $Model + * @param AppModel $Model Model instance * @param mixed $conditions SQL conditions as a string or as an array('field' =>'value',...) * @param string $keyPath A string path to the key, i.e. "{n}.Post.id" * @param string $valuePath A string path to the value, i.e. "{n}.Post.title" @@ -356,7 +357,7 @@ function generatetreelist(&$Model, $conditions = null, $keyPath = null, $valuePa * * reads the parent id and returns this node * - * @param AppModel $Model + * @param AppModel $Model Model instance * @param mixed $id The ID of the record to read * @param integer $recursive The number of levels deep to fetch associated records * @return array Array of data for the parent node @@ -387,7 +388,7 @@ function getparentnode(&$Model, $id = null, $fields = null, $recursive = null) { /** * Get the path to the given node * - * @param AppModel $Model + * @param AppModel $Model Model instance * @param mixed $id The ID of the record to read * @param mixed $fields Either a single string of a field name, or an array of field names * @param integer $recursive The number of levels deep to fetch associated records @@ -424,7 +425,7 @@ function getpath(&$Model, $id = null, $fields = null, $recursive = null) { * * If the node is the last child, or is a top level node with no subsequent node this method will return false * - * @param AppModel $Model + * @param AppModel $Model Model instance * @param mixed $id The ID of the record to move * @param mixed $number how many places to move the node or true to move to last position * @return boolean true on success, false on failure @@ -481,7 +482,7 @@ function movedown(&$Model, $id = null, $number = 1) { * * If the node is the first child, or is a top level node with no previous node this method will return false * - * @param AppModel $Model + * @param AppModel $Model Model instance * @param mixed $id The ID of the record to move * @param mixed $number how many places to move the node, or true to move to first position * @return boolean true on success, false on failure @@ -543,7 +544,7 @@ function moveup(&$Model, $id = null, $number = 1) { * parameter only applies to "parent" mode and determines what to do if the parent field contains an id that is not present. * * @todo Could be written to be faster, *maybe*. Ideally using a subquery and putting all the logic burden on the DB. - * @param AppModel $Model + * @param AppModel $Model Model instance * @param string $mode parent or tree * @param mixed $missingParentAction 'return' to do nothing and return, 'delete' to * delete, or the id of the parent to set as the parent_id @@ -615,9 +616,16 @@ function recover(&$Model, $mode = 'parent', $missingParentAction = null) { * This method does not change the parent of any node. * * Requires a valid tree, by default it verifies the tree before beginning. - * - * @param AppModel $Model - * @param array $options + * + * Options: + * + * - 'id' id of record to use as top node for reordering + * - 'field' Which field to use in reordeing defaults to displayField + * - 'order' Direction to order either DESC or ASC (defaults to ASC) + * - 'verify' Whether or not to verify the tree before reorder. defaults to true. + * + * @param AppModel $Model Model instance + * @param array $options array of options to use in reordering. * @return boolean true on success, false on failure */ function reorder(&$Model, $options = array()) { @@ -649,7 +657,7 @@ function reorder(&$Model, $options = array()) { * If the parameter delete is false, the node will become a new top level node. Otherwise the node will be deleted * after the children are reparented. * - * @param AppModel $Model + * @param AppModel $Model Model instance * @param mixed $id The ID of the record to remove * @param boolean $delete whether to delete the node after reparenting children (if any) * @return boolean true on success, false on failure @@ -717,7 +725,7 @@ function removefromtree(&$Model, $id = null, $delete = false) { * * Returns true if the tree is valid otherwise an array of (type, incorrect left/right index, message) * - * @param AppModel $Model + * @param AppModel $Model Model instance * @return mixed true if the tree is valid or empty, otherwise an array of (error type [index, node], * [incorrect left/right index,node id], message) * @access public @@ -788,7 +796,7 @@ function verify(&$Model) { * of recovering a corrupted table, or creating new nodes. Otherwise it should always be false. In reality this * method could be private, since calling save with parent_id set also calls setParent * - * @param AppModel $Model + * @param AppModel $Model Model instance * @param mixed $parentId * @return boolean true on success, false on failure * @access protected