waHtmlControl

In most cases, to obtain HTML code of a form element, it is sufficient to simply call method getControl.

In order to create an element of a custom type, first call method registerControl, which must return HTML of such a custom element. Then call method getControl by passing your custom element type ID as its parameter.

Methods

addNamespace
Adds namespace to the value of name attribute of a control.
getControl
Returns control's HTML code.
registerControl
Adds a custom control type to the list of available ones.

public static final function addNamespace (&$params, $namespace = '')

Adds namespace to the value of name attribute of a control. The namespace is added through generation of an array variable name where the single array key is the original control name value.

Parameters

&$params
Array of control parameters as described for getControl method.
$namespace
Namespace value in the form of a string or an array of strings. If simple string value is specified, then the name of the variable sent to the server becomes the specified namespace value, and the single key of the sent array variable becomes the original name value. If an array is specified, then the first array item becomes the name of the variable sent to the server, each subsequent array item becomes the single key of a nested sub-array, and the original name value becomes the single key of the most deeply nested sub-array.

Example

$params = [];
waHtmlControl::addNamespace($params, 'some');
$control = waHtmlControl::getControl(waHtmlControl::INPUT, 'test', $params);

Result

<input ... name="some[test]" ...>

Example

$params = [];
waHtmlControl::addNamespace($params, ['some', 'other']);
$control = waHtmlControl::getControl(waHtmlControl::INPUT, 'test', $params);

Result

<input ... name="some[other][test]" ...>

public static function getControl ($type, $name, $params = [])

Returns control's HTML code.

Parameters

$type
Control type: one of default values or a custom control type, which must be registered in previous code using registerControl method.

Default control types:
- waHtmlControl::CHECKBOX: tag <input type="checkbox">
- waHtmlControl::CONTACTFIELD: drop-down list of contact fields.
- waHtmlControl::FILE: tag <input type="file">
- waHtmlControl::GROUPBOX: group of tags <input type="checkbox>
- waHtmlControl::HELP: tag <p> with text
- waHtmlControl::HIDDEN: tag <input type="hidden>
- waHtmlControl::INPUT: tag <input type="text">
- waHtmlControl::PASSWORD: tag <input type="password">
- waHtmlControl::RADIOGROUP: group of tags <input type="radio">
- waHtmlControl::SELECT: tag <select>
- waHtmlControl::TEXTAREA: tag <textarea>
- waHtmlControl::TITLE: tag <h3> as a header
- waHtmlControl::COLORPICKER: field for convenient color selection
- waHtmlControl::CUSTOM: custom element generated by your app or plugin
$name
String to be used as the value of the name attribute, with the 'namespace' value specified in control parameters taken into account.
$params
Parameters used for generating controls of different types.
- waHtmlControl::CHECKBOX
  - value: value of value attribute; defaults to 1.
  - class: value of class attribute.
  - style: value of style attribute.
  - title: value of title attribute.
  - checked: optional flag requiring to add attribute checked; defaults to false.
- waHtmlControl::CONTACTFIELD
  - value: ID of contact field which must be auto-selected in the drop-down list.
- waHtmlControl::FILE
  - class: value of class attribute.
  - style: value of style attribute.
- waHtmlControl::GROUPBOX
  - options: array of checkbox type elements data. Two modes of specifying the data array are supported:
    
    Mode 1: the key of each array item is the value for the name attribute of the corresponding checkbox element, and its value is the text caption to be displayed next to the checkbox element; e.g.:
```
'options' => [
    1 => 'first',
    2 => 'second',
    3 => 'third',
],
```
    Mode 2: each array item is a sub-array with keys 'value' and 'title' containing the value for the name attribute and the text caption respectively; e.g.:
```
'options' => [
    [
        'value' => 1,
        'title' => 'first',
    ],
    [
        'value' => 2,
        'title' => 'second',
    ],
    [
        'value' => 3,
        'title' => 'third',
    ],
],
```
    Instead of specifying a fixed array of options using the 'options' element, you can assign a dynamically generated set of options using a 'options_callback' element with a callable type value. Example:
```
'options_callback' => ['appMyClass', 'myCallbackMethod'],
```
    An array of options must be generated by the method specified within a callable type value.
  - value: an array of values for name attribute specified in 'options' array, corresponding to the checkbox elements which must be checked by default.
  - options_wrapper: array of parameters used to apply custom design to individual CHECKBOX within common GROUPBOX element:
    - title_wrapper: wrapper around title next to CHECKBOX element; default value: ' %s',
    - description_wrapper: wrapper around description next to CHECKBOX element; default value: '<span class="hint">%s</span>',
    - control_separator: HTML code added between individual CHECKBOX elements; default value: '<br>',
    - custom_control_separator: HTML code to override the value of control_separator.
