Rendering forms and fields
==========================

Most of the time you'll be using morf to display, validate and process web
forms.

The class :class:`~morf.htmlform.HTMLForm` provides shortcuts for this.
Most of the time it's convenient to create forms by subclassing this.

Basic rendering
---------------

Forms, by default, do not know anything about HTML. For that you need a
:class:`morf.render.FormRenderer` object. There are various flavours of
FormRenderer that render in different HTML markup styles. The easiest way to get
hold of a :class:`~morf.render.FormRenderer` object
is to use one of the ``.as_*``
methods on :class:`~morf.htmlform.HTMLForm`:

.. testcode ::

    from morf import HTMLForm, fields

    class MyForm(HTMLForm):

        email = fields.Str()
        name = fields.Str()

    form = MyForm()
    print(form.as_p())

Which outputs the rendered HTML:

.. testoutput ::

    <p><label for="field_email-0">Email</label><div class="control"><input id="field_email-0" name="email" required="" type="text" value="" /></div></p>...




Customizing rendering templates
-------------------------------

You can customize the HTML generated by calling
:meth:`~morf.htmlform.HTMLForm.renderer`:

.. testcode::

    from markupsafe import Markup
    renderer = form.renderer(
        form_template='<ul class="custom-form">{{ fields|join() }}</ul>',
        row_template='<li class="custom-form-row">{{ field }}</li>',
        field_template='<span>{{ label }}: {{ control }}</span>{{ errors }}',
        errors_template=
                '<div class="oops-errors">'
                '{% for message in errors %}{{ message|e }}{% endfor %}'
                '</div>',
        label_template='<label for="{{ id }}">{{ label|e }}</label>')

    print(renderer)

Which will output the HTML:

.. testoutput::

    <ul class="custom-form"><li class="custom-form-row"><span><label...

The various '_template' arguments are Jinja2 templates,
and you can use all of the templating features of Jinja2
to customize the output.
For example, if you wanted to add
a Django forms style ``help_text`` attribute::

    email = fields.Str(
                help_text='We will send a confirmation email to this address')

    renderer = form.as_p(field_template=
            '<span>{{ label }}: {{ control }}</span>{{ errors }}'
            '{% if 'help_text' in field.options %}
            '{{ field.options.help_text|e }}'
            '{% endif %}')


For more examples, take a few minutes to look at the source code of
:class:`morf.htmlform.HTMLForm` and :class:`morf.render.RenderOptions`.

Rendering individual fields
---------------------------

:class:`~morf.render.FormRenderer` objects know which fields have already been
rendered and which have not.

This lets you tailor rendering for selected fields
while leaving morf to do the grunt work on the remaining fields.
For example, here's some sample form rendering code in a Jinja2 template::

    <div class="column">
        {{ form.pop('username').render(class_='MyCustomCSSClass') }}
        {% for field in form.select(['email', 'password', 'password_confirm') %}
            {{ field }}
        {% endfor %}
    </div>

    <div class="column">
        {% for field in form %}
            {{ field }}
        {% endfor %}
    </div>

This template renders the form in two separate ``<div>`` elements.
The second ``<div>`` element will only contain fields not previously rendered
in the first ``<div>`` element. Methods such as
:meth:`morf.render.FormRenderer.pop`,
:meth:`morf.render.FormRenderer.select`,
:meth:`morf.render.FormRenderer.select_to`,
:meth:`morf.render.FormRenderer.select_match`
and :meth:`morf.render.FormRenderer.select_except`
give you a lot of flexibility to slice and dice the layout of fields
within the form, without having to hand code everything.

.. automodule:: morf.htmlform
    :members:

.. automodule:: morf.render
    :members: