YAFOWIL is based on a set of core ideas:
If you work with YAFOWIL for the first time, it probably feels a bit different compared to other multiple-class-inheriting, schema-based forms.
Instead YAFOWIL uses simple callables at several places. You never need to
inherit any class from yafowil.* (and if you think you need to you don’t
understand its architecture and should ask us to improve this documentation).
Callables are used for every extensible aspect of YAFOWIL. They are bundled as blueprints and used via the factory.
Explanation: Callables are simple functions or instances of a class with a
__call__ method.
A YAFOWIL form consists of a tree of widgets. Everything you would probably call a “Field” in other form libraries is a widget instance. Widgets can have children. Thus, fieldsets and even the form root itself are also widgets.
The behavior of a widget is defined by a series of blueprints and properties as shown below in the referring sections.
The widget class is generic! It’s never instantiated directly. The factory is the only place where this happens.
At creation time of widgets you need to use its dict-like API for creating compounds of widgets, such as a form or a fieldset.
Attention! Possible confusion::
While one request-to-response cycle runs, widgets state is kept in a runtime-data instance. It collects all information such as values, request, any errors that occurred, and the rendered HTML of a widget in the context of the current request.
The controller is responsible for form processing (extraction and validation), delegation of actions and form rendering (including error handling).
The controller is initialized with a form and request object and immediately
starts the processing. The rendered instance attribute contains the
rendered form, while the data attribute contains the extracted runtime-data
tree.
Unlike most form frameworks, YAFOWIL does not make a distinction between
extraction of a value from the HTTP-request and validation. Both happen in one
processing step. If an extraction step fails, it raises a
yafowil.base.ExtractionError. This special Python Exception carries a
human-readable message and specifies whether this error shall abort the extraction
chain or not. In either case the form has errors.
The factory knows of the available blueprints and is responsible to construct and configure widget instances. To construct a widget the factory gets called with the blueprint name as first parameter:
from yafowil.base import factory
widget = factory('text', ...)
The behavior of the callbacks in the different execution chains of the
blueprint can be configured with the props dict. See the blueprints reference
for a full list of accepted properties:
widget = factory('text', props={
'disabled': 'disabled',
})
For the root widget (most probably the form itself), the name attribute must be given to the factory:
form = factory('form', name='example_form', props={
'action': 'http://www.example.com/process_form',
})
Child widget names are set automatically using the child key:
form['field_1'] = factory('text')
Usually we have some common widgets, e.g. a pure textarea, and then we need
some label, description, a way to display errors, maybe a table cell or an
encapsulating div and so on. And it can be very different depending on the
framework used or the design we need to implement. But the core functionality
is always the same. In other words: The input field and its behavior is stable,
the eye-candy around it is not.
To solve the different needs, YAFOWIL supports chaining blueprints at factory
time, the so called factory chain.
The blueprint chain is used by passing a colon-separated list of blueprint names
as a string to the factory as first argument. I.e. to provide a text field inside a
wrapper div with label, help-text and error message if extraction failed, call
the factory like so:
form['field_1'] = factory('field:label:error:text', props={
'label': 'Field 1',
'help': 'Helptext for field 1',
'required': 'Field 1 must not be empty',
})
This causes the callable chains of each blueprint to be executed in order. Extractors are executed from right to left while all others are executed left to right.
Now we may come up with the problem that several properties refer to more than one callable inside the execution chains. To address a property specific to a blueprint of the widget, you can prefix it with the blueprint name.
E.g., label.class addresses the class property of the label blueprint
only instead of affecting all blueprints:
form['field_1'] = factory('field:label:error:text', props={
'label': 'Field 1',
'label.class': 'label_css_class'
'help': 'Helptext for field 1',
'required': 'Field 1 must not be empty',
})
For the lazy people, macros are provided. Macros expand to a factory chain of blueprints. Expansion happens at chain-lookup time before the widget is built.
Macros must be registered in the factory and can override property defaults:
factory.register_macro('errorfield', 'field:label:error', 'props': {
'field.class': 'field',
'field.error_class': 'error',
'error.class': 'fieldErrorBox',
'error.render_empty': True,
'error.position': 'before',
})
Now the errorfield macro can be used inside the factory chain by using the
name prefixed with #:
textfield = factory('#errorfield:text')
For usecases where it’s not worth writing a generic widget, it’s possible to inject custom blueprints.
Custom blueprints are passed to the factory either as 5-tuple containing chains
of extractors, edit renderers, preprocessors, builders and display renderers,
or as dictionary containing the chains under the keys extractors,
edit_renderers, preprocessors, builders and display_renderers.
Please read the section about blueprints below to get a deeper understanding of
what happens.
Each chain contains callables as explained above. To tell the factory about usage of a custom blueprint, use the asterisk-prefix in the factory chain, as follows:
``field:label:*mycustom:textarea``
When using custom blueprints, the factory expects the custom
keyword argument, which is a dict with custom blueprint names as keys
(mycustom in our example), and the custom blueprint configuration as
explained above.
Create custom callbacks:
def special_renderer(widget, data):
return u'<SPECIAL>%s</SPECIAL>' % data.rendered
def special_extractor(widget, data):
return data.extracted + ['extracted special']
Inject as dict:
widget = factory('outer:*special:inner', custom={
'special': {
'extractors': [special_extractor],
'edit_renderers': [special_renderer],
},
})
Inject as list:
widget = factory('outer:*special:inner', custom={
'special': ([special_extractor], [special_renderer], [], [], []),
})
Custom blueprints are great for easily injecting validation extractors.
Blueprints are construction guides providing different behaviors on a widget: e.g. rendering an HTML input field, or extracting and validating input data or converting data received from the request.
These behaviors are organized as chains of callables. The behavior of the callables themselves is controlled by properties. Each chain has different responsibilities. Chains are executed left-to-right.
Extractors are responsible to get, convert and validate the data of the current widget in the context of the current request. An extractor is a callable expecting a widget instance and a runtime-data instance as parameters.
User story
An integer field consists of
ExtractionError is raised. Otherwise the
converted value is returned.ExtractionError is raised, otherwise
the value is returned unmodified.Edit renderers are responsible to create HTML form output (unicode-strings) ready to be passed to the response. It is a callable expecting a widget instance and a runtime-data instance as parameters. At this point the runtime-data instance has already passed the extraction chain and contains information about extracted values and errors. Edit renderers may utilize any templating language if desired. YAFOWIL has no preferences nor does it support any specific templating language out of the box. All internal rendering in YAFOWIL happens in pure Python.
The edit renderer chain is executed if the mode of the widget is edit.
User story
An file input field has to be rendered with checkboxes to indicate whether the file should be deleted.
The file input itself is a renderer, and the checkboxes are another renderer.
<input ..> tag for
the file upload.<checkbox ..> tags can be prepended, wrapped around or appended to
the previously rendered <input ..>.Both renderers are reusable and may be used in other contexts, e.g. in an image blueprint context.
Display renderers are responsible to create HTML view output (unicode-strings) ready to be passed to the response.
The display renderer chain is executed if the mode of the widget is display.
Like edit renderers it is a callable expecting widget and runtime-data as
parameters. Like the edit renderer it is executed after extraction.
It is possible to mix edit and display renderers in one widget tree. Each widget can have its own mode.
User story
A form is created for a complex dataset where different groups of users have different access permissions whether to edit or view a dataset value, or even to see it at all. The mode property of the widget controls which rendering chain, if any, gets executed.
The preprocessor chain is executed once per request-to-response cycle, directly after runtime-data was created and before extraction happens. A preprocessor callable can be used to hook up framework-specific requirements, and gets widget and runtime-data as parameters. There are global preprocessors running on every widget and widget-specific pre-processors. Widget-specific pre-processors are executed after the global preprocessors.
User story
YAFOWIL expects the request to be a dict-like object providing parameters
via get and __getitem__. Further i18n support should be available
e.g. via zope.i18n. A framework integration package now provides one
global preprocessor function wrapping the request if needed, and another
hooking up the i18n message factory and the translate function.
This chain of callables is called only once right after the widget was created by the factory. A common use-case is to automatically populate a widget with child widgets. It expects widget and factory as parameters.