Hierarchy

class Hierarchy extends DataExtension

DataObjects that use the Hierarchy extension can be be organised as a hierarchy, with children and parents. The most obvious example of this is SiteTree.

Config options

node_threshold_total int The lower bounds for the amount of nodes to mark. If set, the logic will expand nodes until it reaches at least this number, and then stops. Root nodes will always show regardless of this settting. Further nodes can be lazy-loaded via ajax. This isn't a hard limit. Example: On a value of 10, with 20 root nodes, each having 30 children, the actual node count will be 50 (all root nodes plus first expanded child).
node_threshold_leaf int Limit on the maximum children a specific node can display. Serves as a hard limit to avoid exceeding available server resources in generating the tree, and browser resources in rendering it. Nodes with children exceeding this value typically won't display any children, although this is configurable through the $nodeCountCallback parameter in {@link getChildrenAsUL()}. "Root" nodes will always show all children, regardless of this setting.
hide_from_hierarchy array A list of classnames to exclude from display in both the CMS and front end displays. ->Children() and ->AllChildren affected.
hide_from_cms_tree array A list of classnames to exclude from display in the page tree views of the CMS, unlike $hide_from_hierarchy above which effects both CMS and front end.

Properties

$class from Extension

Methods

__construct()

No description

from Extension
static 
add_to_class(string $class, string $extensionClass, mixed $args = null)

Called when this extension is added to a particular class

from Extension
setOwner(SS_Object $owner, string $ownerBaseClass = null)

Set the owner of this extension.

from Extension
clearOwner()

No description

from Extension
SS_Object
getOwner()

Returns the owner of this extension.

from Extension
static string
get_classname_without_arguments(string $extensionStr)

Helper method to strip eval'ed arguments from a string thats passed to {@link DataObject::$extensions} or {@link Object::add_extension()}.

from Extension
static 
get_extra_config($class, $extension, $args)

No description

static 
unload_extra_statics($class, $extension)

No description

from DataExtension
validate(ValidationResult $validationResult)

Validate the owner object - check for existence of infinite loops.

augmentSQL(SQLQuery $query)

Edit the given query object to support queries for this extension

from DataExtension
augmentDatabase()

Update the database schema as required by this extension.

from DataExtension
augmentWrite(array $manipulation)

Augment a write-record request.

from DataExtension
onBeforeWrite()

No description

from DataExtension
onAfterWrite()

No description

from DataExtension
onBeforeDelete()

No description

from DataExtension
onAfterDelete()

No description

from DataExtension
requireDefaultRecords()

No description

from DataExtension
populateDefaults()

No description

from DataExtension
can($member)

No description

from DataExtension
canEdit($member)

No description

from DataExtension
canDelete($member)

No description

from DataExtension
canCreate($member)

No description

from DataExtension
array
extraStatics($class = null, $extension = null)

Define extra database fields

from DataExtension
updateCMSFields(FieldList $fields)

This function is used to provide modifications to the form in the CMS by the extension. By default, no changes are made. {@link DataObject->getCMSFields()}.

from DataExtension
updateFrontEndFields(FieldList $fields)

This function is used to provide modifications to the form used for front end forms. {@link DataObject->getFrontEndFields()}

from DataExtension
updateCMSActions(FieldList $actions)

This is used to provide modifications to the form actions used in the CMS. {@link DataObject->getCMSActions()}.

from DataExtension
updateSummaryFields(array $fields)

this function is used to provide modifications to the summary fields in CMS by the extension By default, the summaryField() of its owner will merge more fields defined in the extension's $extra_fields['summary_fields']

from DataExtension
updateFieldLabels(array $labels)

this function is used to provide modifications to the fields labels in CMS by the extension By default, the fieldLabels() of its owner will merge more fields defined in the extension's $extra_fields['field_labels']

from DataExtension
string
getChildrenAsUL($attributes = "", $titleEval = '"<li>" . $child->Title', $extraArg = null, $limitToMarked = false, $childrenMethod = "AllChildrenIncludingDeleted", $numChildrenMethod = "numChildren", $rootCall = true, $nodeCountThreshold = null, $nodeCountCallback = null)

