================
deform_bootstrap
================
``deform_bootstrap`` provides `Twitter Bootstrap
<http://twitter.github.com/bootstrap/>`_ compatible widgets, templates
and styles for the `deform form library
<http://pypi.python.org/pypi/deform/0.9.4>`_.
deform_bootstrap is `developed on GitHub
<https://github.com/Kotti/deform_bootstrap>`_. Latest `releases are
available on PyPI <http://pypi.python.org/pypi/deform_bootstrap>`_.
How to use it
=============
I just downloaded this and wanna use it
---------------------------------------
In your Paste Deploy configuration file (e.g. ``development.ini``) add
``deform_bootstrap`` to the list of ``pyramid_includes``, or add a
this line if a ``pyramid.includes`` setting does not exist::
[app:main]
...
pyramid.includes = deform_bootstrap
This will put the templates in ``deform_bootstrap/templates`` into the
`deform search path
<http://docs.pylonsproject.org/projects/deform/en/latest/templates.html>`_.
I want to try it before using
-----------------------------
If you want to quickly try out ``deform_bootstrap`` and see how it
looks in practice you can run these commands, assuming that you have a
`virtualenv <http://pypi.python.org/pypi/virtualenv>`_ set up in your
``deform_bootstrap`` directory::
$ git clone https://github.com/Pylons/deformdemo.git
$ cd deformdemo
$ ../bin/python setup.py develop
$ cd ..
$ bin/pserve demo.ini
You should now be able to access the demo site at http://0.0.0.0:8521
Using tabs in forms
-------------------
To make a tabbed form, use mapping. Each mapping will appear as a new
tab, taking the title of the mapping as the name for the tab. If you
specify no tabs for some information, it will default to a '*Basic*'
tab.
A form using the following `Client` schema will render with two tabs
'Person data' and 'Car stuffs':
::
import colander
class Person(colander.Schema):
name = colander.SchemaNode(
colander.String(),
title='Name',
)
surname = colander.SchemaNode(
colander.String(),
title='Surname',
)
class Car(colander.Schema):
color = colander.SchemaNode(
colander.String(),
title='Color',
)
horsepower = colander.SchemaNode(
colander.Integer(),
title='Horsepower',
)
class Client(colander.Schema):
person = Person(title='Person data')
car = Car(title='Car stuffs')
Additional widgets / getting rid of legacy stuff
================================================
jQueryUI
--------
Deform depends on ``jQueryUI`` for these wigdgets:
- AutocompleteInputWidget
- DateInputWidget
- DateTimeInputWidget
``deform_bootstrap`` comes with widgets that replace these, and that are
compatible with Bootstrap. If you don't use any of these, you can skip
the remainder of this section and just delete ``jQueryUI`` from your CSS
and JS imports. Otherwise you'll need to add ``bootstrap-typeahead.js``
and/or ``bootstrap-datepicker.js`` to your JS includes.
You can then use deform_bootstrap's TypeaheadInputWidget as a drop in
replacement for deform's AutocompleteInputWidget.
Unfortunately things are a litte more complicated for DateInputWidget and
DateTimeInputWidget, because ``bootstrap`` does not provide native widgets
for that usecases (yet?). Therefore you will need to either use
``deform_bootstrap.css`` provided by ``deform_bootstrap`` or build your own
``bootstrap.css`` using `LESS <http://lesscss.org/>`. Once you have ``lessc``
installed it can be done like this::
$ cd deform_bootstrap/static
$ lessc deform_bootstrap.less
You'll then find your custom ``deform_bootstrap.css`` which immediately leads
to a shiny new look for DateInputWidgets. For DateTimeInputWidgets you'll
have to replace your existing imports. This is as easy as replacing
``from deform.widget import DateTimeInputWidget`` with
``from deform_bootstrap.widget import DateTimeInputWidget`` in your code.
<ul> / <li> markup
------------------
Deform uses <ul> / <li> markup for rendering sequences. Although one can
argue, that this is semanticaly correct, it doesn't make much sense in the
context of form rendering and requires quite some additional CSS to produce
visually appealing results. Therefore ``deform_bootstrap`` removes all list
markup and generates nice forms with no additional CSS required.
In order to make this work with not only with fixed length sequences, but
also variable length sequences, 2 functions in ``deform.js`` needs to be
patched. This can be done by simply adding the provided
``deform_bootstrap.js`` to your JS requirements. If your application doesn't
use variable length sequences, you can safely skip this step.
Chosen by Harvest
-----------------
A progressively enhanced replacement for HTML select elements, Chosen
implements single and multiple selection modes that offer a much better
UX than the standard widgets.
It has autocomplete features, placeholder support and a slick style that
looks good either with or without Bootstrap.
See http://harvesthq.github.com/chosen/ for documentation and examples.
Only the jQuery version is provided by this package.
Static resources
================
``deform_bootstrap`` comes with a bunch of static resources, which might
confuse you. Fortunately most of them are just needed to pass *all the* tests
and most most of them (if any) won't be needed in your ``deform_bootstrap``
based application.
CSS
---
``deform_bootstrap.css``
This file contains the complete Bootstrap 2.0.1 CSS plus additional
styles for the datepicker widget (see above). You may use it for your
application (great for initial development), but might also want to consider
rolling your own customized version for deployment.
``jquery_chosen/chosen.css``
The main style for ``ChosenSingleWidget`` and ``ChosenMultipleWidget``.
``chosen_bootstrap.css``
This file contains a small fix for conflicts between chosen and bootstrap.
Only needed if you make use of chosen, but harmless if you don't.
``bootstrap-datepicker.css``
The styles for the *native* bootstrap datepicker widget (see above).
Note that ``chosen_bootstrap.css`` and ``bootstrap-datepicker.css``
are included in ``deform_bootstrap.css``, so you will only need them
if you use some other version of the bootstrap css.
JS
--
``bootstrap-datepicker.js``
Only needed if you want to use the *native* bootstrap datepicker widget
(see above).
``bootstrap_typeahead.js``
Only needed if you want to use the *native* bootstrap datepicker widget
(see above).
``bootstrap.min.js``
Only needed as a direct dependency of the ``bootstrap_XXX.js`` files.
``deform_bootstrap.js``
Only needed as if you want to use *variable length sequences*
(see "<ul> / <li> markup" above).
``jquery-x.x.x.min.js``
Only needed if you want to use any of the other JS resources.
``jquery-ui-x.x.x.custom.min.js``
Only needed if prefer using deform's orinial ``AutocompleteInputWidget``
over deform_bootstrap's ``TypeaheadInputWidget`` or deform's
``DateTimeInputWidget`` over deform_bootstrap's *native* version
(see above).
``jquery-ui-timepicker-addon-x.x.x.js``
Same as for ``jquery-ui-x.x.x.custom.min.js``.
``jquery.form-2.96.js``
Only needed if you want to use ``use_ajax=True`` with ``deform.Form``.
``jquery.maskedinput-x.x.js``
Only needed if you want ``mask='...'`` with any of the ``deform``
widgets that support it.
``jquery_chosen/chosen.jquery.js``
Only needed if you use ``ChosenSingleWidget``, ``ChosenOptGroupWidget``, or
``ChosenMultipleWidget``,
LESS / twitter_bootstrap
------------------------
Not needed at all. Only used internally to build the custom
``deform_bootstrap.css`` with the additional datepicker styles.
Information for developers / contributors
=========================================
Running unit tests
------------------
::
$ bin/python setup.py dev
$ bin/py.test
deformdemo
----------
``deform_bootstrap`` passes 100% of the `deformdemo
<http://deformdemo.repoze.org/>`_ tests. Please do run the Selenium
tests before submitting a patch.
However, bootstrap requires a newer version of jquery than deform ships
with by default. This in turn would require a newer version of jquery.form
(> 2.43) which unfortunately is backward incompatible in its ajax handling.
Thus, deform_bootstrap cannot currently support deform's ``use_ajax`` feature.
The corresponding selenium tests have therefore been disabled until deform
catches up. Note, that you can still use jquery.form itself.
Running Selenium tests
----------------------
* Make sure you have a Java interpreter installed.
* Download Selenium Server <http://seleniumhq.org/download/> standalone jar file.
* Start the server with demo.ini.
* In another terminal, run ``java -jar selenium-server-standalone-X.X.jar``.
Success is defined as seeing output on the console that ends like this:
01:49:06.105 INFO - Started SocketListener on 0.0.0.0:4444
01:49:06.105 INFO - Started org.openqa.jetty.jetty.Server@7d2a1e44
* In yet another terminal, run the tests with the command:
$ bin/python deform_bootstrap/demo/test.py
API
===
input_prepend / input_append
----------------------------
Bootstrap has a nice feature to prepend/append text to input[type=text]
form elements (see http://twitter.github.com/bootstrap/base-css.html#forms).
To use it with ``deform_bootstrap`` you can simply pass ``input_prepend``
or ``input_append`` as keyword arguments to the widget constructor in your
``colander.Schema`` subclass::
class PersonSchema(colander.Schema):
weight = colander.SchemaNode(
colander.Integer(),
title=u"Weight",
widget=deform.widget.TextInputWidget(
input_append="kg",
css_class="span1",
))
bootstrap_form_style
--------------------
Bootstrap supports `four form styles`__. By default, ``deform_bootstrap``
uses the ``.form-horizontal`` style. You can specify one of the other
styles be setting the ``bootstrap_form_style`` attribute of your ``Form``::
myform = Form(myschema, bootstrap_form_style='form-vertical')
__ http://twitter.github.com/bootstrap/base-css.html#forms
inline
------
Bootstrap supports inline checkbox and radio choices. Normally
``RadioChoiceWidget``\s and ``CheckboxChoiceWidgets``\s are displayed
with one choice per line. To select the inline style, set the
``inline`` attribute of the choice widget to a trueish value::
class MySchema(colander.Schema):
choice = colander.SchemaNode(
colander.String(),
widget=deform.widget.CheckboxChoiceWidget(
values=[(u'a', u'Apple'),
(u'b', u'Bear'),
(u'c', u'Computer')],
inline=True))
Thanks
======
deform_bootstrap was created by Daniel Nouri. Thanks to the following
people for support, code, patches etc:
- Andreas Kaiser
- Chris McDonough
- Jason Kölker
- Jeff Dairiki
- Marco Mariani
- Tom Lazar
- https://github.com/Kotti/deform_bootstrap/contributors
CHANGES
=======
0.2.9 - 2013-08-09
------------------
- Add bootstrap iconglyphs and fix deform_bootstrap.css to point to
them. See #61
- Add readonly textinput that uses bootstrap styling.
- Add tabbed forms support. See ``README.rst`` for details.
0.2.8 - 2013-06-25
------------------
- Fix resource registry. See #56.
- Work around broken resource_filename() on Google AppEngine. See #57.
- Fix all fields being marked invalid if another field in the same
mapping/sequence is. See #58.
0.2.7 - 2013-05-04
------------------
- Add support for Py3k. See #55.
- Improve test coverage. See #55.
0.2.6 - 2013-02-23
------------------
- Inherit ChosenMultipleWidget from SelectWidget. This fixes broken readonly
SelectWidgets. See #49.
- Add support for css_class argument in Button constructor. See #48.
0.2.5
-----
- Fix normalization of chosen widget values. (#40)
- Add remote source for TypeAheadInputWidget, 'source' attribute
renamed to 'values'. (#37)
- Fixed `sequence_item.pt` not to break in Chameleon. (#39)
0.2.4 - 2012-10-24
------------------
- Add missing requirements (jquery ui timepicker).
0.2.3 - 2012-10-18
------------------
- Add support for deform's new orderable sequence support. See #34.
0.2.2 - 2012-06-11
------------------
- Upgraded Bootstrap to v2.0.4
- Add missing alert class to mapping template for validation errors.
0.2.1 - 2012-04-17
------------------
- Add ChosenOptGroupWidget.
0.2 - 2012-03-20
----------------
- ChosenSingleWidget and ChosenMultipleWidget; includes chosen 0.9.7 [mmariani]
- Add support for "inline" checkbox and radio choices.
- Many bugfixes. Many thanks to dairiki.
0.1 - 2012-02-29
----------------
- Add TypeAheadInputWidget (with Selenium tests).
- Add DateTimeInputWidget (with "native" Bootstrap CSS/JS and Selenium tests).
- Ged rid of jQueryUI legacy.
- Get rid of ul/li markup legacy.
- Restructure / update documentation.
- Include latest versions of all JS/CSS resources, Bootstrap 2.0.1 LESS files
with additional datepicker widget.
0.1a5 - 2012-02-09
------------------
- All deformdemo Selenium tests passing.
- Add sequence templates.
0.1a4 - 2012-02-09
------------------
- In ``includeme``, prepend deform search path instead of resetting
the whole renderer.
0.1a3 - 2012-02-03
------------------
- Changes to support Bootstrap 2.0.
- Added support for Bootstrap's feature to prepend/append text to
``input[type=text]`` via input_prepend/input_append keyword
arguments to ``deform.Widget`` constructor.