class Hierarchy extends DataExtension (View source)

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.

Properties

protected SS_Object $owner

The object this extension is applied to.

from  Extension
protected DataObject $ownerBaseClass

The base class that this extension was applied to; $this->owner must be one of these

from  Extension
public $class from  Extension
protected $markedNodes
protected $markingFilter
protected int $_cache_numChildren
protected static array $marked

Cache of DataObjects' marked statuses: [ClassName][ID] = bool

protected static array $expanded

Cache of DataObjects' expanded statuses: [ClassName][ID] = bool

protected static array $treeOpened

Cache of DataObjects' opened statuses: [ClassName][ID] = bool

Methods

public
__construct()

No description

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

Called when this extension is added to a particular class

public
setOwner(SS_Object $owner, string $ownerBaseClass = null)

Set the owner of this extension.

public
clearOwner()

No description

public
getOwner()

Returns the owner of this extension.

public static 
string
get_classname_without_arguments(string $extensionStr)

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

public static 
get_extra_config($class, $extension, $args)

No description

public static 
unload_extra_statics($class, $extension)

No description

public
validate(ValidationResult $validationResult)

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

public
augmentSQL(SQLQuery $query)

Edit the given query object to support queries for this extension

public
augmentDatabase()

Update the database schema as required by this extension.

public
augmentWrite(array $manipulation)

Augment a write-record request.

public
onBeforeWrite()

No description

public
onAfterWrite()

No description

public
onBeforeDelete()

No description

public
onAfterDelete()

No description

public
requireDefaultRecords()

No description

public
populateDefaults()

No description

public
can($member)

No description

public
canEdit($member)

No description

public
canDelete($member)

No description

public
canCreate($member)

No description

public
array
extraStatics($class = null, $extension = null)

Define extra database fields

public
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. DataObject->getCMSFields().

public
updateFrontEndFields(FieldList $fields)

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

public
updateCMSActions(FieldList $actions)

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

public
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']

public
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']

