User Tools

Site Tools

Helper Field 'text'

Field 'text' is a vanilla, one line HTML input:

Panel with a Helper generated text field.

Panel with a Helper generated text field.

Code used to generate this screenshot is the code below.

PHP Code

'MYCONTROLLER_OPTION' => [
    'type'          => 'text',
    'title'         => $this->l('Field title:'),
    'required'      => true,
    'hint'          => $this->l('This is the hint.'),
    'desc'          => $this->l('Description of the field.'),
    'suffix'        => $this->l('units'),
    'auto_value'    => true,
    'no_escape'     => true,
    'placeholder'   => $this->l('placeholder text'),
    'autocomplete'  => true,
    'id'            => 'myid',
    'class'         => 'myclass',
    'size'          => 10,
    'default'       => 0,
    'cast'          => 'intval',
    'validation'    => 'isInt',
    'empty'         => false,
]

Parameter Description

'type'

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

'title'

Text to be displayed just above the HTML input 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 input. HTML allowed. Optional.

'suffix'

Text displayed visually as part of the HTML input, but behind a separating line. Typically used for units like kg, days, etc. HTML allowed. Optional.

'auto_value'

Whether Helper should grab the currently set value 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.

'value'

Set HTML input value to 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.

'no_escape'

Whether the field value grabbed from the database should be escaped for HTML. Defaults to false.

'placeholder'

Parameter placeholder added to the HTML input, which displays placeholder text. Plain text, no HTML. Optional.

'autocomplete'

If set, but false, the HTML input gets an autocomplete=“off” added. If it's set and true, or not set, no such parameter gets added.

'id'

HTML ID added to the HTML input. Optional.

'class'

CSS class added to the HTML input. Optional.

'size'

Parameter size added to the HTML input. Currently this gets overridden by CSS, text fields expand to the available width of the surrounding panel. Defaults to 5.

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'

Name of a PHP casting function to convert the submitted value with. Can be boolval, floatval, priceval or intval. Default is to store a string.

'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">
    <div class="input-group myclass">
      <input class="form-control myclass"
             id="myid"
             size="10"
             name="MYCONTROLLER_OPTION"
             value=""
             placeholder="placeholder text"
             type="text">
      <span class="input-group-addon">units</span>
    </div>
  </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_text.txt · Last modified: 2019/02/22 18:40 by Traumflug