.. _simple-tutorial: ========================================= Creating, Validating And Rendering A Form ========================================= This tutorials shows how to use Formular in a web application. Creating A Form --------------- A simple form for a login looks like this:: class LoginForm(HTMLForm): username = TextField(label=u"Username", required=True) password = PasswordField(label=u"Password", required=True) repeat_password = password.copy(label=u"Repeat Password", equals="password") As you can see one way of creating a form is doing it declarativly, another way is assigning a field to a :class:`formular.forms.Form` class or an instance of such a class. Fields from superclasses are inherited. Every field gets a label, which is shown to the user of the renderd form. Validators are passed as keyword arguments, a list of built-in validators can be found :ref:`here `, you can create your own using :meth:`formular.fields.Field.register_as_validator`. Now once you created such a form you can use it to validate data. Validating A Form ----------------- In most frameworks you have some kind of function or method which get's a request object, values from the route and returns a context, a template or even the response. This is an example of a simple view:: def login(request): # Passing the session and the action makes sure that the form is # protected against cross-site request forgery attacks. form = LoginForm(session=request.session, action=request.path) if form.validate(request.form): # The validated values are stored in the .value attribute of each # field. You can also access the form.data dictionary and use the # field name to get the value like ``form.data["username"]``. user = User.query.filter_by(name=form.username.value).first() if user.has_password(form.password.value): request.login(form.username.value) # For this example we just return a dictionary as the context for the # template. return {"form": form.as_widget()} ``request.form`` is just a dictionary. If you pass ``without_csrf_protection=True`` to :class:`formular.forms.HTMLForm.validate` you can even use it to validate other formats like JSON. .. seealso:: :ref:`frameworks` Rendering A Form ---------------- To render a form, Formular uses widgets. A widget represents a field or a form, such a widget can be rendered into one or more different HTML Elements. Earlier we passed the widget of the form to the context. So to render it we just do ``form.render()`` in the template and we get a nice definition list of labels and fields. The errors which occured during validation can be nicely displayed using ``form.errors.render()`` in the template. Although you probably want to use CSS to change the look of it. A simple jinja template would therefore look like this: .. code-block:: html+jinja Formular - Example

Login

{{ form.errors.render() }} {{ form.render() }} .. seealso:: :ref:`The widget API documentation `.