1. Qiq
  2. 2.x
  3. Helpers
  4. Form Helpers

2.9.3. Form Helpers

All helpers automatically apply appropriate escaping. This means you can use {{= ... }} to output them. If you use {{h ... }} et al., you will end up double-escaping the output.

You can also address the helpers as methods on $this in PHP template code.

Finally, many of these helpers accept a trailing variadic list of named parameters as HTML tag attributes. This means you can add just about any attribute as if it was a parameter on the helper method. Underscores in the parameter name will be converted to dashes; e.g., foo_bar: 'baz' will become foo-bar="baz" in the returned helper output. For attributes that cannot double as named parameters, use the attr array parameter.

2.9.3.1. Form Tag

Open a form like so:

{{= form (
    action: '/hello',
    attr: [],               // (array) optional key-value attributes
    id: 'form-id'           // (...mixed) optional named parameter attributes
) }}

<!-- defaults to method="post" action="" enctype="multipart/form-data" -->
<form method="post" action="/hello" enctype="multipart/form-data" id="form-id">

You can close a form just using </form>.

2.9.3.2. Input Tags

2.9.3.2.1. checkboxField

{{= checkboxField (
    name: 'flag',
    value: 'foo',
    checked: true,
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="checkbox" name="flag" value="foo" checked />

2.9.3.2.2. checkboxFields

The checkboxFields helper can be used for one or more checkboxes at a time, and has greater functionality than the checkboxField helper:

  • The options array specifies one or more checkboxes as part of the field, with each value when checked, and the corresponding label.

  • If the options have more than one element, then field name will be appended automatically with [] to make it an array.

  • The value attribute will be matched against the options and the correct checkboxes will be checked for you.

  • The default parameter, when non-null, will produce a hidden input field for the value when no checkboxes are checked.

{{= checkboxFields (
    name: 'flags',
    value: 'bar',
    default: '',
    options: [
        'foo' => 'Foo Flag',
        'bar' => 'Bar Flag',
        'baz' => 'Baz Flag',
    ],
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="hidden" name="flags" value="" />
<label><input type="checkbox" name="flags[]" value="foo" /> Foo Flag</label>
<label><input type="checkbox" name="flags[]" value="bar" checked /> Bar Flag</label>
<label><input type="checkbox" name="flags[]" value="baz" /> Baz Flag</label>

2.9.3.2.3. colorField

{{= colorField (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="color" name="foo" value="bar" />

2.9.3.2.4. dateField

{{= dateField (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="date" name="foo" value="bar" />

2.9.3.2.5. datetimeField

{{= datetimeField (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="datetime" name="foo" value="bar" />

2.9.3.2.6. datetimeLocalField

{{= datetimeLocalField (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="datetime-local" name="foo" value="bar" />

2.9.3.2.7. emailField

{{= emailField (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="email" name="foo" value="bar" />

2.9.3.2.8. fileField

{{= fileField (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="file" name="foo" value="bar" />

2.9.3.2.9. hiddenField

{{= hiddenField (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="hidden" name="foo" value="bar" />

2.9.3.2.10. inputField

A generic input field; specify the type needed.

{{= inputField (
    type: 'text',
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="text" name="foo" value="bar" />

2.9.3.2.11. monthField

{{= monthField (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="month" name="foo" value="bar" />

2.9.3.2.12. numberField

{{= numberField (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="number" name="foo" value="bar" />

2.9.3.2.13. passwordField

{{= passwordField (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="password" name="foo" value="bar" />

2.9.3.2.14. radioField

{{= radioField (
    name: 'foo',
    value: 'baz',
    checked: true,
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="radio" name="foo" value="baz" checked />

2.9.3.2.15. radioFields

The radioFields helper has greater functionality than the radioField helper:

  • The options parameter specfies one or more radio buttons as part of the field, with their value when checked, and their corresponding label.

  • The value parameter will be matched against the options and the correct radio button will be checked for you.

{{= radioFields (
    name: 'foo',
    value: 'baz',
    options: [
        'bar' => 'Bar Label',
        'baz' => 'Baz Label,
        'dib' => 'Dib Label',
    ),
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<label><input type="radio" name="foo" value="bar" /> Bar Label</label>
<label><input type="radio" name="foo" value="baz" checked /> Baz Label</label>
<label><input type="radio" name="foo" value="dib" /> Dib Label</label>

2.9.3.2.16. rangeField

{{= rangeField (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="range" name="foo" value="bar" />

2.9.3.2.17. searchField

{{= searchField (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="search" name="foo" value="bar" />

2.9.3.2.18. select

Use the options parameter to describe the <option> tags.

The placeholder parameter is honored as a placeholder label when no option is selected. The default parameter, when non-null, specifies the value of that placeholder.

Use multiple: true to set up a multiple select; this will automatically add [] to the name if it is not already there.

{{= select (
    name: 'foo',
    value: 'dib',
    placeholder: 'Please pick one',
    default: '',
    options: [
        'bar' => 'Bar Label',
        'baz' => 'Baz Label',
        'dib' => 'Dib Label',
        'zim' => 'Zim Label',
    ],
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<select name="foo">
    <option value="" disabled>Please pick one</option>
    <option value="bar">Bar Label</option>
    <option value="baz">Baz Label</option>
    <option value="dib" selected>Dib Label</option>
    <option value="zim">Zim Label</option>
</select>

The helper also supports option groups. If an options array value is itself an array, the key for that element will be used as an <optgroup> label and the array of values will be options under that group.

{{= select (
    name: 'foo',
    value: 'bar',
    options: => [
        'Group A' => [
            'bar' => 'Bar Label',
            'baz' => 'Baz Label',
        ],
        'Group B' => [
            'dib' => 'Dib Label',
            'zim' => 'Zim Label',
        ],
    ],
) }}

<select name="foo">
    <optgroup label="Group A">
        <option value="bar">Bar Label</option>
        <option value="baz">Baz Label</option>
    </optgroup>
    <optgroup label="Group B">
        <option value="dib" selected>Dib Label</option>
        <option value="zim">Zim Label</option>
    </optgroup>
</select>

2.9.3.2.19. telField

{{= telField(
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="tel" name="foo" value="bar" />

2.9.3.2.20. textField

{{= textField (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="text" name="foo" value="bar" />

2.9.3.2.21. textarea

{{= textarea (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<textarea name="foo">bar</textarea>

2.9.3.2.22. timeField

{{= timeField (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="time" name="foo" value="bar" />

2.9.3.2.23. urlField

{{= urlField (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="url" name="foo" value="bar" />

2.9.3.2.24. weekField

{{= weekField (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="week" name="foo" value="bar" />

2.9.3.3. Button Tags

Helpers for various button tags.

2.9.3.3.1. button

{{= button (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="button" name="foo" value="bar" />

2.9.3.3.2. imageButton

{{= imageButton (
    name: 'foo',
    src: '/images/map.png',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="image" name="foo" src="/images/map.png" />

2.9.3.3.3. submitButton

{{= submitButton (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="submit" name="foo" value="bar" />

2.9.3.3.4. resetButton

{{= resetButton (
    name: 'foo',
    value: 'bar',
    attr: [],               // (array) optional key-value attributes
    ...                     // (...mixed) optional named parameter attributes
) }}

<input type="reset" name="foo" value="bar" />

2.9.3.4. Label Tag

A helper for <label> tags.

{{= label (
    'Label For Field',      // (string) label text
    attr: [],               // (array) optional key-value attributes
    for: 'field'            // (...mixed) optional named parameter attributes
) }}

<label for="field">Label For Field</label>