Class SelectBoxWidget

Input widget class for generating a selectbox.

This class is usually used internally by Cake\View\Helper\FormHelper, it but can be used to generate standalone select boxes.

Namespace: Cake\View\Widget

Properties summary

  • $_templates protected
    \Cake\View\StringTemplate

    StringTemplate instance.

  • $defaults protected
    array

    Data defaults.

Method Summary

  • __construct() public

    Constructor.

  • _emptyValue() protected

    Generate the empty value based on the input.

  • _isDisabled() protected

    Helper method for deciding what options are disabled.

  • _isSelected() protected

    Helper method for deciding what options are selected.

  • _renderContent() protected

    Render the contents of the select element.

  • _renderOptgroup() protected

    Render the contents of an optgroup element.

  • _renderOptions() protected

    Render a set of options.

  • mergeDefaults() protected

    Merge default values with supplied data.

  • render() public

    Render a select box form input.

  • secureFields() public

    Returns a list of fields that need to be secured for this widget.

  • setMaxLength() protected

    Set value for "maxlength" attribute if applicable.

  • setRequired() protected

    Set value for "required" attribute if applicable.

  • setStep() protected

    Set value for "step" attribute if applicable.

Method Detail

__construct() public 

__construct(\Cake\View\StringTemplate $templates)

Constructor.

Parameters

\Cake\View\StringTemplate $templates

Templates list.

_emptyValue() protected 

_emptyValue(mixed $value)

Generate the empty value based on the input.

Parameters

string|bool|array $value

The provided empty value.

Returns

array

The generated option key/value.

_isDisabled() protected 

_isDisabled(string $key, ?array $disabled)

Helper method for deciding what options are disabled.

Parameters

string $key

The key to test.

string[]|null $disabled

The disabled values.

Returns

bool

_isSelected() protected 

_isSelected(string $key, mixed $selected)

Helper method for deciding what options are selected.

Parameters

string $key

The key to test.

string[]|string|false|null $selected

The selected values.

Returns

bool

_renderContent() protected 

_renderContent(array $data)

Render the contents of the select element.

Parameters

array $data

The context for rendering a select.

Returns

array

_renderOptgroup() protected 

_renderOptgroup(string $label, mixed $optgroup, ?array $disabled, mixed $selected, mixed $templateVars, mixed $escape)

Render the contents of an optgroup element.

Parameters

string $label

The optgroup label text

array|\ArrayAccess $optgroup

The opt group data.

array|null $disabled

The options to disable.

array|string|null $selected

The options to select.

array $templateVars

Additional template variables.

bool $escape

Toggle HTML escaping

Returns

string

Formatted template string

_renderOptions() protected 

_renderOptions(iterable $options, ?array $disabled, mixed $selected, mixed $templateVars, mixed $escape)

Render a set of options.

Will recursively call itself when option groups are in use.

Parameters

iterable $options

The options to render.

array|null $disabled

The options to disable.

array|string|null $selected

The options to select.

array $templateVars

Additional template variables.

bool $escape

Toggle HTML escaping.

Returns

string[]

Option elements.

mergeDefaults() protected 

mergeDefaults(array $data, \Cake\View\Form\ContextInterface $context)

Merge default values with supplied data.

Parameters

array $data

Data array

\Cake\View\Form\ContextInterface $context

Context instance.

Returns

array

Updated data array.

render() public 

render(array $data, \Cake\View\Form\ContextInterface $context)

Render a select box form input.

Render a select box input given a set of data. Supported keys are:

  • name - Set the input name.
  • options - An array of options.
  • disabled - Either true or an array of options to disable. When true, the select element will be disabled.
  • val - Either a string or an array of options to mark as selected.
  • empty - Set to true to add an empty option at the top of the option elements. Set to a string to define the display text of the empty option. If an array is used the key will set the value of the empty option while, the value will set the display text.
  • escape - Set to false to disable HTML escaping.

Options format

The options option can take a variety of data format depending on the complexity of HTML you want generated.

You can generate simple options using a basic associative array:

'options' => ['elk' => 'Elk', 'beaver' => 'Beaver']

If you need to define additional attributes on your option elements you can use the complex form for options:

'options' => [
  ['value' => 'elk', 'text' => 'Elk', 'data-foo' => 'bar'],
]

This form requires that both the value and text keys be defined. If either is not set options will not be generated correctly.

If you need to define option groups you can do those using nested arrays:

'options' => [
 'Mammals' => [
   'elk' => 'Elk',
   'beaver' => 'Beaver'
 ]
]

And finally, if you need to put attributes on your optgroup elements you can do that with a more complex nested array form:

'options' => [
  [
    'text' => 'Mammals',
    'data-id' => 1,
    'options' => [
      'elk' => 'Elk',
      'beaver' => 'Beaver'
    ]
 ],
]

You are free to mix each of the forms in the same option set, and nest complex types as required.

Parameters

array $data

Data to render with.

\Cake\View\Form\ContextInterface $context

The current form context.

Returns

string

A generated select box.

Throws

RuntimeException
when the name attribute is empty.

secureFields() public 

secureFields(array $data)

Returns a list of fields that need to be secured for this widget.

Parameters

array $data

The data to render.

Returns

string[]

Array of fields to secure.

setMaxLength() protected 

setMaxLength(array $data, \Cake\View\Form\ContextInterface $context, string $fieldName)

Set value for "maxlength" attribute if applicable.

Parameters

array $data

Data array

\Cake\View\Form\ContextInterface $context

Context instance.

string $fieldName

Field name.

Returns

array

Updated data array.

setRequired() protected 

setRequired(array $data, \Cake\View\Form\ContextInterface $context, string $fieldName)

Set value for "required" attribute if applicable.

Parameters

array $data

Data array

\Cake\View\Form\ContextInterface $context

Context instance.

string $fieldName

Field name.

Returns

array

Updated data array.

setStep() protected 

setStep(array $data, \Cake\View\Form\ContextInterface $context, string $fieldName)

Set value for "step" attribute if applicable.

Parameters

array $data

Data array

\Cake\View\Form\ContextInterface $context

Context instance.

string $fieldName

Field name.

Returns

array

Updated data array.

Property Detail

$_templates protected

StringTemplate instance.

Type

\Cake\View\StringTemplate

$defaults protected

Data defaults.

Type

array

© 2005–present The Cake Software Foundation, Inc.
Licensed under the MIT License.
CakePHP is a registered trademark of Cake Software Foundation, Inc.
We are not endorsed by or affiliated with CakePHP.
https://api.cakephp.org/4.1/class-Cake.View.Widget.SelectBoxWidget.html