Usage.
*
*
* static $has_one = array(
* 'RightContent' => 'SiteTree'
* );
*
* function getCMSFields() {
* ...
* $treedropdownfield = new TreeDropdownField("RightContentID", "Choose a page to show on the right:", "SiteTree");
* ..
* }
*
*
* This will generate a tree allowing the user to expand and contract subsections
* to find the appropriate page to save to the field.
*
* @see TreeMultiselectField for the same implementation allowing multiple selections
* @see DropdownField for a simple dropdown field.
* @see CheckboxSetField for multiple selections through checkboxes.
* @see OptionsetField for single selections via radiobuttons.
*
* @package forms
* @subpackage fields-relational
*/
class TreeDropdownField extends FormField {
private static $url_handlers = array(
'$Action!/$ID' => '$Action'
);
private static $allowed_actions = array(
'tree'
);
/**
* @ignore
*/
protected $sourceObject, $keyField, $labelField, $filterCallback,
$disableCallback, $searchCallback, $baseID = 0;
/**
* @var string default child method in Hierarchy->getChildrenAsUL
*/
protected $childrenMethod = 'AllChildrenIncludingDeleted';
/**
* @var string default child counting method in Hierarchy->getChildrenAsUL
*/
protected $numChildrenMethod = 'numChildren';
/**
* Used by field search to leave only the relevant entries
*/
protected $searchIds = null, $showSearch, $searchExpanded = array();
/**
* CAVEAT: for search to work properly $labelField must be a database field,
* or you need to setSearchFunction.
*
* @param string $name the field name
* @param string $title the field label
* @param string|array $sourceObject The object-type to list in the tree. This could
* be one of the following:
* - A DataObject class name with the {@link Hierarchy} extension.
* - An array of key/value pairs, like a {@link DropdownField} source. In
* this case, the field will act like show a flat list of tree items,
* without any hierarchy. This is most useful in conjunction with
* {@link TreeMultiselectField}, for presenting a set of checkboxes in
* a compact view. Note, that all value strings must be XML encoded
* safely prior to being passed in.
*
* @param string $keyField to field on the source class to save as the
* field value (default ID).
* @param string $labelField the field name to show as the human-readable
* value on the tree (default Title).
* @param bool $showSearch enable the ability to search the tree by
* entering the text in the input field.
*/
public function __construct($name, $title = null, $sourceObject = 'SilverStripe\\Security\\Group', $keyField = 'ID',
$labelField = 'TreeTitle', $showSearch = true
) {
$this->sourceObject = $sourceObject;
$this->keyField = $keyField;
$this->labelField = $labelField;
$this->showSearch = $showSearch;
//Extra settings for Folders
if ($sourceObject == 'Folder') {
$this->childrenMethod = 'ChildFolders';
$this->numChildrenMethod = 'numChildFolders';
}
$this->addExtraClass('single');
parent::__construct($name, $title);
}
/**
* Set the ID of the root node of the tree. This defaults to 0 - i.e.
* displays the whole tree.
*
* @param int $ID
* @return $this
*/
public function setTreeBaseID($ID) {
$this->baseID = (int) $ID;
return $this;
}
/**
* Set a callback used to filter the values of the tree before
* displaying to the user.
*
* @param callback $callback
* @return $this
*/
public function setFilterFunction($callback) {
if(!is_callable($callback, true)) {
throw new InvalidArgumentException('TreeDropdownField->setFilterCallback(): not passed a valid callback');
}
$this->filterCallback = $callback;
return $this;
}
/**
* Set a callback used to disable checkboxes for some items in the tree
*
* @param callback $callback
* @return $this
*/
public function setDisableFunction($callback) {
if(!is_callable($callback, true)) {
throw new InvalidArgumentException('TreeDropdownField->setDisableFunction(): not passed a valid callback');
}
$this->disableCallback = $callback;
return $this;
}
/**
* Set a callback used to search the hierarchy globally, even before
* applying the filter.
*
* @param callback $callback
* @return $this
*/
public function setSearchFunction($callback) {
if(!is_callable($callback, true)) {
throw new InvalidArgumentException('TreeDropdownField->setSearchFunction(): not passed a valid callback');
}
$this->searchCallback = $callback;
return $this;
}
public function getShowSearch() {
return $this->showSearch;
}
/**
* @param bool $bool
* @return $this
*/
public function setShowSearch($bool) {
$this->showSearch = $bool;
return $this;
}
/**
* @param string $method The parameter to ChildrenMethod to use when calling Hierarchy->getChildrenAsUL in
* {@link Hierarchy}. The method specified determines the structure of the returned list. Use "ChildFolders"
* in place of the default to get a drop-down listing with only folders, i.e. not including the child elements in
* the currently selected folder. setNumChildrenMethod() should be used as well for proper functioning.
*
* See {@link Hierarchy} for a complete list of possible methods.
* @return $this
*/
public function setChildrenMethod($method) {
$this->childrenMethod = $method;
return $this;
}
/**
* @param string $method The parameter to numChildrenMethod to use when calling Hierarchy->getChildrenAsUL in
* {@link Hierarchy}. Should be used in conjunction with setChildrenMethod().
*
* @return $this
*/
public function setNumChildrenMethod($method) {
$this->numChildrenMethod = $method;
return $this;
}
/**
* @param array $properties
* @return string
*/
public function Field($properties = array()) {
Requirements::add_i18n_javascript(FRAMEWORK_DIR . '/client/lang');
Requirements::javascript(FRAMEWORK_DIR . '/thirdparty/jquery/jquery.js');
Requirements::javascript(FRAMEWORK_DIR . '/thirdparty/jquery-entwine/dist/jquery.entwine-dist.js');
Requirements::javascript(FRAMEWORK_DIR . '/thirdparty/jstree/jquery.jstree.js');
Requirements::javascript(FRAMEWORK_DIR . '/client/dist/js/TreeDropdownField.js');
Requirements::css(FRAMEWORK_DIR . '/thirdparty/jquery-ui-themes/smoothness/jquery-ui.css');
Requirements::css(FRAMEWORK_DIR . '/client/dist/styles/TreeDropdownField.css');
$item = DataObject::singleton($this->sourceObject);
$emptyTitle = _t(
'DropdownField.CHOOSE_MODEL',
'(Choose {name})',
['name' => $item->i18n_singular_name()]
);
$record = $this->Value() ? $this->objectForKey($this->Value()) : null;
if($record instanceof ViewableData) {
$title = $record->obj($this->labelField)->forTemplate();
} elseif($record) {
$title = Convert::raw2xml($record->{$this->labelField});
}
else {
$title = $emptyTitle;
}
// TODO Implement for TreeMultiSelectField
$metadata = array(
'id' => $record ? $record->ID : null,
'ClassName' => $record ? $record->ClassName : $this->sourceObject
);
$properties = array_merge(
$properties,
array(
'Title' => $title,
'EmptyTitle' => $emptyTitle,
'Metadata' => ($metadata) ? Convert::raw2json($metadata) : null,
)
);
return parent::Field($properties);
}
public function extraClass() {
return implode(' ', array(parent::extraClass(), ($this->showSearch ? "searchable" : null)));
}
/**
* Get the whole tree of a part of the tree via an AJAX request.
*
* @param SS_HTTPRequest $request
* @return string
* @throws Exception
*/
public function tree(SS_HTTPRequest $request) {
// Array sourceObject is an explicit list of values - construct a "flat tree"
if(is_array($this->sourceObject)) {
$output = "