silverstripe-framework/src/ORM/Hierarchy/Hierarchy.php

437 lines
14 KiB
PHP
Raw Normal View History

<?php
namespace SilverStripe\ORM\Hierarchy;
use SilverStripe\Admin\LeftAndMain;
use SilverStripe\Control\Controller;
use SilverStripe\ORM\DataList;
use SilverStripe\ORM\SS_List;
use SilverStripe\ORM\ValidationResult;
use SilverStripe\ORM\ArrayList;
use SilverStripe\ORM\DataObject;
use SilverStripe\ORM\DataExtension;
use SilverStripe\Versioned\Versioned;
use Exception;
/**
* 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.
*
* @property int $ParentID
* @property DataObject|Hierarchy $owner
* @method DataObject Parent()
*/
class Hierarchy extends DataExtension
2016-11-29 00:31:16 +01:00
{
/**
* Cache for {@see numChildren()}
*
* @var int
*/
protected $_cache_numChildren = null;
/**
* Cache for {@see Children()}
*
* @var SS_List
*/
protected $_cache_children = null;
/**
* 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).
*
* @config
* @var int
*/
private static $node_threshold_total = 50;
/**
* 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.
*
* @config
* @var int
*/
private static $node_threshold_leaf = 250;
/**
* A list of classnames to exclude from display in both the CMS and front end
* displays. ->Children() and ->AllChildren affected.
* Especially useful for big sets of pages like listings
* If you use this, and still need the classes to be editable
* then add a model admin for the class
* Note: Does not filter subclasses (non-inheriting)
*
* @var array
* @config
*/
private static $hide_from_hierarchy = 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.
* Especially useful for big sets of pages like listings
* If you use this, and still need the classes to be editable
* then add a model admin for the class
* Note: Does not filter subclasses (non-inheriting)
*
* @var array
* @config
*/
private static $hide_from_cms_tree = array();
2016-11-29 00:31:16 +01:00
public static function get_extra_config($class, $extension, $args)
{
return array(
'has_one' => array('Parent' => $class)
);
}
2016-11-29 00:31:16 +01:00
/**
* Validate the owner object - check for existence of infinite loops.
*
* @param ValidationResult $validationResult
*/
2016-11-29 00:31:16 +01:00
public function validate(ValidationResult $validationResult)
{
// The object is new, won't be looping.
/** @var DataObject|Hierarchy $owner */
$owner = $this->owner;
if (!$owner->ID) {
2016-11-29 00:31:16 +01:00
return;
}
// The object has no parent, won't be looping.
if (!$owner->ParentID) {
2016-11-29 00:31:16 +01:00
return;
}
// The parent has not changed, skip the check for performance reasons.
if (!$owner->isChanged('ParentID')) {
2016-11-29 00:31:16 +01:00
return;
}
// Walk the hierarchy upwards until we reach the top, or until we reach the originating node again.
$node = $owner;
while ($node && $node->ParentID) {
if ((int)$node->ParentID === (int)$owner->ID) {
// Hierarchy is looping.
$validationResult->addError(
_t(
__CLASS__ . '.InfiniteLoopNotAllowed',
'Infinite loop found within the "{type}" hierarchy. Please change the parent to resolve this',
'First argument is the class that makes up the hierarchy.',
array('type' => get_class($owner))
),
'bad',
'INFINITE_LOOP'
);
break;
}
$node = $node->Parent();
}
}
2016-11-29 00:31:16 +01:00
/**
* Get a list of this DataObject's and all it's descendants IDs.
*
* @return int[]
*/
2016-11-29 00:31:16 +01:00
public function getDescendantIDList()
{
$idList = array();
$this->loadDescendantIDListInto($idList);
return $idList;
}
2016-11-29 00:31:16 +01:00
/**
* Get a list of this DataObject's and all it's descendants ID, and put them in $idList.
*
* @param array $idList Array to put results in.
* @param DataObject|Hierarchy $node
*/
protected function loadDescendantIDListInto(&$idList, $node = null)
2016-11-29 00:31:16 +01:00
{
if (!$node) {
$node = $this->owner;
}
$children = $node->AllChildren();
foreach ($children as $child) {
if (!in_array($child->ID, $idList)) {
$idList[] = $child->ID;
$this->loadDescendantIDListInto($idList, $child);
}
}
}
/**
* Get the children for this DataObject filtered by canView()
*
* @return SS_List
*/
2016-11-29 00:31:16 +01:00
public function Children()
{
if ($this->_cache_children) {
return $this->_cache_children;
}
$this->_cache_children = $this
->owner
->stageChildren(false)
->filterByCallback(function (DataObject $record) {
return $record->canView();
});
return $this->_cache_children;
}
/**
* Return all children, including those 'not in menus'.
*
* @return DataList
*/
2016-11-29 00:31:16 +01:00
public function AllChildren()
{
return $this->owner->stageChildren(true);
}
/**
* 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.
*
* @return ArrayList
*/
public function AllChildrenIncludingDeleted()
2016-11-29 00:31:16 +01:00
{
$stageChildren = $this->owner->stageChildren(true);
2016-11-29 00:31:16 +01:00
// Add live site content that doesn't exist on the stage site, if required.
if ($this->owner->hasExtension(Versioned::class)) {
// Next, go through the live children. Only some of these will be listed
$liveChildren = $this->owner->liveChildren(true, true);
if ($liveChildren) {
$merged = new ArrayList();
$merged->merge($stageChildren);
$merged->merge($liveChildren);
$stageChildren = $merged;
}
}
$this->owner->extend("augmentAllChildrenIncludingDeleted", $stageChildren);
return $stageChildren;
}
2016-11-29 00:31:16 +01:00
/**
* Return all the children that this page had, including pages that were deleted from both stage & live.
*
* @return DataList
* @throws Exception
*/
2016-11-29 00:31:16 +01:00
public function AllHistoricalChildren()
{
if (!$this->owner->hasExtension(Versioned::class)) {
throw new Exception('Hierarchy->AllHistoricalChildren() only works with Versioned extension applied');
}
$baseTable = $this->owner->baseTable();
$parentIDColumn = $this->owner->getSchema()->sqlColumnForField($this->owner, 'ParentID');
return Versioned::get_including_deleted(
$this->owner->baseClass(),
[ $parentIDColumn => $this->owner->ID ],
"\"{$baseTable}\".\"ID\" ASC"
);
}
/**
* Return the number of children that this page ever had, including pages that were deleted.
*
* @return int
*/
2016-11-29 00:31:16 +01:00
public function numHistoricalChildren()
{
return $this->AllHistoricalChildren()->count();
}
2016-11-29 00:31:16 +01:00
/**
* Return the number of direct children. By default, values are cached after the first invocation. Can be
* augumented by {@link augmentNumChildrenCountQuery()}.
*
* @param bool $cache Whether to retrieve values from cache
* @return int
*/
2016-11-29 00:31:16 +01:00
public function numChildren($cache = true)
{
// Load if caching
if ($cache && isset($this->_cache_numChildren)) {
return $this->_cache_numChildren;
}
// We call stageChildren(), because Children() has canView() filtering
$children = (int)$this->owner->stageChildren(true)->Count();
// Save if caching
if ($cache) {
$this->_cache_numChildren = $children;
}
return $children;
}
/**
* Checks if we're on a controller where we should filter. ie. Are we loading the SiteTree?
*
* @return bool
*/
2016-11-29 00:31:16 +01:00
public function showingCMSTree()
{
if (!Controller::has_curr() || !class_exists(LeftAndMain::class)) {
2016-11-29 00:31:16 +01:00
return false;
}
$controller = Controller::curr();
return $controller instanceof LeftAndMain
&& in_array($controller->getAction(), array("treeview", "listview", "getsubtree"));
}
/**
* Return children in the stage site.
*
* @param bool $showAll Include all of the elements, even those not shown in the menus. Only applicable when
* extension is applied to {@link SiteTree}.
* @return DataList
*/
2016-11-29 00:31:16 +01:00
public function stageChildren($showAll = false)
{
$hideFromHierarchy = $this->owner->config()->hide_from_hierarchy;
$hideFromCMSTree = $this->owner->config()->hide_from_cms_tree;
$staged = DataObject::get($this->ownerBaseClass)
->filter('ParentID', (int)$this->owner->ID)
->exclude('ID', (int)$this->owner->ID);
if ($hideFromHierarchy) {
$staged = $staged->exclude('ClassName', $hideFromHierarchy);
}
if ($hideFromCMSTree && $this->showingCMSTree()) {
$staged = $staged->exclude('ClassName', $hideFromCMSTree);
}
if (!$showAll && DataObject::getSchema()->fieldSpec($this->owner, 'ShowInMenus')) {
$staged = $staged->filter('ShowInMenus', 1);
}
$this->owner->extend("augmentStageChildren", $staged, $showAll);
return $staged;
}
/**
* Return children in the live site, if it exists.
*
* @param bool $showAll Include all of the elements, even those not shown in the menus. Only
* applicable when extension is applied to {@link SiteTree}.
* @param bool $onlyDeletedFromStage Only return items that have been deleted from stage
* @return DataList
* @throws Exception
*/
2016-11-29 00:31:16 +01:00
public function liveChildren($showAll = false, $onlyDeletedFromStage = false)
{
if (!$this->owner->hasExtension(Versioned::class)) {
throw new Exception('Hierarchy->liveChildren() only works with Versioned extension applied');
}
$hideFromHierarchy = $this->owner->config()->hide_from_hierarchy;
$hideFromCMSTree = $this->owner->config()->hide_from_cms_tree;
$children = DataObject::get($this->owner->baseClass())
->filter('ParentID', (int)$this->owner->ID)
->exclude('ID', (int)$this->owner->ID)
->setDataQueryParam(array(
'Versioned.mode' => $onlyDeletedFromStage ? 'stage_unique' : 'stage',
'Versioned.stage' => 'Live'
));
if ($hideFromHierarchy) {
$children = $children->exclude('ClassName', $hideFromHierarchy);
}
if ($hideFromCMSTree && $this->showingCMSTree()) {
$children = $children->exclude('ClassName', $hideFromCMSTree);
}
if (!$showAll && DataObject::getSchema()->fieldSpec($this->owner, 'ShowInMenus')) {
$children = $children->filter('ShowInMenus', 1);
}
return $children;
}
/**
* Get this object's parent, optionally filtered by an SQL clause. If the clause doesn't match the parent, nothing
* is returned.
*
* @param string $filter
* @return DataObject
*/
2016-11-29 00:31:16 +01:00
public function getParent($filter = null)
{
$parentID = $this->owner->ParentID;
if (empty($parentID)) {
return null;
}
$idSQL = $this->owner->getSchema()->sqlColumnForField($this->ownerBaseClass, 'ID');
return DataObject::get_one($this->ownerBaseClass, array(
array($idSQL => $parentID),
$filter
));
}
/**
* Return all the parents of this class in a set ordered from the closest to furtherest parent.
*
* @param bool $includeSelf
* @return ArrayList
*/
public function getAncestors($includeSelf = false)
2016-11-29 00:31:16 +01:00
{
$ancestors = new ArrayList();
$object = $this->owner;
2016-11-29 00:31:16 +01:00
if ($includeSelf) {
$ancestors->push($object);
}
while ($object = $object->getParent()) {
$ancestors->push($object);
}
2016-11-29 00:31:16 +01:00
return $ancestors;
}
2016-11-29 00:31:16 +01:00
/**
* Returns a human-readable, flattened representation of the path to the object, using its {@link Title} attribute.
*
* @param string $separator
* @return string
*/
2016-11-29 00:31:16 +01:00
public function getBreadcrumbs($separator = ' &raquo; ')
{
$crumbs = array();
$ancestors = array_reverse($this->owner->getAncestors()->toArray());
/** @var DataObject $ancestor */
2016-11-29 00:31:16 +01:00
foreach ($ancestors as $ancestor) {
$crumbs[] = $ancestor->getTitle();
2016-11-29 00:31:16 +01:00
}
$crumbs[] = $this->owner->getTitle();
return implode($separator, $crumbs);
}
/**
* Flush all Hierarchy caches:
* - Children (instance)
* - NumChildren (instance)
* - Marked (global)
* - Expanded (global)
* - TreeOpened (global)
*/
2016-11-29 00:31:16 +01:00
public function flushCache()
{
$this->_cache_children = null;
$this->_cache_numChildren = null;
}
}