silverstripe-framework/forms/ListboxField.php

271 lines
7.2 KiB
PHP

<?php
/**
* Multi-line listbox field, created from a <select> tag.
*
* <b>Usage</b>
*
* <code>
* new ListboxField(
* $name = "pickanumber",
* $title = "Pick a number",
* $source = array(
* "1" => "one",
* "2" => "two",
* "3" => "three"
* ),
* $value = 1
* )
* </code>
*
* @see DropdownField for a simple <select> field with a single element.
* @see CheckboxSetField for multiple selections through checkboxes.
* @see OptionsetField for single selections via radiobuttons.
* @see TreeDropdownField for a rich and customizeable UI that can visualize a tree of selectable elements
*
* @package forms
* @subpackage fields-basic
*/
class ListboxField extends DropdownField {
/**
* The size of the field in rows.
* @var int
*/
protected $size;
/**
* Should the user be able to select multiple
* items on this dropdown field?
*
* @var boolean
*/
protected $multiple = false;
/**
* @var Array
*/
protected $disabledItems = array();
/**
* @var Array
*/
protected $defaultItems = array();
/**
* Creates a new dropdown field.
*
* @param string $name The field name
* @param string $title The field title
* @param array $source An map of the dropdown items
* @param string|array $value You can pass an array of values or a single value like a drop down to be selected
* @param int $size Optional size of the select element
* @param form The parent form
*/
function __construct($name, $title = '', $source = array(), $value = '', $size = null, $multiple = false) {
if($size) $this->size = $size;
if($multiple) $this->multiple = $multiple;
parent::__construct($name, $title, $source, $value);
}
/**
* Returns a <select> tag containing all the appropriate <option> tags
*/
function Field($properties = array()) {
if($this->multiple) $this->name .= '[]';
$options = array();
// We have an array of values
if(is_array($this->value)){
// Loop through and figure out which values were selected.
foreach($this->getSource() as $value => $title) {
$options[] = new ArrayData(array(
'Title' => $title,
'Value' => $value,
'Selected' => (in_array($value, $this->value) || in_array($value, $this->defaultItems)),
'Disabled' => $this->disabled || in_array($value, $this->disabledItems),
));
}
} else {
// Listbox was based a singlular value, so treat it like a dropdown.
foreach($this->getSource() as $value => $title) {
$options[] = new ArrayData(array(
'Title' => $title,
'Value' => $value,
'Selected' => ($value == $this->value || in_array($value, $this->defaultItems)),
'Disabled' => $this->disabled || in_array($value, $this->disabledItems),
));
}
}
$properties = array_merge($properties, array('Options' => new ArrayList($options)));
return $this->customise($properties)->renderWith($this->getTemplate());
}
function getAttributes() {
return array_merge(
parent::getAttributes(),
array(
'multiple' => $this->multiple,
'size' => $this->size
)
);
}
/**
* Sets the size of this dropdown in rows.
* @param int $size The height in rows (e.g. 3)
*/
function setSize($size) {
$this->size = $size;
return $this;
}
/**
* Sets this field to have a muliple select attribute
* @param boolean $bool
*/
function setMultiple($bool) {
$this->multiple = $bool;
return $this;
}
function setSource($source) {
if($source) {
$hasCommas = array_filter(array_keys($source), create_function('$key', 'return strpos($key, ",") !== FALSE;'));
if($hasCommas) {
throw new InvalidArgumentException('No commas allowed in $source keys');
}
}
parent::setSource($source);
return $this;
}
/**
* Return the CheckboxSetField value as a string
* selected item keys.
*
* @return string
*/
function dataValue() {
if($this->value && is_array($this->value) && $this->multiple) {
$filtered = array();
foreach($this->value as $item) {
if($item) {
$filtered[] = str_replace(",", "{comma}", $item);
}
}
return implode(',', $filtered);
} else {
return parent::dataValue();
}
}
/**
* Save the current value of this field into a DataObject.
* If the field it is saving to is a has_many or many_many relationship,
* it is saved by setByIDList(), otherwise it creates a comma separated
* list for a standard DB text/varchar field.
*
* @param DataObject $record The record to save into
*/
function saveInto(DataObject $record) {
if($this->multiple) {
$fieldname = $this->name;
if($fieldname && $record && ($record->has_many($fieldname) || $record->many_many($fieldname))) {
$idList = (is_array($this->value)) ? array_values($this->value) : array();
if(!$record->ID) $record->write(); // record needs to have an ID in order to set relationships
$record->$fieldname()->setByIDList($idList);
} elseif($fieldname && $record) {
if($this->value) {
$this->value = str_replace(',', '{comma}', $this->value);
$record->$fieldname = implode(",", $this->value);
} else {
$record->$fieldname = null;
}
}
} else {
parent::saveInto($record);
}
}
/**
* Load a value into this CheckboxSetField
*/
function setValue($val, $obj = null) {
// If we're not passed a value directly,
// we can look for it in a relation method on the object passed as a second arg
if(!$val && $obj && $obj instanceof DataObject && $obj->hasMethod($this->name)) {
$funcName = $this->name;
$val = array_values($obj->$funcName()->getIDList());
}
if($val) {
if(!$this->multiple && is_array($val)) {
throw new InvalidArgumentException('No array values allowed with multiple=false');
}
if($this->multiple) {
$parts = (is_array($val)) ? $val : preg_split("/ *, */", trim($val));
if(ArrayLib::is_associative($parts)) {
throw new InvalidArgumentException('No associative arrays allowed multiple=true');
}
// Doesn't check against unknown values in order to allow for less rigid data handling.
// They're silently ignored and overwritten the next time the field is saved.
parent::setValue($parts);
} else {
if(!in_array($val, array_keys($this->source))) {
throw new InvalidArgumentException(sprintf(
'Invalid value "%s" for multiple=false',
Convert::raw2xml($val)
));
}
parent::setValue($val);
}
} else {
parent::setValue($val);
}
return $this;
}
/**
* Mark certain elements as disabled,
* regardless of the {@link setDisabled()} settings.
*
* @param array $items Collection of array keys, as defined in the $source array
*/
function setDisabledItems($items) {
$this->disabledItems = $items;
return $this;
}
/**
* @return Array
*/
function getDisabledItems() {
return $this->disabledItems;
}
/**
* Default selections, regardless of the {@link setValue()} settings.
* Note: Items marked as disabled through {@link setDisabledItems()} can still be
* selected by default through this method.
*
* @param Array $items Collection of array keys, as defined in the $source array
*/
function setDefaultItems($items) {
$this->defaultItems = $items;
return $this;
}
/**
* @return Array
*/
function getDefaultItems() {
return $this->defaultItems;
}
}