<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>FormHelper &mdash; django-crispy-forms 1.0.0 documentation</title>
    
    <link rel="stylesheet" href="_static/flasky.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '1.0.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="django-crispy-forms 1.0.0 documentation" href="index.html" />
    <link rel="next" title="Layouts" href="layouts.html" />
    <link rel="prev" title="{% crispy %} tag with forms" href="crispy_tag_forms.html" />
   
  
  <link media="only screen and (max-device-width: 480px)" href="_static/small_flask.css" type= "text/css" rel="stylesheet" />

  </head>
  <body>
    <div class="related">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="genindex.html" title="General Index"
             accesskey="I">index</a></li>
        <li class="right" >
          <a href="py-modindex.html" title="Python Module Index"
             >modules</a> |</li>
        <li class="right" >
          <a href="layouts.html" title="Layouts"
             accesskey="N">next</a> |</li>
        <li class="right" >
          <a href="crispy_tag_forms.html" title="{% crispy %} tag with forms"
             accesskey="P">previous</a> |</li>
        <li><a href="index.html">django-crispy-forms 1.0.0 documentation</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body">
            
  <div class="section" id="formhelper">
<span id="form-helpers"></span><h1>FormHelper<a class="headerlink" href="#formhelper" title="Permalink to this headline">¶</a></h1>
<p>What is a <tt class="docutils literal"><span class="pre">FormHelper</span></tt> and how to use it, is throughly explained in a previous section <a class="reference internal" href="crispy_tag_forms.html#crispy-tag-forms"><em>{% crispy %} tag with forms</em></a>.</p>
<div class="section" id="formhelper-with-a-form-attached-default-layout">
<span id="helper-form-attached"></span><h2>FormHelper with a form attached (Default layout)<a class="headerlink" href="#formhelper-with-a-form-attached-default-layout" title="Permalink to this headline">¶</a></h2>
<p>Since version 1.2.0 <tt class="docutils literal"><span class="pre">FormHelper</span></tt> optinally can be passed an instance of a form. You would do it this way:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">ExampleForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
        <span class="nb">super</span><span class="p">(</span><span class="n">ExampleForm</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">helper</span> <span class="o">=</span> <span class="n">FormHelper</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
</pre></div>
</div>
<p>When you do this crispy-forms builds a default layout using <tt class="docutils literal"><span class="pre">form.fields</span></tt> for you, so you don&#8217;t have to manually list them all if your form is huge. If you later need to manipulate some bits of a big layout, using dynamic layouts it&#8217;s highly recommended, check <a class="reference internal" href="dynamic_layouts.html#dynamic-layouts"><em>Updating layouts on the go</em></a>.</p>
<p>Also, now the helper is able to cross match the layout with the form instance, being able to search by widget type if you are using dynamic API.</p>
</div>
<div class="section" id="helper-attributes-you-can-set">
<span id="helper-attributes"></span><h2>Helper attributes you can set<a class="headerlink" href="#helper-attributes-you-can-set" title="Permalink to this headline">¶</a></h2>
<dl class="docutils">
<dt><strong>template</strong></dt>
<dd>When set allows you to render a form/formset using a custom template. Default template is at <tt class="docutils literal"><span class="pre">{{</span> <span class="pre">TEMPLATE_PACK</span> <span class="pre">}}/[whole_uni_form.html|whole_uni_formset.html]</span></tt></dd>
<dt><strong>field_template</strong></dt>
<dd>When set allows you to render a form/formset using a custom field template. Default template is at <tt class="docutils literal"><span class="pre">{{</span> <span class="pre">TEMPLATE_PACK</span> <span class="pre">}}/field.html</span></tt>. Beware that this is only effective when setting a <tt class="docutils literal"><span class="pre">FormHelper.layout</span></tt>.</dd>
<dt><strong>form_method = &#8216;POST&#8217;</strong></dt>
<dd>Specifies form method attribute. You can see it to ‘POST’ or ‘GET’. Defaults to ‘POST’</dd>
<dt><strong>form_action</strong></dt>
<dd><p class="first">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:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">url</span><span class="p">(</span><span class="s">r&#39;^show/profile/$&#39;</span><span class="p">,</span> <span class="s">&#39;show_my_profile_view&#39;</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="s">&#39;show_my_profile&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>You can also point it to a URL ‘/whatever/blabla/’.</p>
<p>Sometimes you may want to add arguments to the URL, for that you will have to do in your view:</p>
<div class="last highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.core.urlresolvers</span> <span class="kn">import</span> <span class="n">reverse</span>
<span class="n">form</span><span class="o">.</span><span class="n">helper</span><span class="o">.</span><span class="n">form_action</span> <span class="o">=</span> <span class="n">reverse</span><span class="p">(</span><span class="s">&#39;url_name&#39;</span><span class="p">,</span> <span class="n">args</span><span class="o">=</span><span class="p">[</span><span class="n">event</span><span class="o">.</span><span class="n">id</span><span class="p">])</span>
<span class="n">form</span><span class="o">.</span><span class="n">helper</span><span class="o">.</span><span class="n">form_action</span> <span class="o">=</span> <span class="n">reverse</span><span class="p">(</span><span class="s">&#39;url_name&#39;</span><span class="p">,</span> <span class="n">kwargs</span><span class="o">=</span><span class="p">{</span><span class="s">&#39;book_id&#39;</span><span class="p">:</span> <span class="n">book</span><span class="o">.</span><span class="n">id</span><span class="p">})</span>
</pre></div>
</div>
</dd>
<dt><strong>attrs</strong></dt>
<dd><p class="first">Added in 1.2.0, a dictionary to set any kind of form attributes. Underscores in keys are translated into hyphens. The recommended way when you need to set several form attributes in order to keep your helper tidy:</p>
<div class="last highlight-python"><pre>``{'id': 'form-id', 'data_id': '/whatever'}``
&lt;form id="form-id" data-id="/whatever" ...&gt;</pre>
</div>
</dd>
<dt><strong>form_id</strong></dt>
<dd>Specifies form DOM id attribute. If no id provided then no id attribute is created on the form.</dd>
<dt><strong>form_class</strong></dt>
<dd>String containing separated CSS clases to be applied to form class attribute. The form will always have by default ‘uniForm’ class.</dd>
<dt><strong>form_tag = True</strong></dt>
<dd>It specifies if <tt class="docutils literal"><span class="pre">&lt;form&gt;&lt;/form&gt;</span></tt> tags should be rendered when using a Layout. If set to <tt class="docutils literal"><span class="pre">False</span></tt> it renders the form without the <tt class="docutils literal"><span class="pre">&lt;form&gt;&lt;/form&gt;</span></tt> tags. Defaults to <tt class="docutils literal"><span class="pre">True</span></tt>.</dd>
<dt><strong>disable_csrf = False</strong></dt>
<dd>Disable CSRF token, when done, crispy-forms won&#8217;t use <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">crsf_token</span> <span class="pre">%}</span></tt> tag. This is useful when rendering several forms using <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">crispy</span> <span class="pre">%}</span></tt> tag and <tt class="docutils literal"><span class="pre">form_tag</span> <span class="pre">=</span> <span class="pre">False</span></tt> csrf_token gets rendered several times.</dd>
<dt><strong>form_error_title</strong></dt>
<dd>If you are rendering a form using <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">crispy</span> <span class="pre">%}</span></tt> tag and it has <tt class="docutils literal"><span class="pre">non_field_errors</span></tt> to display, they are rendered in a div. You can set the title of the div with this attribute. Example: “Form Errors”.</dd>
<dt><strong>formset_error_title</strong></dt>
<dd>If you are rendering a formset using <tt class="docutils literal"><span class="pre">{%</span> <span class="pre">crispy</span> <span class="pre">%}</span></tt> tag and it has <tt class="docutils literal"><span class="pre">non_form_errors</span></tt> to display, they are rendered in a div. You can set the title of the div with this attribute. Example: “Formset Errors”.</dd>
<dt><strong>form_style = &#8216;default&#8217;</strong></dt>
<dd>Helper attribute for uni_form template pack. Uni-form has two different form styles built-in. You can choose which one to use, setting this variable to <tt class="docutils literal"><span class="pre">default</span></tt> or <tt class="docutils literal"><span class="pre">inline</span></tt>.</dd>
<dt><strong>form_show_errors = True</strong></dt>
<dd>Default set to <tt class="docutils literal"><span class="pre">True</span></tt>. It decides wether to render or not form errors. If set to <tt class="docutils literal"><span class="pre">False</span></tt>, form.errors will not be visible even if they happen. You have to manually render them customizing your template. This allows you to customize error output.</dd>
<dt><strong>render_unmentioned_fields = False</strong></dt>
<dd>By default django-crispy-forms renders the layout specified if it exists strictly, which means it only renders what the layout mentions, unless your form has <tt class="docutils literal"><span class="pre">Meta.fields</span></tt> and <tt class="docutils literal"><span class="pre">Meta.exclude</span></tt> defined, in that case it uses them. If you want to render unmentioned fields (all form fields), for example if you are worried about forgetting mentioning them you have to set this property to <tt class="docutils literal"><span class="pre">True</span></tt>. It defaults to <tt class="docutils literal"><span class="pre">False</span></tt>.</dd>
<dt><strong>render_hidden_fields = False</strong></dt>
<dd>By default django-crispy-forms renders the layout specified if it exists strictly. Sometimes you might be interested in rendering all form&#8217;s hidden fields no matter if they are mentioned or not. It defaults to <tt class="docutils literal"><span class="pre">False</span></tt>.</dd>
<dt><strong>render_required_fields = False</strong></dt>
<dd>By default django-crispy-forms renders the layout specified if it exists strictly. Sometimes you might be interested in rendering all form&#8217;s hidden required fields no matter if they are mentioned or not. It defaults to <tt class="docutils literal"><span class="pre">False</span></tt>.</dd>
</dl>
</div>
<div class="section" id="bootstrap-helper-attributes">
<h2>Bootstrap Helper attributes<a class="headerlink" href="#bootstrap-helper-attributes" title="Permalink to this headline">¶</a></h2>
<p>There are currently some helper attributes that only have functionality for a specific template pack. This doesn&#8217;t necessarily mean that they won&#8217;t be supported for other template packs in the future.</p>
<dl class="docutils">
<dt><strong>help_text_inline = False</strong></dt>
<dd>Sets whether help texts should be rendered inline or block. If set to <tt class="docutils literal"><span class="pre">True</span></tt> help texts will be rendered <tt class="docutils literal"><span class="pre">help-inline</span></tt> class, otherwise using <tt class="docutils literal"><span class="pre">help-block</span></tt>. By default text messages are rendered in block mode.</dd>
<dt><strong>error_text_inline = True</strong></dt>
<dd>Sets whether to render error messages inline or block. If set to <tt class="docutils literal"><span class="pre">True</span></tt> errors will be rendered using <tt class="docutils literal"><span class="pre">help-inline</span></tt> class, otherwise using <tt class="docutils literal"><span class="pre">help-block</span></tt>. By default error messages are rendered in inline mode.</dd>
<dt><strong>html5_required = False</strong></dt>
<dd>When set to <tt class="docutils literal"><span class="pre">True</span></tt> all required fields inputs will be rendered with HTML5 <tt class="docutils literal"><span class="pre">required=required</span></tt> attribute.</dd>
<dt><strong>form_show_labels = True</strong></dt>
<dd>Default set to <tt class="docutils literal"><span class="pre">True</span></tt>. It decides wether to render or not form&#8217;s fields labels.</dd>
</dl>
</div>
<div class="section" id="bootstrap-3-helper-attributes">
<h2>Bootstrap 3 Helper attributes<a class="headerlink" href="#bootstrap-3-helper-attributes" title="Permalink to this headline">¶</a></h2>
<p>All previous, <tt class="docutils literal"><span class="pre">bootstrap</span></tt> (version 2) attributes are also settable in bootstrap 3 template pack <tt class="docutils literal"><span class="pre">FormHelpers</span></tt>. Here are listed the ones, that are only availble in <tt class="docutils literal"><span class="pre">bootstrap3</span></tt> template pack:</p>
<dl class="docutils">
<dt><strong>label_class = &#8216;&#8217;</strong></dt>
<dd>Default set to <tt class="docutils literal"><span class="pre">''</span></tt>. This class will be applied to every label, this is very useful to do horizontal forms. Set it for example like this <tt class="docutils literal"><span class="pre">label_class</span> <span class="pre">=</span> <span class="pre">col-lg-2</span></tt>.</dd>
<dt><strong>field_class = &#8216;&#8217;</strong></dt>
<dd>Default set to <tt class="docutils literal"><span class="pre">''</span></tt>. This class will be applied to every div <tt class="docutils literal"><span class="pre">controls</span></tt> wrapping a field. This is useful for doing horizontal forms. Set it for example like this <tt class="docutils literal"><span class="pre">field_class</span> <span class="pre">=</span> <span class="pre">col-lg-8</span></tt>.</dd>
</dl>
</div>
<div class="section" id="custom-helper-attributes">
<h2>Custom Helper attributes<a class="headerlink" href="#custom-helper-attributes" title="Permalink to this headline">¶</a></h2>
<p>Maybe you would like that <tt class="docutils literal"><span class="pre">FormHelper</span></tt> did some extra thing that is not currently supported or maybe you have a very specific use case. The good part is that you can add extra attributes and crispy-forms will automagically inject them within template context. Let&#8217;s see an example, to make things clear.</p>
<p>We want some forms to have labels uppercase, for that we would like to set a helper attribute name <tt class="docutils literal"><span class="pre">labels_uppercase</span></tt> to <tt class="docutils literal"><span class="pre">True</span></tt> or <tt class="docutils literal"><span class="pre">False</span></tt>. So we go and set in our helper:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">helper</span><span class="o">.</span><span class="n">labels_uppercase</span> <span class="o">=</span> <span class="bp">True</span>
</pre></div>
</div>
<p>What will happen is that crispy-forms will inject a Django template variable named <tt class="docutils literal"><span class="pre">{{</span> <span class="pre">labels_uppercase</span> <span class="pre">}}</span></tt> with its corresponding value within its templates, including <tt class="docutils literal"><span class="pre">field.html</span></tt>, which is the template in charge of rendering a field when using crispy-forms. So we can go into that template and customize it. We will need to get familiar with it, but it&#8217;s quite easy to follow, in the end it&#8217;s only a Django template.</p>
<p>When we find where labels get rendered, this chunk of code to be more precise:</p>
<div class="highlight-python"><pre>{% if field.label and not field|is_checkbox and form_show_labels %}
    &lt;label for="{{ field.id_for_label }}" class="control-label {% if field.field.required %}requiredField{% endif %}"&gt;
        {{ field.label|safe }}{% if field.field.required %}&lt;span class="asteriskField"&gt;*&lt;/span&gt;{% endif %}
    &lt;/label&gt;
{% endif %}</pre>
</div>
<p>The line that we would change wold end up like this:</p>
<div class="highlight-python"><pre>{% if not labels_uppercase %}{{ field.label|safe }}{% else %}{{ field.label|safe|upper }}{% endif %}{% if field.field.required %}</pre>
</div>
<p>Now we only need to override field template, for that you may want to check section <a class="reference internal" href="layouts.html#override-templates"><em>Overriding layout objects templates</em></a>.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Be careful, depending on what you aim to do, sometimes using dynamic layouts is a better option, check section <a class="reference internal" href="dynamic_layouts.html#dynamic-layouts"><em>Updating layouts on the go</em></a>.</p>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar">
        <div class="sphinxsidebarwrapper"><h3 style="font-size: 30px;"><a href="index.html">crispy-forms</a></h3>
<p>
  <iframe src="http://ghbtns.com/github-btn.html?user=maraujop&repo=django-crispy-forms&type=watch&count=true&size=large"
    allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
</p>

<p>
  django-crispy-forms is a Django application that lets you easily build, customize and reuse forms using your favorite CSS framework, without writing template code and without having to take care of annoying details. You are currently looking at the documentation of the development release.
</p>


<h3>Support</h3>
<p>
    If you love django-crispy-forms, consider making a small donation <a href="http://flattr.com/thing/512037/django-crispy-forms">on Flattr</a>:
</p>
<p>
    <a class="FlattrButton" style="display:none;" rev="flattr;button:compact;" href="http://django-crispy-forms.rtfd.org"></a>
    <noscript><a href="http://flattr.com/thing/512037/django-crispy-forms" target="_blank">
    <img src="http://api.flattr.com/button/flattr-badge-large.png" alt="Flattr this" title="Click to flattr django-crispy-forms" border="0" /></a></noscript>
</p>
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">FormHelper</a><ul>
<li><a class="reference internal" href="#formhelper-with-a-form-attached-default-layout">FormHelper with a form attached (Default layout)</a></li>
<li><a class="reference internal" href="#helper-attributes-you-can-set">Helper attributes you can set</a></li>
<li><a class="reference internal" href="#bootstrap-helper-attributes">Bootstrap Helper attributes</a></li>
<li><a class="reference internal" href="#bootstrap-3-helper-attributes">Bootstrap 3 Helper attributes</a></li>
<li><a class="reference internal" href="#custom-helper-attributes">Custom Helper attributes</a></li>
</ul>
</li>
</ul>
<h3>Related Topics</h3>
<ul>
  <li><a href="index.html">Documentation overview</a><ul>
      <li>Previous: <a href="crispy_tag_forms.html" title="previous chapter">{% crispy %} tag with forms</a></li>
      <li>Next: <a href="layouts.html" title="next chapter">Layouts</a></li>
  </ul></li>
</ul>
  <h3>This Page</h3>
  <ul class="this-page-menu">
    <li><a href="_sources/form_helper.txt"
           rel="nofollow">Show Source</a></li>
  </ul>
<div id="searchbox" style="display: none">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <script type="text/javascript">
    /* <![CDATA[ */
        (function() {
            var s = document.createElement('script'), t = document.getElementsByTagName('script')[0];
            s.type = 'text/javascript';
            s.async = true;
            s.src = 'http://api.flattr.com/js/0.6/load.js?mode=auto';
            t.parentNode.insertBefore(s, t);
        })();
    /* ]]> */</script>

    <div class="footer">
      &copy; Copyright 2009-2013, Miguel Araujo and Daniel Greenfeld.
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
    </div>
  </body>
</html>