Returns the children of this DataObject as an XHTML UL. This will be called recursively on each child, so if they have children they will be displayed as a UL inside a LI.

int
markPartialTree($nodeCountThreshold = null, $context = null, $childrenMethod = "AllChildrenIncludingDeleted", $numChildrenMethod = "numChildren")

Mark a segment of the tree, by calling mark().

setMarkingFilter(string $parameterName, mixed $parameterValue)

Filter the marking to only those object with $node->$parameterName == $parameterValue

setMarkingFilterFunction(string $funcName)

Filter the marking to only those where the function returns true. The node in question will be passed to the function.

bool
markingFilterMatches(DataObject $node)

Returns true if the marking filter matches on the given node.

DataList
markChildren(DataObject $node, mixed $context = null, string $childrenMethod = "AllChildrenIncludingDeleted", string $numChildrenMethod = "numChildren")

Mark all children of the given node that match the marking filter.

string
markingClasses(string $numChildrenMethod = "numChildren")

Return CSS classes of 'unexpanded', 'closed', both, or neither, as well as a 'jstree-*' state depending on the marking of this DataObject.

bool
markById(int $id, bool $open = false)

Mark the children of the DataObject with the given ID.

markToExpose(DataObject $childObj)

Expose the given object in the tree, by marking this page and all it ancestors.

array
markedNodeIDs()

Return the IDs of all the marked nodes.

SiteTree[]
parentStack()

Return an array of this page and its ancestors, ordered item -> root.

markExpanded()

Mark this DataObject as expanded.

markUnexpanded()

Mark this DataObject as unexpanded.

markOpened()

Mark this DataObject's tree as opened.

markClosed()

Mark this DataObject's tree as closed.

bool
isMarked()

Check if this DataObject is marked.

bool
isExpanded()

Check if this DataObject is expanded.

bool
isTreeOpened()

Check if this DataObject's tree is opened.

int[]
getDescendantIDList()

Get a list of this DataObject's and all it's descendants IDs.

loadDescendantIDListInto(array $idList)

Get a list of this DataObject's and all it's descendants ID, and put them in $idList.

DataList
Children()

Get the children for this DataObject.

DataList
AllChildren()

Return all children, including those 'not in menus'.

ArrayList
AllChildrenIncludingDeleted(mixed $context = null)

Return all children, including those that have been deleted but are still in live.

ArrayList
doAllChildrenIncludingDeleted(mixed $context = null)

No description

DataList
AllHistoricalChildren()

Return all the children that this page had, including pages that were deleted from both stage & live.

int
numHistoricalChildren()

Return the number of children that this page ever had, including pages that were deleted.

int
numChildren(bool $cache = true)

Return the number of direct children. By default, values are cached after the first invocation. Can be augumented by {@link augmentNumChildrenCountQuery()}.

bool
showingCMSTree()

Checks if we're on a controller where we should filter. ie. Are we loading the SiteTree?

DataList
stageChildren(bool $showAll = false)

Return children in the stage site.

DataList
liveChildren(bool $showAll = false, bool $onlyDeletedFromStage = false)

Return children in the live site, if it exists.

DataObject
getParent(string $filter = null)

Get this object's parent, optionally filtered by an SQL clause. If the clause doesn't match the parent, nothing is returned.

ArrayList
getAncestors()

Return all the parents of this class in a set ordered from the lowest to highest parent.

string
getBreadcrumbs(string $separator = ' &raquo; ')

Returns a human-readable, flattened representation of the path to the object, using its {@link Title} attribute.

DataObject
naturalPrev(string $className, DataObject $afterNode = null)

Get the next node in the tree of the type. If there is no instance of the className descended from this node, then search the parents.

DataObject
naturalNext(string $className = null, string|int $root, DataObject $afterNode = null)

Get the next node in the tree of the type. If there is no instance of the className descended from this node, then search the parents.

flushCache()

Flush all Hierarchy caches: - Children (instance) - NumChildren (instance) - Marked (global) - Expanded (global) - TreeOpened (global)

static 
reset()

