Dealing with tags¶
There are two ways of using zenfroms app.
First way - use {% zenform %}
and {% endzenform %}
template tags.
In the middle of them you can do whatever you want, tags defines a special
conetxt and track form fields usage.
Second way is the use {% izenform %}
tempalte tag. This tag renders all form,
and don’t allow you to make modifications in field flow.
{% zenform %} and {% endzenform %}¶
Usage
{% zenform form [options key1=value1, key2=value2] %}
Your form goes here!
{% fieldset unused_fields title 'All my form' %}
{% endzenform %}
form
- Django’s formkey1=value1, key2=value2
- options string, which will be converted to a dict. you can add your options and use them later in templates
To use this tag pair, you should use {% fieldset %}
tags.
Follow documentation about this tag usage.
Context
Tag creates special inner conetxt.
form
- original form, passed in argumentsunused_fields
- fields, that were not rendered within the tag.options
- options dict specified in tag definitionTag can watch what fields were used only when you are rendering them with ‘zenforms’ tags. I.e. it couldn’t track used and unused fields if you place them manually.
Example
Render Django’s default UserCreationForm
:
{% zenform form %}
{% fieldset 'username' title 'User data' %}
{% fieldset unused_fields title 'The rest' %}
{% endzenform %}
Templates
Tags {% zenform %}
and {% endzenform %}
uses two templates to wrap the rendered form:
zenforms/zenform_prefix.html
zenforms/zenform_postfix.html
You are welcome to ovreride them in your project.
Note
Zenforms will add a bit of css classes to your widgets. I hope, it wil not crash your app.
It adds textInput
css class for forms.CharField
and forms.EmailField
,
and error
class for bound fields with errors.
{% fieldset %}¶
Second part of {% zenform %}
-{% endzenform %}
tags is {% fieldset %}
tag.
Usage:
{% fieldset 'field1' 'field2' [title 'MyFieldset'] %}
{% fieldset unused_fields %}
'field1' 'field2'
- strings with field names, which will be included in fieldsetMyFieldset
- optionally you can set fieldsset’s title. Therefore, it will be rendered as <h3> tag.
Warning
Aware of use iterable arguments in the {% fieldset %}
tag. Because of unused_fields
argument support,
this tag consider all iterables as unused_fields
.
Template
This tag uses 'zenforms/fieldset.html'
template. There is nothing interesting there,
only includes and cycles. You wouldn’t like to override it.
But in zenforms/fields
you may find something interesting.
Common fields are rendered with zenforms/fields/single.html
template.
{% multifield %}¶
If you want to group several fields in one line of form this tag is for you.
Usage:
{% multifield args as varname [label 'Label'] %}
- args - List of form field names, which you want to group. Quotes are nessecary,
- varname - output variable name. Quotes are not nessecary,
- label - optional group’s name.
Multifield tag returns object recognizable by {% fieldset %}
so you do the following:
{% multifield 'first_name' 'last_name' as credentials label 'Enter your name' %}
{% fieldset credentials 'password1' 'password2' %}
Template
{% multifield %}
tag renders it’s contents via zenforms/fields/multi.html
template.
You may override it.
{% readonly %}¶
I faced with the task to display data and then edit it. I created this tag as a solution.
{% readonly %}
tag renders django’s model instance data like it would be in form.
Usage:
{% readonly instance 'field1' 'field2' [label 'MyLabel'] [as varname] %}
instance
- Django model instance'field1' 'field2'
- list of instance fields. It is important that model must have that fieldsMyLabel
- you can optionally specify a label for all fields, for example, User datavarname
- optionally saves rendered fields into template variable for futher usage.
ReadonlyTag also returns recognizable by {% fieldset %}
value, you can mix fields, multifields
and read-olny-fields as you wish.
{% zenform form %}
{% readonly admin 'username' 'last_name' label 'Your admin data' as admin_data %}
{% multifield 'first_name' 'last_name' as credentials label 'Enter your name' %}
{% fieldset admin_data credentials unused_fields %}
{% endzenform %}
Template
{% readonly %}
tag renders it’s contents via zenforms/fields/readonly.html
template.
You may override it too.
{% submit %}¶
Very simple tag. Renders submit button in button holder for you.
Usage:
{% submit [value] %}
value
- submit value, for example, ‘Save’ or ‘Send’
Template
Tag uses zenforms/submit.html
tempalte. Override it if you wish.
{% izenform %}¶
Finally! The last tag {% izenform %}
renders for without bunch of template tags,
if simply renders all form fields into one fieldset. In the most cases it is tag-what-you-need.
Usage:
{% izenform form [options key1=value1, key2=value2] %}
Options are the same as for {% zenform %} tags:
form
- Django’s formkey1=value1, key2=value2
- options string, which will be converted to a dict. you can add your options and use them later in templates
Template
Tag uses zenforms/zenform_inline.html
template. Nothing interesting there.
{{ form.field|attrs:”class=required”}}¶
If you want to quickly modify input attribute, you can use attrs
tempalte filter.
Usage:
{{ form.field|attrs:"attr1=value1,attr2=value2,attr3=value3 value4" }}
Pretty simple to write more.
Zenform options¶
There are several pre-defined options.
- notag - if
options.notag
returns True, form will be rendered without tag - nocsrf - zeonforms automatically insert
{% scrf_token %}
in all forms. If you’re using GET method, you’ll definetly need this option. - action - form action
- method - form method
- inline - if
options.inline
returns True, form will be rendered in alternate layout, the label is on the left side of field, rather than on the top - submit - submit text, used in
zenforms/submit.html
template, as submit control value.