- waHtmlControl::HELP
  - value: text to be added inside tag <p>.
  - class: value of class attribute.
- waHtmlControl::HIDDEN
  - value: value of value attribute.
  - class: value of class attribute.
- waHtmlControl::INPUT and waHtmlControl::PASSWORD
  - value: value of value attribute.
  - class: value of class attribute.
  - style: value of style attribute.
  - size: value of size attribute.
  - maxlength: value of maxlength attribute.
  - placeholder: value of placeholder attribute.
  - readonly: flag requiring to add attribute readonly; defaults to false.
  - autocomplete: flag requiring to add attribute autocomplete="on|off"; by default, the attribute is not added.
  - autofocus: flag requiring to add attribute autofocus; defaults to false.
- waHtmlControl::RADIOGROUP
  - options: array of radio type elements data. Two modes of specifying the data array are supported:
    
    Mode 1: the key of each array item is the value of the value attribute of the corresponding radio element, and its value is the text caption to be displayed next to the radio element; e.g.:
```
'options' => [
    1 => 'first',
    2 => 'second',
    3 => 'third',
],
```
    Mode 2: each array item is a sub-array with keys 'value' and 'title' containing the value of the value attribute and the text caption respectively; e.g.:
```
'options' => [
    [
        'value' => 1,
        'title' => 'first',
    ],
    [
        'value' => 2,
        'title' => 'second',
    ],
    [
        'value' => 3,
        'title' => 'third',
    ],
],
```
    Instead of specifying a fixed array of options using the 'options' element, you can assign a dynamically generated set of options using a 'options_callback' element with a callable type value. Example:
```
'options_callback' => ['appMyClass', 'myCallbackMethod'],
```
    An array of options must be generated by the method specified within a callable type value.
  - value: the value of a value attribute from the 'options' array corresponding to the radio element which must be selected by default.
  - control_separator: optional portion of HTML code to be added between each pair of radio elements.
  - custom_control_separator: HTML code to override the value of control_separator.
- waHtmlControl::SELECT
  - options: array of option elements data. Two modes of specifying the data array are supported:
    
    Mode 1: the key of each array item is the value of the value attribute of the corresponding option element, and its value is the text caption to be displayed in the select drop-down list; e.g.:
```
'options' => [
    1 => 'first',
    2 => 'second',
    3 => 'third',
],
```
    Array keys must be either integers or strings. Mixing up integer and string keys within one array may lead to unpredictable results.
    Mode 2: each array item is a sub-array with keys 'value' and 'title' containing the value of the value attribute and the text caption respectively; e.g.:
```
'options' => [
    [
        'value' => 1,
        'title' => 'first',
    ],
    [
        'value' => 2,
        'title' => 'second',
    ],
    [
        'value' => 3,
        'title' => 'third',
    ],
],
```
    Instead of specifying a fixed array of options using the 'options' element, you can assign a dynamically generated set of options using a 'options_callback' element with a callable type value. Example:
```
'options_callback' => ['appMyClass', 'myCallbackMethod'],
```
    An array of options must be generated by the method specified within a callable type value.
  - value: the value of a value attribute from the 'options' array corresponding to the option element which must be selected by default.
- waHtmlControl::TITLE
  - value: text to be added inside tag <h3>.
  - description: text to be added inside tag <h4> directly following tag <h3> as a sub-header.
  - class: value of class attribute.
  - style: value of style attribute.
- waHtmlControl::COLORPICKER
  - value: color value selected by default.
  - options: list of pre-defined buttons for quick color selection; array keys are color values, array item values are sub-arrays in the format 'current locale ID' => 'color name' (color names are available to users as title hints displayed on mouse hover).
- waHtmlControl::CUSTOM
  - callback: array of a the names of a PHP class and its public static method returning the HTML code of a custom element and accepting the following parameters:
    - $params: element’s individual parameters as an array, whose values you can use to generated the returned HTMl code.
    - $namespace: a namespace value specified for a particular element instance.
- waHtmlControl::TEXTAREA
  - value: contents of the textarea element.
  - class: value of class attribute.
  - style: value of style attribute.
  - cols: value of cols attribute.
  - rows: value of rows attribute.
  - wrap: value of wrap attribute.
  - placeholder: value of placeholder attribute.
  - readonly: flag requiring to add attribute readonly; defaults to false.
  - autofocus: flag requiring to add attribute autofocus; defaults to false.
  - wysiwyg: non-empty array of parameters for calling fromTextArea method of JavaScript library CodeMirror. When such an array is provided, which can also be replaced with a simple true value, a textarea element is transformed into a custom source code editing element with code highlighting feature. For this option to work, CSS and JavaScript files from directory wa-content/js/codemirror/ must be included on a page. When the wysiwyg parameter is specified, the values of parameters class, style, cols, rows, wrap, placeholder, readonly, autofocus are ignored.