Reset global Hierarchy caches: - Marked - Expanded - TreeOpened

Details

in Extension at line 42
__construct()

in Extension at line 54
static add_to_class(string $class, string $extensionClass, mixed $args = null)

Called when this extension is added to a particular class

Parameters

string $class
string $extensionClass
mixed $args

in Extension at line 66
setOwner(SS_Object $owner, string $ownerBaseClass = null)

Set the owner of this extension.

Parameters

SS_Object $owner The owner object,
string $ownerBaseClass The base class that the extension is applied to; this may be the class of owner, or it may be a parent. For example, if Versioned was applied to SiteTree, and then a Page object was instantiated, $owner would be a Page object, but $ownerBaseClass would be 'SiteTree'.

in Extension at line 74
clearOwner()

in Extension at line 85
SS_Object getOwner()

Returns the owner of this extension.

Return Value

SS_Object

in Extension at line 97
static string get_classname_without_arguments(string $extensionStr)

Helper method to strip eval'ed arguments from a string thats passed to {@link DataObject::$extensions} or {@link Object::add_extension()}.

Parameters

string $extensionStr E.g. "Versioned('Stage','Live')"

Return Value

string Extension classname, e.g. "Versioned"

at line 70
static get_extra_config($class, $extension, $args)

Parameters

$class
$extension
$args

in DataExtension at line 32
static unload_extra_statics($class, $extension)

Parameters

$class
$extension

at line 81
validate(ValidationResult $validationResult)

Validate the owner object - check for existence of infinite loops.

Parameters

ValidationResult $validationResult Local validation result

in DataExtension at line 50
augmentSQL(SQLQuery $query)

Edit the given query object to support queries for this extension

Parameters

SQLQuery $query Query to augment.

in DataExtension at line 59
augmentDatabase()

Update the database schema as required by this extension.

When duplicating a table's structure, remember to duplicate the create options as well. See {@link Versioned->augmentDatabase} for an example.

in DataExtension at line 67
augmentWrite(array $manipulation)

Augment a write-record request.

Parameters

array $manipulation Array of operations to augment.

in DataExtension at line 70
onBeforeWrite()

in DataExtension at line 73
onAfterWrite()

in DataExtension at line 76
onBeforeDelete()

in DataExtension at line 79
onAfterDelete()

in DataExtension at line 82
requireDefaultRecords()

in DataExtension at line 85
populateDefaults()

in DataExtension at line 88
can($member)

Parameters

$member

in DataExtension at line 91
canEdit($member)

Parameters

$member

in DataExtension at line 94
canDelete($member)

Parameters

$member

in DataExtension at line 97
canCreate($member)

Parameters

$member

in DataExtension at line 112
array extraStatics($class = null, $extension = null)

Define extra database fields

Return a map where the keys are db, has_one, etc, and the values are additional fields/relations to be defined.

Parameters

$class since this method might be called on the class directly
$extension since this can help to extract parameters to help set indexes

Return Value

array Returns a map where the keys are db, has_one, etc, and the values are additional fields/relations to be defined.

in DataExtension at line 129
updateCMSFields(FieldList $fields)

This function is used to provide modifications to the form in the CMS by the extension. By default, no changes are made. {@link DataObject->getCMSFields()}.

Please consider using {@link updateFormFields()} to globally add formfields to the record. The method {@link updateCMSFields()} should just be used to add or modify tabs, or fields which are specific to the CMS-context.

Caution: Use {@link FieldList->addFieldToTab()} to add fields.

Parameters

FieldList $fields FieldList with a contained TabSet

in DataExtension at line 140
updateFrontEndFields(FieldList $fields)

This function is used to provide modifications to the form used for front end forms. {@link DataObject->getFrontEndFields()}

Caution: Use {@link FieldList->push()} to add fields.

Parameters

FieldList $fields FieldList without TabSet nesting

in DataExtension at line 149
updateCMSActions(FieldList $actions)

This is used to provide modifications to the form actions used in the CMS. {@link DataObject->getCMSActions()}.

Parameters

FieldList $actions FieldList

in DataExtension at line 160
updateSummaryFields(array $fields)

