django-twitterbootstrap-form 0.4.0
Render Django forms as described using the twitter bootstrap HTML layout
License: MIT
Keywords: django,twitter,bootstrap,form

=============================
Django Twitter Bootstrap Form
=============================

Render Django forms using the HTML described by the `Bootstrap 3 <http://getbootstrap.com/css/#forms>`_.

Demo
====

A basic demo is availaible on this `sandbox <http://django-sandbox.geelweb.org/twitter-bootstrap-form>`_

Install
=======

From PyPI::

    pip install django-twitterbootstrap-form

From Source::

    python setup.py install

About Bootstrap 2
-----------------

You can install the 0.2 version of this lib if you still work with old versions
of `Bootstrap <http://twitter.github.com/bootstrap/base-css.html#forms>`_

From PyPI::

    pip install django-twitterbootstrap-form==0.2

From Source::

    git checkout 0.2
    python setup.py install

Requirements
------------

**0.4.0**

 * Django >= 1.8
 * django-widget-tweaks == 1.3

**0.3.3**

 * Django >= 1.4, <= 1.8
 * django-widget-tweaks == 1.3

Configuring
===========

Add ``widget_tweaks`` to your ``INSTALLED_APPS``.

Add ``geelweb.django.twitter_bootstrap_form`` to ``INSTALLED_APPS`` in your settings

Load the tags adding ``{% load twitter_bootstrap %}`` in templates

Template filters
================

**twitter_bootstrap**

This tag takes 4 optional parameters

 * *layout*: Default: "default". Existing layouts are, default, search, inline,
   horizontal
 * *size*: Default: "sm". The column sizes. xs, sm, md, lg.
 * *labelcols*: Default: 2. Number of columns used for labels
 * *fieldcols*: Default: 12 - labelcols. NUmber of columns used for fields.

Example::

    {{ form|twitter_bootstrap }}

Advanced usage::

    {{ form|twitter_bootstrap:"horizontal,md,3,3" }}

More examples
-------------

Default form::

    <form role="form">
        {{ default_form|twitter_bootstrap }}
        <button type="submit" class="btn btn-default">Submit</button>
    </form>

Search form / Navbar form::

    <form role="search" class="navbar-form">
        {{ search_form|twitter_bootstrap:"search" }}
        <button type="submit" class="btn btn-default">Search</button>
    </form>

Inline form::

    <form role="form" class="form-inline">
        {{ inline_form|twitter_bootstrap:"inline" }}
        <button type="submit" class="btn btn-default">Sign in</button>
    </form>

Horizontal form::

    <form role="form" class="form-horizontal">
        {{ horizontal_form|twitter_bootstrap:"horizontal" }}
        <div class="form-group">
            <div class="col-sm-offset-2 col-sm-10">
                <button type="submit" class="btn btn-default">Sign in</button>
            </div>
        </div>
    </form>

Settings
========

**BOOTSTRAP_REQUIRED_SUFFIX**

Default: ' \*'

Required field label suffix.

Widgets
=======

TextInputWithButton
-------------------

Widget to render `bootstrap button addons <http://getbootstrap.com/components/#input-groups-buttons>`_.

Takes one optional argument:

*btn_attrs*

A dictionary containing HTML attributes to be set on the button. The button can
be appened or prepended to the input field using the ``placement`` key set to
``append`` or ``prepend``::

    from geelweb.django.twitter_bootstrap_form.widgets import TextInputWithButton

    field = forms.CharField(widget=TextInputWithButton(btn_attrs={
        'label': 'search',
        'type': 'submit',
        'placement': 'append'
    }))

TextInputWithAddon
------------------

Form widget to render `bootstrap addons <http://getbootstrap.com/components/#input-groups-basic>`_.

Takes three optional arguments:

*addon*

The addon label

*placement*

the addon placement, ``append`` or ``prepend``

*size*

nothing for a normal size, ``input-group-lg`` for a large input and
``input-group-sm`` for a small input.

Example::

    from geelweb.django.twitter_bootstrap_form.widgets import TextInputWithAddon

    field = forms.CharField(widget=TextInputWithAddon(
        addon='.00',
        placement='append',
        size='input-group-lg'
    ))