Widgets¶

A widget is Powerform’s representation of an HTML input element. The widget handles the rendering of the HTML, and the extraction of data from a GET/POST dictionary that corresponds to the widget.

The HTML generated by the built-in widgets uses HTML5 syntax, targeting <!DOCTYPE html>. For example, it uses boolean attributes such as checked rather than the XHTML style of checked=’checked’.

Note

Widgets should not be confused with the form fields. Form fields deal with the logic of input validation and are used directly in templates. Widgets deal with rendering of HTML form input elements on the web page and extraction of raw submitted data. However, widgets do need to be assigned to form fields.

Specifying widgets
Built-in widgets
- Widgets handling input of text
- Selector and checkbox widgets

Specifying widgets ¶

Whenever you specify a field on a form, Powerform will use a default widget that is appropriate to the type of data that is to be displayed. To find which widget is used on which field, see the documentation about Built-in Field classes.

However, if you want to use a different widget for a field, you can just use the widget argument on the field definition. For example:

namespace App\Forms;


use Eddmash\PowerOrm\Form\Form;

class CommentForm extends Form
{
    /**
     * @inheritDoc
     */
    public function fields()
    {
        return [
            'name'=>Form::CharField(),
            'url'=>Form::UrlField(),
            'comment'=>Form::CharField(['widget'=>Form::TextArea()])
        ];
    }

}

This would specify a form with a comment that uses a larger Textarea widget, rather than the default TextInput widget.

Built-in widgets ¶

Powerform provides a representation of all the basic HTML widgets, plus some commonly used groups of widgets in the EddmashPowerOrmFormWidgets module, including the input of text, various checkboxes and selectors, uploading files, and handling of multi-valued input.

Widgets handling input of text ¶

These widgets make use of the HTML elements input and textarea.

TextInput¶

Text input: <input type=”text” …>

NumberInput¶

Text input: <input type=”number” …>

Beware that not all browsers support entering localized numbers in number input types.

EmailInput¶

Text input: <input type=”email” …>

URLInput¶

Text input: <input type=”url” …>

PasswordInput¶

Password input: <input type=’password’ …>

HiddenInput¶

Hidden input: <input type=’hidden’ …>

Note that there also is a MultipleHiddenInput widget that encapsulates a set of hidden input elements.

DateInput¶

Date input as a simple text box: <input type=’text’ …>

Takes same arguments as TextInput, with one more optional argument:

format

The format in which this field’s initial value will be displayed.

If no format argument is provided, the default format is the first format found in DATE_INPUT_FORMATS.

Textarea¶

Text area: <textarea>…</textarea>

Selector and checkbox widgets ¶

CheckboxInput¶

Checkbox: <input type=’checkbox’ …>

Takes one optional argument:

check_test

A callable that takes the value of the CheckboxInput and returns True if the checkbox should be checked for that value.

Select¶

Select widget: <select><option …>…</select>

choices

This attribute is optional when the form field does not have a choices attribute. If it does, it will override anything you set here when the attribute is updated on the Field.

NullBooleanSelect¶

Select widget with options ‘Unknown’, ‘Yes’ and ‘No’

SelectMultiple¶

Similar to select, but allows multiple selection: <select multiple=’multiple’>…</select>

RadioSelect¶

Similar to select, but rendered as a list of radio buttons within <li> tags:

<ul>
  <li><input type='radio' name='...'></li>
  ...
</ul>

CheckboxSelectMultiple¶

Similar to SelectMultiple, but rendered as a list of check buttons:

<ul>
  <li><input type='checkbox' name='...' ></li>
  ...
</ul>