this function is used to provide modifications to the summary fields in CMS by the extension By default, the summaryField() of its owner will merge more fields defined in the extension's $extra_fields['summary_fields']

Parameters

array $fields Array of field names

in DataExtension at line 180
updateFieldLabels(array $labels)

this function is used to provide modifications to the fields labels in CMS by the extension By default, the fieldLabels() of its owner will merge more fields defined in the extension's $extra_fields['field_labels']

Parameters

array $labels Array of field labels

at line 130
string getChildrenAsUL($attributes = "", $titleEval = '"<li>" . $child->Title', $extraArg = null, $limitToMarked = false, $childrenMethod = "AllChildrenIncludingDeleted", $numChildrenMethod = "numChildren", $rootCall = true, $nodeCountThreshold = null, $nodeCountCallback = null)

Returns the children of this DataObject as an XHTML UL. This will be called recursively on each child, so if they have children they will be displayed as a UL inside a LI.

Parameters

$attributes
$titleEval
$extraArg
$limitToMarked
$childrenMethod
$numChildrenMethod
$rootCall
$nodeCountThreshold
$nodeCountCallback

Return Value

string

at line 221
int markPartialTree($nodeCountThreshold = null, $context = null, $childrenMethod = "AllChildrenIncludingDeleted", $numChildrenMethod = "numChildren")

Mark a segment of the tree, by calling mark().

The method performs a breadth-first traversal until the number of nodes is more than minCount. This is used to get a limited number of tree nodes to show in the CMS initially.

This method returns the number of nodes marked. After this method is called other methods can check {@link isExpanded()} and {@link isMarked()} on individual nodes.

Parameters

$nodeCountThreshold
$context
$childrenMethod
$numChildrenMethod

Return Value

int The actual number of nodes marked.

at line 251
setMarkingFilter(string $parameterName, mixed $parameterValue)

Filter the marking to only those object with $node->$parameterName == $parameterValue

Parameters

string $parameterName The parameter on each node to check when marking.
mixed $parameterValue The value the parameter must be to be marked.

at line 264
setMarkingFilterFunction(string $funcName)

Filter the marking to only those where the function returns true. The node in question will be passed to the function.

Parameters

string $funcName The name of the function to call

at line 276
bool markingFilterMatches(DataObject $node)

Returns true if the marking filter matches on the given node.

Parameters

DataObject $node Node to check

Return Value

bool

at line 308
DataList markChildren(DataObject $node, mixed $context = null, string $childrenMethod = "AllChildrenIncludingDeleted", string $numChildrenMethod = "numChildren")

Mark all children of the given node that match the marking filter.

Parameters

DataObject $node Parent node
mixed $context
string $childrenMethod The name of the instance method to call to get the object's list of children
string $numChildrenMethod The name of the instance method to call to count the object's children

Return Value

DataList

at line 360
string markingClasses(string $numChildrenMethod = "numChildren")

Return CSS classes of 'unexpanded', 'closed', both, or neither, as well as a 'jstree-*' state depending on the marking of this DataObject.

Parameters

string $numChildrenMethod The name of the instance method to call to count the object's children

Return Value

string

at line 384
bool markById(int $id, bool $open = false)

Mark the children of the DataObject with the given ID.

Parameters

int $id ID of parent node
bool $open If this is true, mark the parent node as opened

Return Value

bool

at line 401
markToExpose(DataObject $childObj)

Expose the given object in the tree, by marking this page and all it ancestors.

Parameters

DataObject $childObj

at line 415
array markedNodeIDs()

Return the IDs of all the marked nodes.

Return Value

array

at line 424
SiteTree[] parentStack()

Return an array of this page and its ancestors, ordered item -> root.

Return Value

SiteTree[]

at line 456
markExpanded()

Mark this DataObject as expanded.

at line 464
markUnexpanded()

Mark this DataObject as unexpanded.

at line 472
markOpened()

Mark this DataObject's tree as opened.

at line 480
markClosed()

Mark this DataObject's tree as closed.

at line 491
bool isMarked()

Check if this DataObject is marked.

Return Value

bool

at line 502
bool isExpanded()

