TreeBehavior Class Info:
- Class Declaration:
class TreeBehavior extends ModelBehavior
- File name:
- cake/libs/model/behaviors/tree.php
- Description:
Tree Behavior.
Enables a model object to act as a node-based tree. Using Modified Preorder Tree Traversal
- Class Inheritance
- See
http://en.wikipedia.org/wiki/Tree_traversal
- Package
- cake
- Subpackage
- cake.cake.libs.model.behaviors
- Link
- http://book.cakephp.org/view/1339/Tree
Properties:
-
_defaults array
Defaults
-
errors array
Errors
-
mapMethods array
Allows the mapping of preg-compatible regular expressions to public or private methods in this class, where the array key is a /-delimited regular expression, and the value is a class method. Similar to the functionality of the findBy* / findAllBy* magic methods.
-
settings array
Contains configuration settings for use with individual model objects. This is used because if multiple models use this Behavior, each will use the same object instance. Individual model settings should be stored as an associative array, keyed off of the model name.
Method Summary:
- _addToWhitelist( $model, $field )
- afterDelete( $model )
- afterFind( $model, $results, $primary )
- afterSave( $Model, $created )
- beforeDelete( $Model )
- beforeFind( $model, $query )
- beforeSave( $Model )
- beforeValidate( $model )
- cakeError( $method, $messages = array ( ) )
- childcount( $Model, $id = NULL, $direct = false )
- children( $Model, $id = NULL, $direct = false, $fields = NULL, $order = NULL, $limit = NULL, $page = 1, $recursive = NULL )
- cleanup( $model )
- __construct( )
- dispatchMethod( $model, $method, $params = array ( ) )
- generatetreelist( $Model, $conditions = NULL, $keyPath = NULL, $valuePath = NULL, $spacer = '_', $recursive = NULL )
- getparentnode( $Model, $id = NULL, $fields = NULL, $recursive = NULL )
- getpath( $Model, $id = NULL, $fields = NULL, $recursive = NULL )
- log( $msg, $type = 2 )
- movedown( $Model, $id = NULL, $number = 1 )
- moveup( $Model, $id = NULL, $number = 1 )
- Object( )
- onError( $model, $error )
- _persist( $name, $return, $object, $type = NULL )
- recover( $Model, $mode = 'parent', $missingParentAction = NULL )
- removefromtree( $Model, $id = NULL, $delete = false )
- reorder( $Model, $options = array ( ) )
- requestAction( $url, $extra = array ( ) )
- _savePersistent( $name, $object )
- _set( $properties = array ( ) )
- _setParent( $Model, $parentId = NULL, $created = false )
- setup( $Model, $config = array ( ) )
- _stop( $status = 0 )
- toString( )
- verify( $Model )
_addToWhitelist
topIf $model's whitelist property is non-empty, $field will be added to it. Note: this method should only be used in beforeValidate or beforeSave to ensure that it only modifies the whitelist for the current save operation. Also make sure you explicitly set the value of the field which you are allowing.
- Parameters:
-
-
object $model required
Model using this behavior
-
string $field required
Field to be added to $model's whitelist
-
- Method defined in:
- cake/libs/model/model_behavior.php on line 196
- Access
protected
- Return
void
afterDelete
topAfter delete callback
- Parameters:
-
-
object $model required
Model using this behavior
-
- Method defined in:
- cake/libs/model/model_behavior.php on line 143
- Access
public
afterFind
topAfter find callback. Can be used to modify any results returned by find and findAll.
- Parameters:
-
-
object $model required
Model using this behavior
-
mixed $results required
The results of the find operation
-
boolean $primary required
Whether this model is being queried directly (vs. being queried as an association)
-
- Method defined in:
- cake/libs/model/model_behavior.php on line 98
- Return
mixed Result of the find operation
- Access
public
afterSave
topAfter save method. Called after all saves
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.
- Parameters:
-
-
AppModel $Model required
Model instance.
-
boolean $created required
indicates whether the node just saved was created or updated
-
- Method defined in:
- cake/libs/model/behaviors/tree.php on line 87
- Return
boolean true on success, false on failure
- Access
public
beforeDelete
topBefore delete method. Called before all deletes
Will delete the current node and all children using the deleteAll method and sync the table
- Parameters:
-
-
AppModel $Model required
Model instance
-
- Method defined in:
- cake/libs/model/behaviors/tree.php on line 108
- Return
boolean true to continue, false to abort the delete
- Access
public
beforeFind
topBefore find callback
- Parameters:
-
-
object $model required
Model using this behavior
-
$query required
-
- Method defined in:
- cake/libs/model/model_behavior.php on line 87
- Return
boolean True if the operation should continue, false if it should abort
- Access
public
beforeSave
topBefore save method. Called before all saves
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. For newly created nodes with NO parent the left and right field values are set directly by this method bypassing the setParent logic.
- Parameters:
-
-
AppModel $Model required
Model instance
-
- Method defined in:
- cake/libs/model/behaviors/tree.php on line 141
- Since
1.2
- Return
boolean true to continue, false to abort the save
- Access
public
beforeValidate
topBefore validate callback
- Parameters:
-
-
object $model required
Model using this behavior
-
- Method defined in:
- cake/libs/model/model_behavior.php on line 107
- Return
boolean True if validate operation should continue, false to abort
- Access
public
cakeError
topUsed to report user friendly errors. If there is a file app/error.php or app/app_error.php this file will be loaded error.php is the AppError class it should extend ErrorHandler class.
- Parameters:
-
-
string $method required
Method to be called in the error class (AppError or ErrorHandler classes)
-
array $messages optional array ( )
Message that is to be displayed by the error class
-
- Method defined in:
- cake/libs/object.php on line 187
- Return
error message
- Access
public
childcount
topGet the number of child nodes
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.
- Parameters:
-
-
AppModel $Model required
Model instance
-
mixed $id optional NULL
The ID of the record to read or false to read all top level nodes
-
boolean $direct optional false
whether to count direct, or all, children
-
- Method defined in:
- cake/libs/model/behaviors/tree.php on line 212
- Return
integer number of child nodes
- Access
public
- Link
- http://book.cakephp.org/view/1347/Counting-children
children
topGet the child nodes of the current model
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.
- Parameters:
-
-
AppModel $Model required
Model instance
-
mixed $id optional NULL
The ID of the record to read
-
boolean $direct optional false
whether to return only the direct, or all, children
-
mixed $fields optional NULL
Either a single string of a field name, or an array of field names
-
string $order optional NULL
SQL ORDER BY conditions (e.g. "price DESC" or "name ASC") defaults to the tree order
-
integer $limit optional NULL
SQL LIMIT clause, for calculating items per page.
-
integer $page optional 1
Page number, for accessing paged data
-
integer $recursive optional NULL
The number of levels deep to fetch associated records
-
- Method defined in:
- cake/libs/model/behaviors/tree.php on line 259
- Return
array Array of child nodes
- Access
public
- Link
- http://book.cakephp.org/view/1346/Children
cleanup
topClean up any initialization this behavior has done on a model. Called when a behavior is dynamically detached from a model using Model::detach().
- Parameters:
-
-
object $model required
Model using this behavior
-
- Method defined in:
- cake/libs/model/model_behavior.php on line 73
- Access
public
- See
__construct
topClass constructor, overridden in descendant classes.
- Method defined in:
- cake/libs/object.php on line 54
dispatchMethod
topOverrides Object::dispatchMethod to account for PHP4's broken reference support
- Parameters:
-
-
$model required
-
$method required
-
$params optional array ( )
-
- Method defined in:
- cake/libs/model/model_behavior.php on line 161
- See
Object::dispatchMethod
- Access
public
- Return
mixed
generatetreelist
topA convenience method for returning a hierarchical array used for HTML select boxes
- Parameters:
-
-
AppModel $Model required
Model instance
-
mixed $conditions optional NULL
SQL conditions as a string or as an array('field' =>'value',...)
-
string $keyPath optional NULL
A string path to the key, i.e. "{n}.Post.id"
-
string $valuePath optional NULL
A string path to the value, i.e. "{n}.Post.title"
-
string $spacer optional '_'
The character or characters which will be repeated
-
integer $recursive optional NULL
The number of levels deep to fetch associated records
-
- Method defined in:
- cake/libs/model/behaviors/tree.php on line 317
- Return
array An associative array of records, where the id is the key, and the display field is the value
- Access
public
- Link
- http://book.cakephp.org/view/1348/generatetreelist
getparentnode
topGet the parent node
reads the parent id and returns this node
- Parameters:
-
-
AppModel $Model required
Model instance
-
mixed $id optional NULL
The ID of the record to read
-
$fields optional NULL
-
integer $recursive optional NULL
The number of levels deep to fetch associated records
-
- Method defined in:
- cake/libs/model/behaviors/tree.php on line 373
- Return
array Array of data for the parent node
- Access
public
- Link
- http://book.cakephp.org/view/1349/getparentnode
getpath
topGet the path to the given node
- Parameters:
-
-
AppModel $Model required
Model instance
-
mixed $id optional NULL
The ID of the record to read
-
mixed $fields optional NULL
Either a single string of a field name, or an array of field names
-
integer $recursive optional NULL
The number of levels deep to fetch associated records
-
- Method defined in:
- cake/libs/model/behaviors/tree.php on line 407
- Return
array Array of nodes from top most parent to current node
- Access
public
- Link
- http://book.cakephp.org/view/1350/getpath
log
topConvience method to write a message to CakeLog. See CakeLog::write() for more information on writing to logs.
- Parameters:
-
-
string $msg required
Log message
-
integer $type optional 2
Error type constant. Defined in app/config/core.php.
-
- Method defined in:
- cake/libs/object.php on line 148
- Return
boolean Success of log write
- Access
public
movedown
topReorder the node without changing the parent.
If the node is the last child, or is a top level node with no subsequent node this method will return false
- Parameters:
-
-
AppModel $Model required
Model instance
-
mixed $id optional NULL
The ID of the record to move
-
mixed $number optional 1
how many places to move the node or true to move to last position
-
- Method defined in:
- cake/libs/model/behaviors/tree.php on line 445
- Return
boolean true on success, false on failure
- Access
public
- Link
- http://book.cakephp.org/view/1352/moveDown
moveup
topReorder the node without changing the parent.
If the node is the first child, or is a top level node with no previous node this method will return false
- Parameters:
-
-
AppModel $Model required
Model instance
-
mixed $id optional NULL
The ID of the record to move
-
mixed $number optional 1
how many places to move the node, or true to move to first position
-
- Method defined in:
- cake/libs/model/behaviors/tree.php on line 504
- Return
boolean true on success, false on failure
- Access
public
- Link
- http://book.cakephp.org/view/1353/moveUp
Object
topA hack to support __construct() on PHP 4 Hint: descendant classes have no PHP4 class_name() constructors, so this constructor gets called first and calls the top-layer __construct() which (if present) should call parent::__construct()
- Method defined in:
- cake/libs/object.php on line 43
- Return
Object
onError
topDataSource error callback
- Parameters:
-
-
object $model required
Model using this behavior
-
string $error required
Error generated in DataSource
-
- Method defined in:
- cake/libs/model/model_behavior.php on line 152
- Access
public
_persist
topChecks for a persistent class file, if found file is opened and true returned If file is not found a file is created and false returned If used in other locations of the model you should choose a unique name for the persistent file There are many uses for this method, see manual for examples
- Parameters:
-
-
string $name required
name of the class to persist
-
$return required
-
string $object required
the object to persist
-
$type optional NULL
-
- Method defined in:
- cake/libs/object.php on line 218
- Return
boolean Success
- Access
protected
- Todo
add examples to manual
recover
topRecover a corrupted tree
The mode parameter is used to specify the source of info that is valid/correct. The opposite source of data will be populated based upon that source of info. E.g. if the MPTT fields are corrupt or empty, with the $mode 'parent' the values of the parent_id field will be used to populate the left and right fields. The missingParentAction parameter only applies to "parent" mode and determines what to do if the parent field contains an id that is not present.
delete, or the id of the parent to set as the parent_id
- Parameters:
-
-
AppModel $Model required
Model instance
-
string $mode optional 'parent'
parent or tree
-
mixed $missingParentAction optional NULL
'return' to do nothing and return, 'delete' to
-
- Method defined in:
- cake/libs/model/behaviors/tree.php on line 569
- Todo
Could be written to be faster, maybe. Ideally using a subquery and putting all the logic burden on the DB.
- Return
boolean true on success, false on failure
- Access
public
- Link
- http://book.cakephp.org/view/1628/Recover
removefromtree
topRemove the current node from the tree, and reparent all children up one level.
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.
- Parameters:
-
-
AppModel $Model required
Model instance
-
mixed $id optional NULL
The ID of the record to remove
-
boolean $delete optional false
whether to delete the node after reparenting children (if any)
-
- Method defined in:
- cake/libs/model/behaviors/tree.php on line 689
- Return
boolean true on success, false on failure
- Access
public
- Link
- http://book.cakephp.org/view/1354/removeFromTree
reorder
topReorder method.
Reorders the nodes (and child nodes) of the tree according to the field and direction specified in the parameters. This method does not change the parent of any node.
Requires a valid tree, by default it verifies the tree before beginning.
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.
- Parameters:
-
-
AppModel $Model required
Model instance
-
array $options optional array ( )
array of options to use in reordering.
-
- Method defined in:
- cake/libs/model/behaviors/tree.php on line 649
- Return
boolean true on success, false on failure
- Link
- Array
requestAction
topCalls a controller's method from any location. Can be used to connect controllers together or tie plugins into a main application. requestAction can be used to return rendered views or fetch the return value from controller actions.
- Parameters:
-
-
mixed $url required
String or array-based url.
-
array $extra optional array ( )
if array includes the key "return" it sets the AutoRender to true.
-
- Method defined in:
- cake/libs/object.php on line 80
- Return
mixed Boolean true or false on success/failure, or contents of rendered action if 'return' is set in $extra.
- Access
public
_savePersistent
topYou should choose a unique name for the persistent file
There are many uses for this method, see manual for examples
- Parameters:
-
-
string $name required
name used for object to cache
-
object $object required
the object to persist
-
- Method defined in:
- cake/libs/object.php on line 247
- Return
boolean true on save, throws error if file can not be created
- Access
protected
_set
topAllows setting of multiple properties of the object in a single line of code. Will only set properties that are part of a class declaration.
- Parameters:
-
-
array $properties optional array ( )
An associative array containing properties and corresponding values.
-
- Method defined in:
- cake/libs/object.php on line 166
- Return
void
- Access
protected
_setParent
topSets the parent of the given node
The force parameter is used to override the "don't change the parent to the current parent" logic in the event 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
- Parameters:
-
-
AppModel $Model required
Model instance
-
mixed $parentId optional NULL
Model instance
-
$created optional false
-
- Method defined in:
- cake/libs/model/behaviors/tree.php on line 830
- Return
boolean true on success, false on failure
- Access
protected
setup
topInitiate Tree behavior
- Parameters:
-
-
object $Model required
instance of model
-
array $config optional array ( )
array of configuration settings.
-
- Method defined in:
- cake/libs/model/behaviors/tree.php on line 61
- Return
void
- Access
public
_stop
topStop execution of the current script. Wraps exit() making testing easier.
- Parameters:
-
-
$status optional 0
-
- Method defined in:
- cake/libs/object.php on line 135
- Return
void
- Access
public
toString
topObject-to-string conversion. Each class can override this method as necessary.
- Method defined in:
- cake/libs/object.php on line 64
- Return
string The name of this class
- Access
public
verify
topCheck if the current tree is valid.
Returns true if the tree is valid otherwise an array of (type, incorrect left/right index, message)
- Parameters:
-
-
AppModel $Model required
Model instance
-
- Method defined in:
- cake/libs/model/behaviors/tree.php on line 758
- 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
- Link
- http://book.cakephp.org/view/1630/Verify
