Fr3nch13/CakePHP Utilities

SelectBoxWidget extends BasicWidget
in package

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.

Table of Contents

Properties

$_templates  : StringTemplate
StringTemplate instance.
$defaults  : array<string, mixed>
Data defaults.

Methods

__construct()  : mixed
Constructor.
render()  : string
Render a select box form input.
secureFields()  : array<string|int, string>
Returns a list of fields that need to be secured for this widget.
_emptyValue()  : array<string|int, mixed>
Generate the empty value based on the input.
_isDisabled()  : bool
Helper method for deciding what options are disabled.
_isSelected()  : bool
Helper method for deciding what options are selected.
_renderContent()  : array<string|int, string>
Render the contents of the select element.
_renderOptgroup()  : string
Render the contents of an optgroup element.
_renderOptions()  : array<string|int, string>
Render a set of options.
mergeDefaults()  : array<string, mixed>
Merge default values with supplied data.
setMaxLength()  : array<string, mixed>
Set value for "maxlength" attribute if applicable.
setRequired()  : array<string, mixed>
Set value for "required" attribute if applicable.
setStep()  : array<string, mixed>
Set value for "step" attribute if applicable.

Properties

$defaults

Data defaults.

protected array<string, mixed> $defaults = ['name' => '', 'empty' => false, 'escape' => true, 'options' => [], 'disabled' => null, 'val' => null, 'templateVars' => []]

Methods

render()

Render a select box form input.

public render(array<string, mixed> $data, ContextInterface $context) : string

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
$data : array<string, mixed>

Data to render with.

$context : ContextInterface

The current form context.

Tags
throws
RuntimeException

when the name attribute is empty.

Return values
string —

A generated select box.

secureFields()

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

public secureFields(array<string|int, mixed> $data) : array<string|int, string>
Parameters
$data : array<string|int, mixed>

The data to render.

Tags
inheritDoc
Return values
array<string|int, string> —

Array of fields to secure.

_emptyValue()

Generate the empty value based on the input.

protected _emptyValue(array<string|int, mixed>|string|bool $value) : array<string|int, mixed>
Parameters
$value : array<string|int, mixed>|string|bool

The provided empty value.

Return values
array<string|int, mixed> —

The generated option key/value.

_isDisabled()

Helper method for deciding what options are disabled.

protected _isDisabled(string $key, array<string|int, string>|null $disabled) : bool
Parameters
$key : string

The key to test.

$disabled : array<string|int, string>|null

The disabled values.

Return values
bool

_isSelected()

Helper method for deciding what options are selected.

protected _isSelected(string $key, array<string|int, string>|string|int|false|null $selected) : bool
Parameters
$key : string

The key to test.

$selected : array<string|int, string>|string|int|false|null

The selected values.

Return values
bool

_renderContent()

Render the contents of the select element.

protected _renderContent(array<string, mixed> $data) : array<string|int, string>
Parameters
$data : array<string, mixed>

The context for rendering a select.

Return values
array<string|int, string>

_renderOptgroup()

Render the contents of an optgroup element.

protected _renderOptgroup(string $label, ArrayAccess|array<string|int, mixed> $optgroup, array<string|int, mixed>|null $disabled, array<string|int, mixed>|string|null $selected, array<string|int, mixed> $templateVars, bool $escape) : string
Parameters
$label : string

The optgroup label text

$optgroup : ArrayAccess|array<string|int, mixed>

The opt group data.

$disabled : array<string|int, mixed>|null

The options to disable.

$selected : array<string|int, mixed>|string|null

The options to select.

$templateVars : array<string|int, mixed>

Additional template variables.

$escape : bool

Toggle HTML escaping

Return values
string —

Formatted template string

_renderOptions()

Render a set of options.

protected _renderOptions(iterable<string|int, mixed> $options, array<string|int, string>|null $disabled, array<string|int, mixed>|string|null $selected, array<string|int, mixed> $templateVars, bool $escape) : array<string|int, string>

Will recursively call itself when option groups are in use.

Parameters
$options : iterable<string|int, mixed>

The options to render.

$disabled : array<string|int, string>|null

The options to disable.

$selected : array<string|int, mixed>|string|null

The options to select.

$templateVars : array<string|int, mixed>

Additional template variables.

$escape : bool

Toggle HTML escaping.

Return values
array<string|int, string> —

Option elements.

mergeDefaults()

Merge default values with supplied data.

protected mergeDefaults(array<string, mixed> $data, ContextInterface $context) : array<string, mixed>
Parameters
$data : array<string, mixed>

Data array

$context : ContextInterface

Context instance.

Return values
array<string, mixed> —

Updated data array.

setMaxLength()

Set value for "maxlength" attribute if applicable.

protected setMaxLength(array<string, mixed> $data, ContextInterface $context, string $fieldName) : array<string, mixed>
Parameters
$data : array<string, mixed>

Data array

$context : ContextInterface

Context instance.

$fieldName : string

Field name.

Return values
array<string, mixed> —

Updated data array.

setRequired()

Set value for "required" attribute if applicable.

protected setRequired(array<string, mixed> $data, ContextInterface $context, string $fieldName) : array<string, mixed>
Parameters
$data : array<string, mixed>

Data array

$context : ContextInterface

Context instance.

$fieldName : string

Field name.

Return values
array<string, mixed> —

Updated data array.

setStep()

Set value for "step" attribute if applicable.

protected setStep(array<string, mixed> $data, ContextInterface $context, string $fieldName) : array<string, mixed>
Parameters
$data : array<string, mixed>

Data array

$context : ContextInterface

Context instance.

$fieldName : string

Field name.

Return values
array<string, mixed> —

Updated data array.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results