Check if this DataObject is expanded.

Return Value

bool

at line 513
bool isTreeOpened()

Check if this DataObject's tree is opened.

Return Value

bool

at line 524
int[] getDescendantIDList()

Get a list of this DataObject's and all it's descendants IDs.

Return Value

int[]

at line 535
loadDescendantIDListInto(array $idList)

Get a list of this DataObject's and all it's descendants ID, and put them in $idList.

Parameters

array $idList Array to put results in.

at line 555
DataList Children()

Get the children for this DataObject.

Return Value

DataList

at line 574
DataList AllChildren()

Return all children, including those 'not in menus'.

Return Value

DataList

at line 588
ArrayList AllChildrenIncludingDeleted(mixed $context = null)

Return all children, including those that have been deleted but are still in live.

  • Deleted children will be marked as "DeletedFromStage"
  • Added children will be marked as "AddedToStage"
  • Modified children will be marked as "ModifiedOnStage"
  • Everything else has "SameOnStage" set, as an indicator that this information has been looked up.

Parameters

mixed $context

Return Value

ArrayList

at line 598
ArrayList doAllChildrenIncludingDeleted(mixed $context = null)

Parameters

mixed $context

Return Value

ArrayList

See also

AllChildrenIncludingDeleted

at line 633
DataList AllHistoricalChildren()

Return all the children that this page had, including pages that were deleted from both stage & live.

Return Value

DataList

Exceptions

Exception

at line 649
int numHistoricalChildren()

Return the number of children that this page ever had, including pages that were deleted.

Return Value

int

Exceptions

Exception

at line 665
int numChildren(bool $cache = true)

Return the number of direct children. By default, values are cached after the first invocation. Can be augumented by {@link augmentNumChildrenCountQuery()}.

Parameters

bool $cache Whether to retrieve values from cache

Return Value

int

at line 682
bool showingCMSTree()

Checks if we're on a controller where we should filter. ie. Are we loading the SiteTree?

Return Value

bool

at line 696
DataList stageChildren(bool $showAll = false)

Return children in the stage site.

Parameters

bool $showAll Include all of the elements, even those not shown in the menus. Only applicable when extension is applied to {@link SiteTree}.

Return Value

DataList

at line 725
DataList liveChildren(bool $showAll = false, bool $onlyDeletedFromStage = false)

Return children in the live site, if it exists.

Parameters

bool $showAll Include all of the elements, even those not shown in the menus. Only applicable when extension is applied to {@link SiteTree}.
bool $onlyDeletedFromStage Only return items that have been deleted from stage

Return Value

DataList

Exceptions

Exception

at line 758
DataObject getParent(string $filter = null)

Get this object's parent, optionally filtered by an SQL clause. If the clause doesn't match the parent, nothing is returned.

Parameters

string $filter

Return Value

DataObject

at line 774
ArrayList getAncestors()

Return all the parents of this class in a set ordered from the lowest to highest parent.

Return Value

ArrayList

at line 791
string getBreadcrumbs(string $separator = ' &raquo; ')

Returns a human-readable, flattened representation of the path to the object, using its {@link Title} attribute.

Parameters

string $separator

Return Value

string

at line 809
DataObject naturalPrev(string $className, DataObject $afterNode = null)

Get the next node in the tree of the type. If there is no instance of the className descended from this node, then search the parents.

Parameters

string $className Class name of the node to find
DataObject $afterNode Used for recursive calls to this function

Return Value

DataObject

at line 821
DataObject naturalNext(string $className = null, string|int $root, DataObject $afterNode = null)

Get the next node in the tree of the type. If there is no instance of the className descended from this node, then search the parents.

Parameters

string $className Class name of the node to find.
string|int $root ID/ClassName of the node to limit the search to
DataObject $afterNode Used for recursive calls to this function

Return Value

DataObject

at line 874
flushCache()

Flush all Hierarchy caches: - Children (instance) - NumChildren (instance) - Marked (global) - Expanded (global) - TreeOpened (global)

at line 888
static reset()

Reset global Hierarchy caches: - Marked - Expanded - TreeOpened