User Tools

Site Tools

Helper Field 'select'

Field 'select' is a HTML select element, which is a dropdown menu or a selection list, depending on parameter 'size':

Panel with a Helper generated select, //'size'// = 1.

Panel with a Helper generated select, 'size' = 1.

Panel with a Helper generated select, //'size'// = 5.

Panel with a Helper generated select, 'size' = 5.

Code used to generate these screenshots is the code below. Both variants allow a single selection, only. For multiple selections, there's Helper field 'checkbox'.

PHP Code

'MYCONTROLLER_OPTION' => [
    'type'          => 'select',
    'title'         => $this->l('Field title:'),
    'required'      => true,
    'hint'          => $this->l('This is the hint.'),
    'desc'          => $this->l('Description of the field.'),
    'auto_value'    => false,
    'identifier'    => 'my_use',
    'value'         => 'bar',
    'list'          => [
        [
            'my_use'  => 'foo',
            'name'    => $this->l('Use Foo!'),
        ],
        [
            'my_use'  => 'bar',
            'name'    => $this->l('Use bar!'),
        ],
        [
            'my_use'  => 'baz',
            'name'    => $this->l('Use BAZ!'),
        ],
    ],
    'empty_message' => $this->l('List empty.'),
    'class'         => 'myclass',
    'size'          => 1,
    'js'            => 'selectionChanged();',
    'default'       => 'foo',
    'empty'         => false,
]

Parameter Description

'type'

Always 'select' for this type of field. Mandatory.

'title'

Text to be displayed just above the HTML select field. HTML allowed. Optional, but recommended.

'required'

Whether there should be this red star in front of the title. Defaults to false. Setting it to true also makes sure that the entire submitted data gets stored only if there's valid data in this field.

'hint'

Text to be displayed as a tooltip / HTML title. Current back office theme also gives the field title a blue background if such a hint is present. HTML allowed. Optional.

'desc'

More verbose description of the field. Often a text filling multiple lines. Appears in italics and lighter color just below the HTML select. HTML allowed. Optional.

'auto_value'

Whether Helper should grab the currently selected menu entry for the configuration option automatically from POST request parameters, and if there is no such parameter, from the database. Supersedes 'value'. Defaults to true.

'defaultValue'

Value to use if 'auto_value' is unset or set to true, but neither a matching POST request parameter, nor a matching database entry is present. Defaults to an empty string.

'identifier'

String which identifies the key in these pairs inside entries in 'list'. Mandatory.

'value'

Select the HTML menu entry with this value. Requires 'auto_value' to be set to false. Defaults to an empty string.

Notably, as Option Fields are usually set in the class constructor, this value gets set before default procedures had a chance to process the incoming request. Accordingly, setting a value here should parse the request as needed while doing so. Else the shown value is always one version behind.

'list'

List of options to fill the HTML select with. Each option is an array with two key-value pairs. Mandatory. An empty array gives no selector at all. To get an empty selector, e.g. to fill it with JavaScript, define an entry with a pair of empty strings.

'list':[identifier]

First key-value pair for list options. Key must match the defined 'identifier'. Value get used as parameter value for the HTML option.

'list':'name'

Second key-value pair for list options. Key is always 'name'. Value get used as text for the HTML option.

'empty_message'

HTML select gets replaced by this text in case 'list' is an empty array. HTML allowed. Optional.

'cast'

Name of a PHP casting function to convert the submitted value with. Unlike with other Helper fields, this cast gets applied to each menu option before rendering as well as after submit. Can be boolval, floatval, priceval or intval. Default is a string.

'class'

CSS class added to the HTML select. Optional.

'size'

Parameter size added to the HTML select. Defaults to no parameter added. Notably, this has substantial impact on how the HTML element get rendered: size 1 or smaller renders a dropdown menu, bigger numbers render a selection list. Lists for multiple selections are currently not supported.

'js'

JavaScript to execute on selection change (HTML onchange event). Defaults to nothing.

Parameters for Submit

The following parameters describe how submitted field values is dealt with. Ignored if data isn't going to be stored in the database.

'required'

(see above)

'default'

Default value to get stored in the database, in case the submitted field is empty. Optional.

'cast'

(see above)

'validation'

Name of a method in class Validate to check the submitted field value against. Optional.

'empty'

Set to true, if an empty field should also pass validation. Optional.

Common to All

Note that $this->l(), the translation method, removes HTML directives. If HTML as well as a translation is needed, it can be done like this:

'<b>'.$this->l('translatable text').'</b>'

Unclear

During evaluation and code investigation, a couple of parameters appeared which were not entirely clear. Maybe code no longer in use, maybe half-finished new code.

'is_invisible' appears in PS' documentation as settable, but gets overwritten in HelperOptions->generateOptions().

'visibility', 'is_disabled', 'is_invisible', 'multishop_default', 'hide_multishop_checkbox', 'no_multishop_checkbox' all appear in HelperOptions->generateOptions(), as well as in options.tpl, but are hard to test. They're apparently related to enabling/disabling/hiding fields depending on shop context in multishop environments.

HTML Output

Ignoring whitespace, one gets this HTML:

<div id="conf_id_MYCONTROLLER_OPTION">
  <label class="control-label col-lg-3 required">
    <span title=""
          data-toggle="tooltip"
          class="label-tooltip"
          data-original-title="This is the hint."
          data-html="true">
      Field title:
    </span>
  </label>
  <div class="col-lg-9">
    <select class="form-control fixed-width-xxl myclass"
            name="MYCONTROLLER_OPTION"
            onchange="selectionChanged();"
            id="MYCONTROLLER_OPTION"
            size="1">
      <option value="foo">Use Foo!</option>
      <option value="bar" selected="selected">Use bar!</option>
      <option value="baz">Use BAZ!</option>
    </select>
  </div>
  <div class="col-lg-9 col-lg-offset-3">
    <div class="help-block">
      Description of the field.
    </div>
  </div>
</div>

Notable is that most parameter related elements get defined in HTML directly, while 'hint' gets added by JavaScript and the 'required' star by CSS.

helper_field_select.txt ยท Last modified: 2019/02/22 18:39 by Traumflug