formish.forms¶
The form module contains the main form, field, group and sequence classes
- class formish.forms.Form(structure, name=None, defaults=None, errors=None, action_url=None, renderer=None, method='POST')¶
Bases: object
The definition of a form
The Form type is the container for all the information a form needs to render and validate data.
Create a new form instance
Parameters: - structure (schemaish.Structure) – Schema Structure attribute to bind to the the form
- name (str “valid html id”) – Optional form name used to identify multiple forms on the same page
- defaults (dict) – Default values for the form
- errors (dict) – Errors to store on the form for redisplay
- action_url (string “url or path”) – Use if you don’t want the form to post to itself
- renderer (callable) – Something that returns a form serialization when called
- method (string) – Option method, default POST
- action(request, *args)¶
Find and call the action callback for the action found in the request
Parameters: - request (webob.Request) – request which is used to find the action and also passed through to the callback
- args – list of arguments Pass through to the callback
- actions()¶
- Return just the actions part of the template
- add_action(callback, name='submit', label=None)¶
Add an action callable to the form
Parameters: - callback (callable) – A function to call if this action is triggered
- name (string) – The identifier for this action
- label (string) – Use this label instead of the form.name for the value of the action (for buttons, the value is used as the text on the button)
- defaults¶
- Get the raw default data
- element_name¶
- Set the element name
- fields¶
- Return a generator that yields all of the fields at the top level of the form (e.g. if a field is a subsection or sequence, it will be up to the application to iterate that field’s fields.
- Return just the footer part of the template
- get_field(name)¶
Get a field by dotted field name
Parameter: name – Dotted name e.g. names.0.firstname
- get_item_data(key, name, default=<object object at 0x40205908>)¶
- Access item data associates with a field key and an attribute name (e.g. title, widget, description’)
- get_item_data_values(name=None)¶
- get all of the item data values
- get_unvalidated_data(request_data, raise_exceptions=True)¶
Convert the request object into a nested dict in the correct structure of the schema but without applying the schema’s validation.
Parameters: - request_data – Webob style request data
- raise_exceptions – Whether to raise exceptions or return errors
- header()¶
- Return just the header part of the template
- metadata()¶
- Return just the metada part of the template
- name¶
- Get the name of the form, default to formish
- request_data¶
- Retrieve previously set request_data or return the defaults in request_data format.
- set_item_data(key, name, value)¶
- Allow the setting os certain attributes on item_data, a dictionary used to associates data with fields.
- validate(request, failure_callable=None, success_callable=None)¶
Validate the form data in the request.
By default, this method returns either a dict of data or raises an exception if validation fails. However, if either success_callable or failure_callable are provided then the approriate callback will be called, and the callback’s result will be returned instead.
Parameters: - request (webob.Request) – the HTTP request
- failure_callable – Optional callback to call on failure.
- success_callable – Optional callback to call on success.
Returns: Python dict of converted and validated data.
Raises: formish.FormError, raised on validation failure.
- class formish.forms.Action(callback, name, label)¶
Bases: object
An action that that can added to a form.
Parameters: - callback – A callable with the signature (request, form, *args)
- name – an valid html id used to lookup an action
- label – The ‘value’ of the submit button and hence the text that people see
- class formish.forms.Field(name, attr, form)¶
Bases: object
A wrapper for a schema field type that includes form information.
The Schema Type Atribute does not have any bindings to the form library, it can be used on it’s own. We bind the Schema Attribute to a Field in order to include form related information.
Method __call__: returns a serialisation for this field using the form’s renderer - read only
Parameters: - name – Name for the field
- attr (schemaish.attr.*) – Schema attr to bind to the field
- form (formish.Form instance.) – The form the field belongs to.
- classes¶
- Works out a list of classes that should be applied to the field
- cssname¶
- cssname identifier for the field
- defaults¶
- Get the defaults from the form.
- description¶
- The Field schema’s description
- error¶
- Lazily get the error from the form.errors when needed
- errors¶
- Lazily get the error from the form.errors when needed
- inputs()¶
- returns the templated widget
- label()¶
- returns the templated title
- required¶
- Does this field have a Not Empty validator of some sort
- title¶
- The Field schema’s title
- value¶
- Convert the request_data to a value object for the form or None.
- widget¶
- return the fields widget bound with extra params.
- class formish.forms.Group(name, attr, form)¶
Bases: formish.forms.Collection
A group is a basic collection with a different template
Parameters: - name – Name for the Collection
- attr (schemaish.attr.*) – Schema attr to bind to the field
- form (formish.Form instance.) – The form the field belongs to.
- class formish.forms.Sequence(name, attr, form)¶
Bases: formish.forms.Collection
A sequence is a collection with a variable number of fields depending on request data, data or min/max values
Parameters: - name – Name for the Collection
- attr (schemaish.attr.*) – Schema attr to bind to the field
- form (formish.Form instance.) – The form the field belongs to.
- collection_fields()¶
- For sequences we check to see if the name is numeric. As names cannot be numeric normally, the first iteration loops on a fields values and spits out a
- template¶