silverstripe-framework/src/Forms/DropdownField.php

147 lines
3.7 KiB
PHP
Raw Normal View History

<?php
namespace SilverStripe\Forms;
use SilverStripe\ORM\ArrayList;
use SilverStripe\View\ArrayData;
2016-06-23 01:37:22 +02:00
/**
* Dropdown field, created from a select tag.
2014-08-15 08:53:05 +02:00
*
* <b>Setting a $has_one relation</b>
2014-08-15 08:53:05 +02:00
*
* Using here an example of an art gallery, with Exhibition pages,
* each of which has a Gallery they belong to. The Gallery class is also user-defined.
* <code>
2016-11-29 00:31:16 +01:00
* static $has_one = array(
* 'Gallery' => 'Gallery',
* );
2014-08-15 08:53:05 +02:00
*
2016-11-29 00:31:16 +01:00
* public function getCMSFields() {
* $fields = parent::getCMSFields();
* $field = DropdownField::create('GalleryID', 'Gallery', Gallery::get()->map('ID', 'Title'))
* ->setEmptyString('(Select one)');
* $fields->addFieldToTab('Root.Content', $field, 'Content');
* </code>
2014-08-15 08:53:05 +02:00
*
* As you see, you need to put "GalleryID", rather than "Gallery" here.
2014-08-15 08:53:05 +02:00
*
* <b>Populate with Array</b>
2014-08-15 08:53:05 +02:00
*
* Example model definition:
* <code>
* class MyObject extends DataObject {
* static $db = array(
* 'Country' => "Varchar(100)"
* );
* }
* </code>
2014-08-15 08:53:05 +02:00
*
* Example instantiation:
* <code>
* DropdownField::create(
* 'Country',
* 'Country',
* array(
* 'NZ' => 'New Zealand',
* 'US' => 'United States',
* 'GEM'=> 'Germany'
* )
* );
* </code>
2014-08-15 08:53:05 +02:00
*
* <b>Populate with Enum-Values</b>
2014-08-15 08:53:05 +02:00
*
* You can automatically create a map of possible values from an {@link Enum} database column.
2014-08-15 08:53:05 +02:00
*
* Example model definition:
* <code>
* class MyObject extends DataObject {
* static $db = array(
* 'Country' => "Enum('New Zealand,United States,Germany','New Zealand')"
* );
* }
* </code>
2014-08-15 08:53:05 +02:00
*
* Field construction:
* <code>
* DropdownField::create(
* 'Country',
* 'Country',
* singleton('MyObject')->dbObject('Country')->enumValues()
* );
* </code>
2014-08-15 08:53:05 +02:00
*
* <b>Disabling individual items</b>
2014-08-15 08:53:05 +02:00
*
* Individual items can be disabled by feeding their array keys to setDisabledItems.
2014-08-15 08:53:05 +02:00
*
* <code>
* $DrDownField->setDisabledItems( array( 'US', 'GEM' ) );
* </code>
2014-08-15 08:53:05 +02:00
*
* @see CheckboxSetField for multiple selections through checkboxes instead.
* @see ListboxField for a single <select> box (with single or multiple selections).
* @see TreeDropdownField for a rich and customizeable UI that can visualize a tree of selectable elements
*/
2016-11-29 00:31:16 +01:00
class DropdownField extends SingleSelectField
{
2016-11-29 00:31:16 +01:00
/**
* Build a field option for template rendering
*
* @param mixed $value Value of the option
* @param string $title Title of the option
* @return ArrayData Field option
*/
protected function getFieldOption($value, $title)
{
// Check selection
$selected = $this->isSelectedValue($value, $this->Value());
2016-11-29 00:31:16 +01:00
// Check disabled
$disabled = false;
if ($this->isDisabledValue($value) && $title != $this->getEmptyString()) {
$disabled = 'disabled';
}
2014-08-15 08:53:05 +02:00
return new ArrayData([
'Title' => (string)$title,
2016-11-29 00:31:16 +01:00
'Value' => $value,
'Selected' => $selected,
'Disabled' => $disabled,
]);
2016-11-29 00:31:16 +01:00
}
2014-08-15 08:53:05 +02:00
/**
* A required DropdownField must have a user selected attribute,
* so require an empty default for a required field
*
* @return bool
*/
public function getHasEmptyDefault()
{
return parent::getHasEmptyDefault() || $this->Required();
}
2016-11-29 00:31:16 +01:00
/**
* @param array $properties
* @return string
*/
public function Field($properties = [])
2016-11-29 00:31:16 +01:00
{
$options = [];
2016-11-29 00:31:16 +01:00
// Add all options
foreach ($this->getSourceEmpty() as $value => $title) {
$options[] = $this->getFieldOption($value, $title);
}
$properties = array_merge($properties, [
2016-11-29 00:31:16 +01:00
'Options' => new ArrayList($options)
]);
2016-11-29 00:31:16 +01:00
return parent::Field($properties);
}
}