public
string
getChildrenAsUL(string $attributes = "", string|callable $titleEval = '"<li>" . $child->Title', string $extraArg = null, bool $limitToMarked = false, string $childrenMethod = "AllChildrenIncludingDeleted", $numChildrenMethod = "numChildren", bool $rootCall = true, int $nodeCountThreshold = null, callable $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.

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

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

public
setMarkingFilter(string $parameterName, mixed $parameterValue)

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

public
setMarkingFilterFunction(string $funcName)

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

public
bool
markingFilterMatches(DataObject $node)

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

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

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

protected
markingFinished(string $numChildrenMethod = "numChildren")

Ensure marked nodes that have children are also marked expanded. Call this after marking but before iterating over the tree.

public
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.

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

Mark the children of the DataObject with the given ID.

public
markToExpose(DataObject $childObj)

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

public
array
markedNodeIDs()

Return the IDs of all the marked nodes.

public
parentStack()

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

public
markExpanded()

Mark this DataObject as expanded.

public
markUnexpanded()

Mark this DataObject as unexpanded.

public
markOpened()

Mark this DataObject's tree as opened.

public
markClosed()

Mark this DataObject's tree as closed.

public
bool
isMarked()

Check if this DataObject is marked.

public
bool
isExpanded()

Check if this DataObject is expanded.

public
bool
isTreeOpened()

Check if this DataObject's tree is opened.

public
int[]
getDescendantIDList()

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

public
loadDescendantIDListInto(array $idList)

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

public
Children()

Get the children for this DataObject.

public
AllChildren()

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

public
AllChildrenIncludingDeleted(mixed $context = null)

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

public
doAllChildrenIncludingDeleted(mixed $context = null)

No description

public
AllHistoricalChildren()

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

public
int
numHistoricalChildren()

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

public
int
numChildren(bool $cache = true)

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

public
bool
showingCMSTree()

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

public
stageChildren(bool $showAll = false)

Return children in the stage site.

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

Return children in the live site, if it exists.

public
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.

public
getAncestors()

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

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

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

public
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.

public
naturalNext(string $className = null, string|int $root = 0, 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.

public
flushCache()

Flush all Hierarchy caches:

  • Children (instance)
  • NumChildren (instance)
  • Marked (global)
  • Expanded (global)
  • TreeOpened (global)

public static 
reset()

Reset global Hierarchy caches:

  • Marked
  • Expanded
  • TreeOpened

Parent()

No description

Details

__construct()

No description

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

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'.

clearOwner()

No description

SS_Object getOwner()

Returns the owner of this extension.

Return Value

SS_Object

static string get_classname_without_arguments(string $extensionStr)

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

Parameters

string $extensionStr

E.g. "Versioned('Stage','Live')"

Return Value

string

Extension classname, e.g. "Versioned"

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

No description

Parameters

$class
$extension
$args

static unload_extra_statics($class, $extension)

No description

Parameters

$class
$extension

validate(ValidationResult $validationResult)

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

Parameters

ValidationResult $validationResult

Local validation result

augmentSQL(SQLQuery $query)

Edit the given query object to support queries for this extension

Parameters

SQLQuery $query

Query to augment.

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 Versioned->augmentDatabase for an example.

augmentWrite(array $manipulation)

Augment a write-record request.

Parameters

array $manipulation

Array of operations to augment.

onBeforeWrite()

No description

onAfterWrite()

No description

onBeforeDelete()

No description

onAfterDelete()

No description

requireDefaultRecords()

No description

populateDefaults()

No description

can($member)

No description

Parameters

$member

canEdit($member)

No description

Parameters

$member

canDelete($member)

No description

Parameters

$member

canCreate($member)

No description

Parameters

$member

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.

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. DataObject->getCMSFields().

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

Caution: Use FieldList->addFieldToTab() to add fields.

Parameters

FieldList $fields

FieldList with a contained TabSet

updateFrontEndFields(FieldList $fields)

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

Caution: Use FieldList->push() to add fields.

Parameters

FieldList $fields

FieldList without TabSet nesting

updateCMSActions(FieldList $actions)

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

Parameters

FieldList $actions FieldList

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

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

string getChildrenAsUL(string $attributes = "", string|callable $titleEval = '"<li>" . $child->Title', string $extraArg = null, bool $limitToMarked = false, string $childrenMethod = "AllChildrenIncludingDeleted", $numChildrenMethod = "numChildren", bool $rootCall = true, int $nodeCountThreshold = null, callable $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

string $attributes

Attributes to add to the UL

string|callable $titleEval

PHP code to evaluate to start each child - this should include '

  • '

  • string $extraArg

    Extra arguments that will be passed on to children, for if they overload this function

    bool $limitToMarked

    Display only marked children

    string $childrenMethod

    The name of the method used to get children from each object

    $numChildrenMethod
    bool $rootCall

    Set to true for this first call, and then to false for calls inside the recursion. You should not change this.

    int $nodeCountThreshold

    See self::$node_threshold_total

    callable $nodeCountCallback

    Called with the node count, which gives the callback an opportunity to intercept the query. Useful e.g. to avoid excessive children listings (Arguments: $parent, $numChildren)

    Return Value

    string

    int markPartialTree(int $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 isExpanded()} and {@link isMarked() on individual nodes.

    Parameters

    int $nodeCountThreshold

    See getChildrenAsUL()

    $context
    $childrenMethod
    $numChildrenMethod

    Return Value

    int

    The actual number of nodes marked.

    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.

    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

    bool markingFilterMatches(DataObject $node)

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

    Parameters

    DataObject $node

    Node to check

    Return Value

    bool

    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

    protected markingFinished(string $numChildrenMethod = "numChildren")

    Ensure marked nodes that have children are also marked expanded. Call this after marking but before iterating over the tree.

    Parameters

    string $numChildrenMethod

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

    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

    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

    markToExpose(DataObject $childObj)

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

    Parameters

    DataObject $childObj

    array markedNodeIDs()

    Return the IDs of all the marked nodes.

    Return Value

    array

    SiteTree[] parentStack()

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

    Return Value

    SiteTree[]

    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.

    Return Value

    bool

    bool isExpanded()

    Check if this DataObject is expanded.

    Return Value

    bool

    bool isTreeOpened()

    Check if this DataObject's tree is opened.

    Return Value

    bool

    int[] getDescendantIDList()

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

    Return Value

    int[]

    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.

    DataList Children()

    Get the children for this DataObject.

    Return Value

    DataList

    DataList AllChildren()

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

    Return Value

    DataList

    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

    ArrayList doAllChildrenIncludingDeleted(mixed $context = null)

    No description

    Parameters

    mixed $context

    Return Value

    ArrayList

    See also

    AllChildrenIncludingDeleted

    DataList AllHistoricalChildren()

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

    Return Value

    DataList

    Exceptions

    Exception

    int numHistoricalChildren()

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

    Return Value

    int

    Exceptions

    Exception

    int numChildren(bool $cache = true)

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

    Parameters

    bool $cache

    Whether to retrieve values from cache

    Return Value

    int

    bool showingCMSTree()

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

    Return Value

    bool

    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 SiteTree.

    Return Value

    DataList

    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 SiteTree.

    bool $onlyDeletedFromStage

    Only return items that have been deleted from stage

    Return Value

    DataList

    Exceptions

    Exception

    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

    ArrayList getAncestors()

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

    Return Value

    ArrayList

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

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

    Parameters

    string $separator

    Return Value

    string

    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.

    Write!

    Parameters

    string $className

    Class name of the node to find

    DataObject $afterNode

    Used for recursive calls to this function

    Return Value

    DataObject

    DataObject naturalNext(string $className = null, string|int $root = 0, 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

    flushCache()

    Flush all Hierarchy caches:

    • Children (instance)
    • NumChildren (instance)
    • Marked (global)
    • Expanded (global)
    • TreeOpened (global)

    static reset()

    Reset global Hierarchy caches:

    • Marked
    • Expanded
    • TreeOpened

    DataObject Parent()

    No description

    Return Value

    DataObject