Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/smileychris/django-forms

A Django template-based form api.
https://github.com/smileychris/django-forms

Last synced: about 1 year ago
JSON representation

A Django template-based form api.

Awesome Lists containing this project

README 

          
============

Django Forms

============



A designer-focused forms control library which works as a layer over the

standard Django forms API.



Tags

====



.. _form-tag:



``{% form %}``

--------------



Render one or more forms. A basic example of rendering a standard form using

HTML paragraphs for rows would be

``{% form some_form using "forms/p.html" %}``.



Usage::



    {% form some_form [form2 form3 ...] %}



Any of the standard `tag arguments`_ can be used.



Context:



    ``forms``

        List of forms to render.



    ``errors``

        Set to ``True`` if any of the forms contain errors.



    ``non_field_errors``

        List of non-field errors.



.. _row-tag:



``{% row %}``

-------------



Used to render a row template with one or more fields with the currently

defined template.



Usage is either::



    * ``{% row field_list %}``

    * ``{% row some_form.field [some_form.field ...] %}``



Any of the standard `tag arguments`_ can be used.



Context:



    ``fields``

        List of fields to render.



    ``errors``

        List of errors relating to any of the fields in this row.



    ``required``

        The number of fields that are required.



.. _field-tag



``{% field %}``

---------------



Used to render a specific field with the currently defined field template.



Usage::



    {% field some_field %}



