Add a new element to the Widget. Each element must be given at least a type. The name is used to generate an id attribute on the tag created for the element, and for form-specific elements is used as the name attribute. The returned element object can be used to set further attributes, please see the individual element classes for the methods specific to each one.

Create a dropdown or multi-select list element with multiple options. Options are supplied in a key => value list, in which the keys are the actual selected IDs, and the values are the strings displayed in the dropdown.

Set up a constraint on one or more elements. When process() is called on the Widget object, with a $query object, the parameters of the query are checked against the specified constraints. The HTML::Widget::Constraint object is returned to allow setting of further attributes to be set. The string 'Not_' can be prepended to each type name to negate the effects. Thus checking for a non-integer becomes 'Not_Integer'.

If the constraint package name starts with something other than HTML::Widget::Constraint::, you can fully qualify the name by using a unary plus:

Insert the contents of another widget object into this one. Each embedded object will be represented as another set of fields (surrounded by a fieldset tag), inside the created form. No copy is made of the widgets to embed, thus calling as_xml on the resulting object will change data in the widget objects.

With an element argument, the widgets are embedded into the provided element. No checks are made on whether the provided element belongs to $self.

Note that without an element argument, embed embeds into the top level of the widget, and NOT into any subcontainer (whether created by you or implicitly created). If this is not what you need, you can choose one of:

If you are just building a widget and do not need to import constraints and filters from another widget, do not use embed at all, simply assemble using the methods provided by HTML::Widget::Element::Fieldset.

Add a filter. Like constraints, filters can be applied to one or more elements. These are applied to actually change the contents of the fields, supplied by the user before checking the constraints. It only makes sense to apply filters to fields that can contain text - Password, Textfield, Textarea, Upload.

If the filter starts with a name other than HTML::Widget::Filter::, you can fully qualify the name by using a unary plus:

Merge elements, constraints and filters from other widgets, into this one. The elements will be added to the end of the list of elements that have been set already.

Without an element argument, and with standard widgets, the contents of the first top-level element of each widget will be merged into the first top-level element of this widget. This emulates the previous behaviour.

With an element argument, the widgets are merged into the named element. No checks are made on whether the provided element belongs to $self.

After finishing setting up the widget and all its elements, call to create an HTML::Widget::Result. If passed a $query it will run filters and validation on the parameters. The Result object can then be used to produce the HTML.