- Optional parameters common for all control types
  - namespace: namespace value.
  - id: additional value to be added with an underscore character _ at the beginning of the automatically generated value of the id attribute.
  - description: value of 'description' parameter, usually displayed under a control.
  - control_wrapper: template of the HTML wrapper inside which a control's HTML code must be displayed; the template must contain 3 %s snippets, each corresponding, in the specified order, to 1) the value of 'title' parameter, 2) a control's HTML code, 3) the value of 'description' parameter.
  - title_wrapper: template of HTML wrapper for 'title' parameter; default value is %s: , i.e. text followed by a colon.
  - description_wrapper: template of HTML wrapper for value of 'description' parameter.
  - custom_title_wrapper: template to override the value of title_wrapper.
  - custom_description_wrapper: template to override the value of description_wrapper.
  - custom_control_wrapper: template to override the value of control_wrapper.

Example

$control_params = [
    'namespace'           => 'settings',
    'control_wrapper'     => '<div class="field"><div class="name">%s</div><div class="value">%s%s</div></div>',
    'title_wrapper'       => '%s',
    'description_wrapper' => '<br><span class="hint">%s</span>'
];

$controls = [
    waHtmlControl::getControl(waHtmlControl::CHECKBOX, 'setting1', [
        'checked' => true,
        'value'   => 1,
        'title'   => 'Checkbox',
        'description'   => 'Enable or disable it',
    ] + $control_params),

    waHtmlControl::getControl(waHtmlControl::CONTACTFIELD, 'setting2', [
        'title' => 'Contact field',
        'description'   => 'Select one from the list',
    ] + $control_params),

    waHtmlControl::getControl(waHtmlControl::FILE, 'setting3', [
        'title' => 'File',
        'description'   => 'Browse for a file on your computer',
    ] + $control_params),

    waHtmlControl::getControl(waHtmlControl::GROUPBOX, 'setting4', [
        'options' => [
            1 => 'first',
            2 => 'second',
            3 => 'third',
        ],
        'value' => [1, 3],
        'title' => 'Checkboxes',
        'description'   => 'Select any options',
    ] + $control_params),

    waHtmlControl::getControl(waHtmlControl::HIDDEN, 'setting5', [
        'value' => ifset($setting5),
    ]),

    waHtmlControl::getControl(waHtmlControl::INPUT, 'setting6', [
        'title'       => 'Text string',
        'placeholder' => 'enter short text',
    ] + $control_params),

    waHtmlControl::getControl(waHtmlControl::PASSWORD, 'setting7', [
        'title' => 'Password',
        'placeholder' => 'enter a password',
    ] + $control_params),

    waHtmlControl::getControl(waHtmlControl::RADIOGROUP, 'setting8', [
        'options' => [
            1 => 'first',
            2 => 'second',
            3 => 'third',
        ],
        'value' => 2,
        'title' => 'Radio buttons',
        'description'   => 'Select one of the options',
    ] + $control_params),

    waHtmlControl::getControl(waHtmlControl::SELECT, 'setting9', [
        'options' => [
            1 => 'first',
            2 => 'second',
            3 => 'third',
        ],
        'value' => 3,
        'title' => 'Drop-down list',
        'description'   => 'Select one of the items',
    ] + $control_params),

    waHtmlControl::getControl(waHtmlControl::TEXTAREA, 'setting10', [
        'value' => ifset($setting10),
        'title' => 'Multi-line field',
        'placeholder' => 'enter long text',
    ] + $control_params),
    waHtmlControl::getControl(waHtmlControl::COLORPICKER, 'setting11', [
        'value' => '#ff0000',
        'options' => [
            '#ff0000' => [
                'en_US' => 'red',
            ],
            '#00ff00' => [
                'en_US' => 'green',
            ],
        ],
    ] + $control_params),
];

public static function registerControl ($type, $callback)

Adds a custom control type to the list of available ones, which can be used with getControl method.

Parameters

$type
String value of a custom control type, written with the first letter in the upper case and the rest of the string written in the lower case.
$callback
A value which can be called as a function (see documentation for PHP function is_callable). Such a function, which is usually a static method of a PHP class, must accept the value of control's name attribute and an array of parameters for control generation similar to those described for default controls mentioned in the description of getControl method, and must return the custom control's HTML code.

Example

class someClass
{
    public function execute()
    {
        //...
        waHtmlControl::registerControl('Mycontrol', [__CLASS__, 'getControl']);
        wa()->getView()->assign('mycontrol', waHtmlControl::getControl('Mycontrol', $params));
        //...
    }

    public static function getControl($name, $params = [])
    {
        //...    implementation of a custom control
        return '...';   //return custom control's HTML code
    }
}