Requires a context variable named ``form`` to exist (and be a

`django.forms.forms.BaseForm`` instance).



Any of the standard `tag arguments`_ can be used.



Context:



    ``value``

        The value of this field.



    ``errors``

        A list of errors relating to this field.



    ``label``

        The label text for this field.

    

    ``help_text``

        The help text for this field.



    ``form``

        The form this field belongs to.

    

    ``field``

        The underlying form field being rendered.

        

    ``id``

        The id for this field (or an empty string).



    ``id_for_label``

        The id which should be assigned to the field's label



    ``name``

        The name of this field.



    ``html_name``

        The prefixed name of this field



.. _formconfig-tag



``{% formconfig %}``

--------------------



Used to configure rows and fields, as specified by the first tag argument.

Reuse of this tag overrides previously defined matching configurations.



Usage, either::



    * ``{% formconfig row ... %}``, or

    * ``{% formconfig field ... %}``



    Any of the standard `tag arguments`_ can be used.



To limit the configuration of rows for one or more specific fields, use the

``for`` argument. For example::



    {% formconfig row for form.first_name form.last_name using "forms/rows/pretty.html" %}



The ``for`` argument also accepts strings::



    {% formconfig field for "email" with help_text="Your email address" %}



Use the ``priority`` argument to `change the default order of form fields`_.

This can only be used if the configuration is limited to specific fields. For

example::



    {% formconfig field for form.first_name priority 1 %}

    {% formconfig field for form.last_name priority 2 %}



Tag Arguments

=============



These arguments can be used on any form-related tag.



Add to the context (``with``)

-----------------------------



`` with key=value [key=value key=value ...]``



Adds to the context of the template which will be rendered.



Exclude the current context (``only``)

--------------------------------------



If this argument is part of the tag, the current context will not be available

to the template that will be rendered.



.. note::



    There is one exception: any context variable named ``form`` will still be

    available (also any variable starting with ``_formconfig``, but they aren't

    available from templates anyway).



Choose the template (``using`` or ``extends``)

----------------------------------------------



There are two arguments that allow configuration of which template should be

used to render the template:



`` using some_template`` or `` using`` (as the final tag argument)

    Specify the template to use.



`` extends some_template`` or `` extends`` (as the final tag argument)

    Extends an existing template (via the use of ``{% block %}`` tags).

    See the `Extend form-related templates inline`_ section.



The ``using`` argument without a template or either form of the ``extends``

argument means that the template is being defined inline until a closing

``{% end-`` tag is reached (matching the opening tag, for example, 

``{% form extends "forms/custom.html" %}...{% endform %}``).



Other Tags

==========



``{% get_ordered_fields %}``

--------------------------



Used by form templates to retrieve an ordered list of form fields.



Usage::



    {% get_ordered_fields forms_list as var_name %}



Adds a context variable containing a list of fields.



``{% ifcontent %}``

-------------------



Not specific to forms, a useful tag which allows wrapping text if the content

contains non-whitespace. For example, conditionally showing the help text div

inside of the field template::



    {% ifcontent %}

        


            {% content %}

                {% block help %}{{ help_text }}{% endblock %}

            {% endcontent %}

        


    {% endifcontent %}



Examples of extending form-related templates inline

===================================================



Here are some basic examples::



    {% form form1 form2 extends "forms/p.html" %}



        {% block config %}

            {% formconfig field using "forms/fields/booleanselect.html" for form1.accept_tos %}

        {% endblock %}



    {% endform %}



    {% form form1 extends "forms/p.html" %}



        {% block config %}

            {### Set all rows to use a special "p", except for the TOS #}

            {% formconfig row using "forms/rows/special-p.html" %}

            {% formconfig row using "forms/rows/p.html" for form1.accept_tos %}

        {% endblock %}



    {% endform %}



And here's one more slightly more complex example that extends both the form

and a field's template::



    {% form extends "forms/p.html" %}



        {% block config %}

            {% formconfig field for form.is_manager extends %}

                {% block help %}{% blocktrans with site=site.name %}Can this person manage {{ site }}?{% endblocktrans %}{% endblock %}

            {% endformconfig %}

        {% endblock %}

        

        {% block fields %}

            {% row form.first_name form.last_name %}

            {% row form.email with class="email" %}

            {% row form.is_manager %}

        {% endblock fields %}



    {% endform %}



Change the default order of form fields

=======================================



Use the ``priority`` argument of :ref:`formconfig-tag` to order fields without

the need to manually redefine all fields in the form.

To give fields a priority to the top of the form, use positive integers (the

lower the number, the higher priority).



Use negative integers to give fields a low priority (i.e. occuring after both

those with a positive priority and those without a priority set at all).



If multiple fields are given the same priority, the fields configured first

will have the highest priority::



    {% form form1 form2 extends "forms/p.html" %}



        {% block config %}

            {### Put these three fields to the top, in this order #}

            {% formconfig field for "first_name" priority 1 %}

            {% formconfig field for "last_name" priority 1 %}

            {% formconfig field for "email" priority 1 %}

            {### And put this one to the bottom #}

            {% formconfig field for "accept_tos" priority -1 %}

        {% endblock %}



    {% endform %}



If you are creating an entire form template, use this tag to initiate the

reordering of a form's fields::



    {% formreorder form %}



This is done in all the built-in form templates.



Example of a form template

==========================



``forms/p.html``::



    {% block allconfig %}

        {% formconfig row using "forms/rows/p.html" %}

        {% block config %}{% endblock %}

    {% endblock %}

    

    {% if non_field_errors %}

    
    

            {% for errors in form.non_field_errors %}

            
  • {{ errors }}
    • 

            {% endfor %}

        


    {% endif %}

    

    {% get_rows_ordered forms as rows %}

    {% block rows %}

    {% for fields in rows %}

        {% row fields %}

    {% endfor %}

    {% endblock %}



``forms/rows/base.html``::



    {% block row_start %}{% endblock %}

    {% for form, field in fields %}

        {% block start %}{% endblock %}

        {% field field %}

        {% block end %}{% endblock %}

    {% endfor %}

    {% block row_end %}{% endblock %}



``forms/rows/p.html``::



    {% extends "forms/rows/base.html" %}

    {% block start %}
{% endblock %}

    {% block end %}
{% endblock %}



``form/fields/base.html``::



    {% if label %}

        {% block label %}{{ label }}{% endblock %}

    {% endif %}

    

    {% if errors %}

    
    

        {% for error in errors %}

            
  • {{ error }}
    • 

        {% endfor %}

        


    {% endif %}

    {% ifcontent %}

        

            {% content %}

                {% block help %}{{ help_text }}{% endblock %}

            {% endcontent %}

        

    {% endifcontent %}