API helpers

Utilities for helping developers use python for adding various attributes, elements, and UI elements to forms generated via the uni_form template tag.

class helpers.BaseInput(name, value, **kwargs)[source]

A base class to reduce the amount of code in the Input classes.

render(form, form_style, context)

Renders an <input /> if container is used as a Layout object

class helpers.Button(name, value, **kwargs)[source]

Used to create a Submit input descriptor for the uni_form template tag:

button = Button('Button 1', 'Press Me!')

Note

The first argument is also slugified and turned into the id for the button.

class helpers.ButtonHolder(*fields, **kwargs)

Layout object. It wraps fields in a <div class=”buttonHolder”>

This is where you should put Layout objects that render to form buttons like Submit. It should only hold HTML and BaseInput inherited objects.

Example:

ButtonHolder(
    HTML(<span style="display: hidden;">Information Saved</span>),
    Submit('Save', 'Save')
)
class helpers.Column(*fields, **kwargs)[source]

Layout object. It wraps fields in a div whose default class is “formColumn”.

Example:

Column('form_field_1', 'form_field_2') 
class helpers.Fieldset(legend, *fields, **kwargs)[source]

Layout object. It wraps fields in a <fieldset>

Example:

Fieldset("Text for the legend",
    'form_field_1',
    'form_field_2'
)

The first parameter is the text for the fieldset legend. This text is context aware, so you can do things like:

Fieldset("Data for {{ user.username }}",
    'form_field_1',
    'form_field_2'
)
class helpers.FormHelper[source]

This class controls the form rendering behavior of the form passed to the {% uni_form %} tag. For doing so you will need to set its attributes and pass the corresponding helper object to the tag:

{% uni_form form form.helper %}

Let’s see what attributes you can set and what form behaviors they apply to:

form_method: Specifies form method attribute.
You can see it to ‘POST’ or ‘GET’. Defaults to ‘POST’
form_action: Applied to the form action attribute:
  • Can be a named url in your URLconf that can be executed via the {% url %} template tag. Example: ‘show_my_profile’. In your URLconf you could have something like:

    url(r'^show/profile/$', 'show_my_profile_view', name = 'show_my_profile')
    
  • It can simply point to a URL ‘/whatever/blabla/’.

form_id: Generates a form id for dom identification.
If no id provided then no id attribute is created on the form.
form_class: String containing separated CSS clases to be applied
to form class attribute. The form will always have by default ‘uniForm’ class.
form_tag: It specifies if <form></form> tags should be rendered when using a Layout.
If set to False it renders the form without the <form></form> tags. Defaults to True.
form_error_title: If a form has non_field_errors to display, they
are rendered in a div. You can set title’s div with this attribute. Example: “Oooops!” or “Form Errors”
formset_error_title: If a formset has non_form_errors to display, they
are rendered in a div. You can set title’s div with this attribute.
form_style: Uni-form has two built in different form styles. You can choose
your favorite. This can be set to “default” or “inline”. Defaults to “default”.

Public Methods:

add_input(input): You can add input buttons using this method. Inputs
added using this method will be rendered at the end of the form/formset.
add_layout(layout): You can add a Layout object to FormHelper. The Layout
specifies in a simple, clean and DRY way how the form fields should be rendered. You can wrap fields, order them, customize pretty much anything in the form.

Best way to add a helper to a form is adding a property named helper to the form that returns customized FormHelper object:

from uni_form import helpers

class MyForm(forms.Form):
    title = forms.CharField(_("Title"))

    @property
    def helper(self):
        helper = helpers.FormHelper()
        helper.form_id = 'this-form-rocks'
        helper.form_class = 'search'
        submit = helpers.Submit('submit','Submit')
        helper.add_input(submit)
        [...]
        return helper

You can use it in a template doing:

{% load uni_form_tags %}
<html>
    <body>
        <div id="where-I-want-the-generated-form">
            {% uni_form form form.helper %}
        </div>
    </body>            
</html>
get_attributes()[source]

Used by the uni_form_tags to get helper attributes

render_layout(form, context)[source]

Returns safe html of the rendering of the layout

exception helpers.FormHelpersException[source]

This is raised when building a form via helpers throws an error. We want to catch form helper errors as soon as possible because debugging templatetags is never fun.

class helpers.HTML(html)[source]

Layout object. It can contain pure HTML and it has access to the whole context of the page where the form is being rendered.

Examples:

HTML("{% if saved %}Data saved{% endif %}")
HTML('<input type="hidden" name="{{ step_field }}" value="{{ step0 }}" />')
class helpers.Hidden(name, value, **kwargs)[source]

Used to create a Hidden input descriptor for the uni_form template tag.

class helpers.Layout(*fields)[source]

Form Layout. It is conformed by Layout objects: Fieldset, Row, Column, MultiField, HTML, ButtonHolder, Button, Hidden, Reset, Submit and fields. Form fields have to be strings.

Layout objects Fieldset, Row, Column, MultiField and ButtonHolder can hold other Layout objects within. Though ButtonHolder should only hold HTML and BaseInput inherited classes: Button, Hidden, Reset and Submit.

You need to add your Layout to the FormHelper using its method add_layout.

Example:

layout = Layout(
    Fieldset('Company data', 
        'is_company'
    ),
    Fieldset(_('Contact details'),
        'email',
        Row('password1', 'password2'),
        'first_name',
        'last_name',
        HTML('<img src="/media/somepicture.jpg"/>'),
        'company'
    ),
    ButtonHolder(
        Submit('Save', 'Save', css_class='button white'),
    ),
)

helper.add_layout(layout)
class helpers.MultiField(label, *fields, **kwargs)[source]

multiField container. Renders to a multiField <div>

class helpers.Reset(name, value, **kwargs)[source]

Used to create a Hidden input descriptor for the uni_form template tag:

reset = Reset('Reset This Form', 'Revert Me!')

Note

The first argument is also slugified and turned into the id for the reset.

class helpers.Row(*fields, **kwargs)[source]

Layout object. It wraps fields in a div whose default class is “formRow”.

Example:

Row('form_field_1', 'form_field_2', 'form_field_3')
class helpers.Submit(name, value, **kwargs)[source]

Used to create a Submit button descriptor for the uni_form template tag:

submit = Submit('Search the Site', 'search this site')

Note

The first argument is also slugified and turned into the id for the submit button.

helpers.render_field(field, form, form_style, context, template='uni_form/field.html', labelclass=None)[source]

Renders a field, if the field is a django-uni-form object like a Row or a Fieldset, calls its render method. The field is added to a list that the form holds called rendered_fields to avoid double rendering fields. If the field is a form field a BoundField is instantiated, rendered and its html returned.

Previous topic

Customization

Next topic

API templatetags

This Page