Benoît Bryon avatar Benoît Bryon committed ce7f153

Reviewed documentation and setup.py

Comments (0)

Files changed (18)

 #########################
-djc.formrenderingtools
+django-formrenderingtools
 #########################
 
 djc.formrenderingtools is an application for the `Django framework
 Rather than using {{ form.as_p }}, set up and reuse templates to render 
 Django's form elements.
 
-Currently, this application provides a "form_layouts" template tag library
+For the impatient, use the bundled demo project to discover and try the
+application (see docs/demo.txt for details).
+
+This application provides a "form_layouts" template tag library
 which itself provides the following template tags:
 
 * form: renders a full form, i.e. non field errors, all fields, field
 * Python module rename: from django-formrenderingtools to 
   djc.formrenderingtools. The package name does not change (still
   django-formrenderingtools on Pypi).
-* improved documentation
+* Improved documentation
+* Improved packaging. Buildout integration.
+* A demo project is now part of the sourcecode, so that one can quickly
+  discover the application and perform experiments in a sandbox.
 * replaced dependency of Django >= 1.1 by Django >= 1.0
 
 ***********************************
 
 The code is published under the BSD license. See LICENSE for details.
 
-If you want to discover the application, take a look at the
-:doc:`/examples/demo`.
+If you just want to discover the application, have a look at the :doc:`/demo`.
 
 *********************
 Installation synopsis
 Latest release
 ==============
 
-This application is known as "djc.formrenderingtools" on 
+This application is known as "django-formrenderingtools" on 
 `Pypi <http://pypi.python.org/>`_. 
 
 So you can install it with pip or easy_install. As an example::
 
-  # pip install -U djc.formrenderingtools
+  # pip install -U django-formrenderingtools
 
 Obviously, you can also add it to your eggs list in a buildout configuration
 file.
 You can use pip to automatically download and install the project with 
 versionning::
 
-  # pip install -U -e hg+http://bitbucket.org/benoitbryon/djc.formrenderingtools#egg=djc.formrenderingtools
+  # pip install -U -e hg+http://bitbucket.org/benoitbryon/django-formrenderingtools#egg=djc.formrenderingtools
 
 Manual installation
 ===================
 Manual installation is not the recommended way: you'd better learn about
 buildout or virtualenv+pip.
 
-The main project page is http://bitbucket.org/benoitbryon/djc.formrenderingtools.
+The main project page is http://bitbucket.org/benoitbryon/django-formrenderingtools.
 
 You can clone the repository with the following command line:
 
 .. code-block:: bash
 
-  $ hg clone http://bitbucket.org/benoitbryon/djc.formrenderingtools
+  $ hg clone http://bitbucket.org/benoitbryon/django-formrenderingtools
 
-Copy the djc.formrenderingtools folder somewhere in your PYTHON_PATH. It may be in your
-project's directory.
+Copy the django-formrenderingtools/djc folder somewhere in your PYTHON_PATH. It
+may be in your project's directory.
 
 ***************
 Update settings

docs/best_practices.txt

 
 * Put CSS classes to container, so that both container and contained element
   can be styled.
-  As an example:
-  use <div class="hasErrors"><label /><input /></div>
-  rather than <div><label class="hasErrors" /><input /></div>
+  As an example use:
+
+  .. code-block::html
+
+    <div class="hasErrors"><label /><input /></div>
+
+  rather than:
+
+  .. code-block::html
+
+    <div><label class="hasErrors" /><input /></div>
+  
   because the graphic designer may want the DIV's background or the INPUT's 
   border to be red.
 # -*- coding: utf-8 -*-
 #
-# djc.formrenderingtools documentation build configuration file, created by
+# django-formrenderingtools documentation build configuration file, created by
 # sphinx-quickstart on Sat Apr 24 20:02:32 2010.
 #
 # This file is execfile()d with the current directory set to its containing dir.
 master_doc = 'index'
 
 # General information about the project.
-project = u'djc.formrenderingtools'
-copyright = u'2010, Benoit Bryon'
+project = u'django-formrenderingtools'
+copyright = u'2010-2011, Benoit Bryon'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = '0.2'
 # The full version, including alpha/beta/rc tags.
-release = '0.1'
+release = '0.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #html_file_suffix = ''
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'djc.formrenderingtoolsdoc'
+htmlhelp_basename = 'django-formrenderingtoolsdoc'
 
 
 # -- Options for LaTeX output --------------------------------------------------
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'djc.formrenderingtools.tex', u'djc.formrenderingtools Documentation',
+  ('index', 'django-formrenderingtools.tex', u'django-formrenderingtools Documentation',
    u'Benoit Bryon', 'manual'),
 ]
 
+############
+Demo project
+############
+
+Django-formrenderingtools sourcecode contains a demonstration project in the
+demo/ folder.
+
+This project is a demo for the django-formrenderingtools package. Use it to
+quickly see, understand and experiment Django-formrenderingtools concepts.
+
+The demo produces a presentation of django-formrenderingtools usage with
+examples.
+
+Install
+=======
+
+Check requirements. This demo requires the following software to be installed
+on your system:
+
+* Python >= 2.6 ("with" statement in setup.py)
+* Virtualenv
+* Mercurial (if unavailable, download and extract the source from bitbucket
+  manually)
+
+With buildout
+-------------
+
+.. code-block:: bash
+
+  # Get the source
+  hg clone http://bitbucket.org/benoitbryon/django-formrenderingtools
+  # Optional but recommended: create a virtual environment
+  virtualenv --distribute --no-site-packages django-formrenderingtools
+  source django-formrenderingtools/bin/activate
+  # Installation with buildout
+  cd django-formrenderingtools
+  bin/python bootstrap.py -d
+  bin/buildout
+  # You can run the tests!
+  bin/test
+
+If everything went fine, you have a buildout environment and can test the 
+application.
+
+With Virtualenv and pip
+-----------------------
+
+.. code-block:: bash
+
+  # Clone Django-formrenderingtools (or download and extract it):
+  hg clone http://bitbucket.org/benoitbryon/django-formrenderingtools
+  # Create a virtual environment and activate it:
+  virtualenv --no-site-packages --distribute django-formrenderingtools
+  source django-formrenderingtools/bin/activate
+  # Installation with pip
+  cd django-formrenderingtools
+  bin/pip install -r requirements.txt
+  # You can run the tests!
+  bin/python demo/manage.py test formrenderingtools
+
+Look at the demo
+================
+
+* Activate the virtual environment if necessary
+* Run the development server (buildout installation):
+  ::
+
+    bin/django runserver
+
+  Or (virtualenv/pip installation):
+  ::
+  
+    bin/python demo/manage.py runserver
+
+* Open http://localhost:8000/ in your browser.
+* Read the sourcecode in the demo/ folder of your django-formrenderingtools
+  installation.
+
+Experiment
+==========
+
+Use this demo project as a sandbox!
+
+Demo is part of the development process
+=======================================
+
+The demo project is part of the documentation. It has been created to help
+developers discover the application. It explains real-world usage.
+
+The demo project is also intended to become part of the tests.

docs/examples/demo.txt

-######################################
-Django-formrenderingtools demo project
-######################################
-
-Django-formrenderingtools sourcecode contains a demonstration project in the
-demo/ folder.
-
-This project is a demo for the Django-formrenderingtools package. Use it to
-quickly see, understand and experiment Django-formrenderingtools concepts.
-
-Install
-=======
-
-Check requirements. This demo requires the following software to be installed
-on your system:
-
-* Python >= 2.6 ("with" statement in setup.py)
-* Virtualenv
-* Mercurial (if unavailable, download and extract the source from bitbucket
-  manually)
-
-With buildout
--------------
-
-.. code-block:: bash
-
-  # Get the source
-  hg clone http://bitbucket.org/benoitbryon/django-formrenderingtools
-  # Optional but recommended: create a virtual environment
-  virtualenv --distribute --no-site-packages django-formrenderingtools
-  source django-formrenderingtools/bin/activate
-  # Installation with buildout
-  cd django-formrenderingtools
-  bin/python bootstrap.py -d
-  bin/buildout
-  # You can run the tests!
-  bin/test
-
-If everything went fine, you have a buildout environment and can test the 
-application.
-
-With Virtualenv and pip
------------------------
-
-.. code-block:: bash
-
-  # Clone Django-formrenderingtools (or download and extract it):
-  hg clone http://bitbucket.org/benoitbryon/django-formrenderingtools
-  # Create a virtual environment and activate it:
-  virtualenv --no-site-packages --distribute django-formrenderingtools
-  source django-formrenderingtools/bin/activate
-  # Installation with pip
-  cd django-formrenderingtools
-  bin/pip install -r requirements.txt
-  # You can run the tests!
-  bin/python demo/manage.py test formrenderingtools
-
-Look at the demo
-================
-
-* Activate the virtual environment if necessary
-* Run the development server (buildout installation):
-  ::
-
-    bin/django runserver
-
-  Or (virtualenv/pip installation):
-  ::
-  
-    bin/python demo/manage.py runserver
-
-* Open http://localhost:8000/ with your browser
-* Read the sourcecode at django-formrenderingtools/demo
-
-Experiment
-==========
-
-Use this demo project as a sandbox!
-
-Demo is part of the development process
-=======================================
-
-The demo project is part of the documentation. It has been created to help
-developers discover the application. It explains real-world usage.
-
-The demo project is also part of the tests.

docs/examples/form.txt

-##################
-{% form %} example
-##################
-
-The examples below are valid if you do not change the 
-FORMRENDERINGTOOLS_TEMPLATE_DIR setting and do not override the "default"
-layout. If you make some changes, you will get results reflecting the changes!
-
-Examples are taken from djc.formrenderingtools.tests.FormLayoutsTestCase.
-
-***************
-The sample form
-***************
-
-The examples below use the following form definition:
-
-.. code-block:: python
-
-  from django import forms
-  
-  class ContactForm(forms.Form):
-      """
-      A sample form, for use in test cases.
-      """
-      subject = forms.CharField(
-          label='Subject',
-          max_length=100,
-      )
-      message = forms.CharField()
-      sender = forms.EmailField()
-      cc_myself = forms.BooleanField(
-          required=False,
-          help_text='Send a copy of the message to the sender.',
-      )
-    
-      def clean(self):
-          """This sample form never validates!"""
-          raise forms.ValidationError('Sorry, but this sample form never validates!')
-
-This is a quite simple form. If you call is_valid(), then a "non field error"
-is always generated. 
-
-************************************
-The default layout with a valid form
-************************************
-
-This example demonstrates the use of {% form %} with a valid form and
-the default layout.
-
-Python code
-===========
-
-Let's
-
-* instanciate the form (no validation)
-* render it through "my_template.html"
-
-.. code-block:: python
-
-  from django.template.loader import render_to_string
-  
-  default_form = ContactForm() # an empty form, no validation
-  context = {'default_form': default_form}
-  print render_to_string('my_template.html', context)
-
-Template code
-=============
-
-Here is the code of "my_template.html".
-
-.. code-block:: django
-
-  {% load form_layouts %}
-  <form>
-    {% form form=default_form %}
-    <input type="submit">
-  </form>
-
-Output
-======
-
-Here is the generated output (there could be whitespace differences).
-
-.. code-block:: html
-
-  <form>
-    <div class="formItem required subject">
-      <label for="id_subject" class=" required">Subject</label>
-      <input id="id_subject" type="text" name="subject" maxlength="100" />
-    </div>
-    
-    <div class="formItem required message">
-      <label for="id_message" class=" required">Message</label>
-      <input type="text" name="message" id="id_message" />
-    </div>
-    
-    <div class="formItem required sender">
-      <label for="id_sender" class=" required">Sender</label>
-      <input type="text" name="sender" id="id_sender" />
-    </div>
-    
-    <div class="formItem cc_myself">
-      <label for="id_cc_myself" class="">Cc myself</label>
-      <input type="checkbox" name="cc_myself" id="id_cc_myself" />
-      <p class="help">Send a copy of the message to the sender.</p>
-    </div>
-    
-    <input type="submit">
-  </form>
-
-***************************************
-The default layout with an invalid form
-***************************************
-
-This example demonstrates the use of {% form %} with an invalid form and
-the default layout. So there will be error messages.
-
-Python code
-===========
-
-Let's
-
-* instanciate the form with validation
-* render it through "my_template.html"
-
-.. code-block:: python
-
-  from django.template.loader import render_to_string
-  
-  error_form = ContactForm({}) # the same form, with validation (invalid form)
-  context = {'error_form': error_form}
-  print render_to_string('my_template.html', context)
-
-Template code
-=============
-
-Here is the code of "my_template.html".
-
-.. code-block:: django
-
-  {% load form_layouts %}
-  <form>
-    {% form form=error_form %}
-    <input type="submit">
-  </form>
-
-Output
-======
-
-Here is the generated output (there could be whitespace differences).
-
-.. code-block:: html
-
-  <form>
-    <div class="nonFieldErrors">
-      <ul class="errorlist">
-        <li>Sorry, but this sample form never validates!</li>
-      </ul>
-    </div>
-  
-    <div class="formItem hasErrors required subject">
-      <ul class="errorlist">
-        <li>This field is required.</li>
-      </ul>
-      <label for="id_subject" class=" required">Subject</label>
-      <input id="id_subject" type="text" name="subject" maxlength="100" />
-    </div>
-    
-    <div class="formItem hasErrors required message">
-      <ul class="errorlist">
-        <li>This field is required.</li>
-      </ul>
-      <label for="id_message" class=" required">Message</label>
-      <input type="text" name="message" id="id_message" />
-    </div>
-    
-    <div class="formItem hasErrors required sender">
-      <ul class="errorlist">
-        <li>This field is required.</li>
-      </ul>
-      <label for="id_sender" class=" required">Sender</label>
-      <input type="text" name="sender" id="id_sender" />
-    </div>
-    
-    <div class="formItem cc_myself">
-      <label for="id_cc_myself" class="">Cc myself</label>
-      <input type="checkbox" name="cc_myself" id="id_cc_myself" />
-      <p class="help">Send a copy of the message to the sender.</p>
-    </div>
-    
-    <input type="submit">
-  </form>
-
-***********************
-Using an invalid layout
-***********************
-
-The example below demonstrates that if you specify a layout that does not exist,
-then the {% form %} template tag is not able to load it, and finally 
-fallbacks to the default layout.
-
-Python code
-===========
-
-The code is the same as in the first example.
-
-.. code-block:: python
-
-  from django.template.loader import render_to_string
-  
-  default_form = ContactForm() # an empty form, no validation
-  context = {'default_form': default_form}
-  print render_to_string('my_template.html', context)
-
-Template code
-=============
-
-Here is the code of "my_template.html". Let's use a layout which does not 
-exist.
-
-.. code-block:: django
-
-  {% load form_layouts %}
-  <form>
-    {% form form=default_form layout="a_layout_which_does_not_exist" %}
-    <input type="submit">
-  </form>
-
-Output
-======
-
-Here is the generated output. It is the same as in the first example, since the
-default layout has been used.
-
-.. code-block:: html
-
-  <form>
-    <div class="formItem required subject">
-      <label for="id_subject" class=" required">Subject</label>
-      <input id="id_subject" type="text" name="subject" maxlength="100" />
-    </div>
-    
-    <div class="formItem required message">
-      <label for="id_message" class=" required">Message</label>
-      <input type="text" name="message" id="id_message" />
-    </div>
-    
-    <div class="formItem required sender">
-      <label for="id_sender" class=" required">Sender</label>
-      <input type="text" name="sender" id="id_sender" />
-    </div>
-    
-    <div class="formItem cc_myself">
-      <label for="id_cc_myself" class="">Cc myself</label>
-      <input type="checkbox" name="cc_myself" id="id_cc_myself" />
-      <p class="help">Send a copy of the message to the sender.</p>
-    </div>
-    
-    <input type="submit">
-  </form>
-
-**************************************************
-Reordering fields and displaying subsets of fields
-**************************************************
-
-The example below demonstrates how to use the "fields" and "exclude_fields"
-parameters of the {% form %} template tag in order to render subsets of 
-fields and reorder them.
-
-You can combine the "fields" and "exclude_fields" parameters. The latter has
-higher priority (i.e. an excluded field won't be displayed even if in "fields").
-
-Python code
-===========
-
-The code is the same as in the first example.
-
-.. code-block:: python
-
-  from django.template.loader import render_to_string
-  
-  default_form = ContactForm() # an empty form, no validation
-  context = {'default_form': default_form}
-  print render_to_string('my_template.html', context)
-
-Template code
-=============
-
-Here is the code of "my_template.html". Let's display the form in two fieldsets.
-
-.. code-block:: django
-
-  {% load form_layouts %}
-  <form>
-    <fieldset>
-      <legend>First subset of fields: not message nor sender</legend>
-      {% form form=default_form exclude_fields="message,sender" %}
-    </fieldset>
-    
-    <fieldset>
-      <legend>Second subset of fields: sender then message (the order matters)</legend>
-      {% form form=default_form fields="sender,message" %}
-    </fieldset>
-    
-    <input type="submit">
-  </form>
-
-Output
-======
-
-Here is the generated output.
-
-.. code-block:: html
-
-  <form>
-    <fieldset>
-      <legend>First subset of fields: not message nor sender</legend>
-      
-      <div class="formItem required subject">
-        <label for="id_subject" class=" required">Subject</label>
-        <input id="id_subject" type="text" name="subject" maxlength="100" />
-      </div>
-      
-      <div class="formItem cc_myself">
-        <label for="id_cc_myself" class="">Cc myself</label>
-        <input type="checkbox" name="cc_myself" id="id_cc_myself" />
-        <p class="help">Send a copy of the message to the sender.</p>
-      </div>
-    </fieldset>
-
-    <fieldset>
-      <legend>Second subset of fields: sender then message (the order matters)</legend>
- 
-      <div class="formItem required sender">
-        <label for="id_sender" class=" required">Sender</label>
-        <input type="text" name="sender" id="id_sender" />
-      </div>
-
-      <div class="formItem required message">
-        <label for="id_message" class=" required">Message</label>
-        <input type="text" name="message" id="id_message" />
-      </div>
-    </fieldset>
-    
-    <input type="submit">
-  </form>

docs/examples/index.txt

-########
-Examples
-########
-
-A demonstration project is included in the Django-formrenderingtools
-sourcecode. It is the best way to discover code and results. It is also the
-easiest way to get a sandbox. See :doc:`/examples/demo` for details.
-
-.. toctree::
-   :maxdepth: 2
-
-   demo
-   form
-.. djc.formrenderingtools documentation master file, created by
+.. django-formrenderingtools documentation master file, created by
    sphinx-quickstart on Sat Apr 24 20:02:32 2010.
 
-######################################
-djc.formrenderingtools's documentation
-######################################
+#########################################
+django-formrenderingtools's documentation
+#########################################
 
-djc.formrenderingtools is an application for the `Django framework
+django-formrenderingtools is an application for the `Django framework
 <http://www.djangoproject.com/>`_.
-It provides tools for the template designer to customize forms: rather than 
-using {{ form.as_p }}, set up and reuse templates to render form elements.
+It provides tools for the template designer to customize forms.
 
-The goal of this application is to provide a pack of template tags which helps
-you render each element in a form: full form, list of fields, non field errors 
-(global errors), field errors (specific errors), field, label, help text...
-It is intended to be simple to learn and easy to extend. See :doc:`tutorial`
-for a quickstart.
+Rather than using {{ form.as_p }}, set up and reuse templates to render 
+Django's form elements.
 
-Every form element has a corresponding template tag, which uses templates to
-generate the output. Template designers no longer rely on developers to 
-customize the form output. See :doc:`overview` for more information about this 
-concept.
+For the impatient, jump to the :doc:`/demo` to discover and try the application
+in a sandbox.
 
-Currently this application provides a "form_layouts" template tag library 
-which itself provides the following template tags:
+Notice that Django-formrenderingtools is not intended to customize widgets.
+Have a look at `django-floppyforms
+<http://pypi.python.org/pypi/django-floppyforms>`_ for this purpose.
 
-* form: renders a full form, i.e. non field errors, all fields, field
-  errors, labels and help texts
-* form_errors: renders global form errors, i.e. non field errors
-* field_list: renders a set of fields in a form, with corresponding 
-  field errors, labels and help texts
-* field: renders a field, with field errors, label and help text
-* field_errors: renders errors related to a field
-* label: renders a field's label
-* help_text: renders a field's help text
+********
+Contents
+********
 
-For a deeper description of each template tag, see 
-:doc:`reference/template_tags`.
+.. toctree::
+   :maxdepth: 2
 
-This application uses a template-naming system that lets you reuse generic 
-templates or use specific ones, depending on your needs. You can reuse built-in 
-templates, override them or create your own templates. See
-:doc:`reference/template_names` for details.
+   overview
+   INSTALL
+   demo
+   reference/index
+   migrate
+   best_practices
+   contribute
+   LICENSE
+   AUTHORS
+   CHANGES
 
 *****
 Links
   <http://pypi.python.org/pypi/django-formrenderingtools>`_
   in the Python package index.
 
-
-********
-Contents
-********
-
-.. toctree::
-   :maxdepth: 2
-
-   overview
-   INSTALL
-   tutorial
-   reference/index
-   examples/index
-   contribute
-   migrate
-   best_practices
-   LICENSE
-   AUTHORS
-   CHANGES
-
 *******************
 Credits and license
 *******************
 Migrate from Django's builtins to djc.formrenderingtool
 #######################################################
 
-You tried djc.formrenderingtools and it fits your needs? How to safely migrate 
+django-formrenderingtools and it fits your needs? How to safely migrate 
 an existing project from standard Django's practices to formrenderingtools? 
 Here are some guidelines.
 
 * {{ form.as_ul }} by {% form layout="as_ul" %}
 * {{ form.as_table }} by {% form layout="as_table" %}
 
-***********************************************************
+************
+Experimental
+************
+
 Use Form subclass which overrides default rendering methods
-***********************************************************
+===========================================================
 
-Such a class is not yet included in djc.formrenderingtools. The idea is to 
+Such a class is not yet included in django-formrenderingtools. The idea is to 
 instantiate forms which inherit from "SomeFormRenderingToolsCompatibleForm" 
 base class which overrides default Form.__unicode__(), Form.as_table(), 
 Form.as_p() and Form.as_ul().

docs/overview.txt

 This Django application provides tools for the web designer to customize 
 the rendering of forms in templates.
 
-**************************************************
-The problem: rendering forms with Django is boring
-**************************************************
+*************************************
+Rendering forms with Django is boring
+*************************************
 
 For an introduction to Django forms, see the `Django documentation about forms 
 <http://docs.djangoproject.com/en/dev/ref/forms/>`_.
 * how to customize only a few fields in the form?
 
 If you are already aware of these problems, you can read about
-:ref:`the form_layouts template tag library <form_layouts_overview>` in the next 
-section.
+:ref:`the form_layouts template tag library <form_layouts_overview>` in the
+next section.
 
 Otherwise, let's begin by considering the following Django form:
 
   </p>
 
 Seems magic...
+
 HTML output is fully controlled by Python scripts. This is efficient, but the 
-template designer does not have control on it. This does not participate to 
+template designer does not have control on it. This does not contribute to 
 the separation between logic and design.
 
-Now, what if the template designer wants to add a "required" CSS class attribute 
-to the required fields in a form? He has to write code by hand.
+Now, what if the template designer wants to add a "required" CSS class
+attribute to the required fields in a form? He has to write code.
 As explained in the the `Django documentation about form templates
 <http://docs.djangoproject.com/en/dev/topics/forms/#customizing-the-form-template>`_,
 you can write a loop:
 
 Now what if the template designer want to customize only one field in the form?
 He has to write down the complete form. Here is an example where subject's
-help text is displayed before field, and message help text is displayed after
-field:
+help text is displayed before field, and message label is "Your message":
 
 .. code-block:: django
 
   <div class="fieldWrapper">
     {{ form.subject.errors }}
-    <label for="id_subject">E-mail subject:</label>
-    <p class="help">{{ form.subject.help_text }}</p>
+    {{ form.subject.label_tag }}:
+    <span class="helptext">{{ form.subject.help_text }}</p>
     {{ form.subject }}
   </div>
   <div class="fieldWrapper">
     {{ form.message.errors }}
     <label for="id_message">Your message:</label>
     {{ form.message }}
-    <p class="help">{{ form.message.help_text }}</p>
+    <span class="helptext">{{ form.message.help_text }}</p>
   </div>
   <div class="fieldWrapper">
     {{ form.sender.errors }}
-    <label for="id_sender">Your email address:</label>
+    {{ form.sender.label_tag }}:
     {{ form.sender }}
   </div>
   <div class="fieldWrapper">
     {{ form.cc_myself.errors }}
-    <label for="id_cc_myself">CC yourself?</label>
+    {{ form.cc_myself.label_tag }}:
     {{ form.cc_myself }}
   </div>
 
-And what if you want to customize many fields in many forms? Then it gets really
-boring, isn't it?
+And what if you want to customize many fields in many forms? Then it gets
+really boring, isn't it?
 
 The `Django documentation about reusable form templates
 <http://docs.djangoproject.com/en/dev/topics/forms/#reusable-form-templates>`_
   If you find yourself doing this often, you might consider creating a custom 
   inclusion tag.
 
-So, here comes djc.formrenderingtools.
+So, here comes django-formrenderingtools.
 This application uses templates to render forms, wherever it is possible.
 Default templates can be reused, and specific templates can be created if 
 necessary.
 .. _form_layouts_overview:
 
 ***************************************************
-A solution: the "form_layouts" template tag library
+Introducing the "form_layouts" template tag library
 ***************************************************
 
 Consider the form used in the previous section.
 
-Here is how you can use djc.formrenderingtools to display it:
+Here is how you can use django-formrenderingtools to display it:
 
 .. code-block:: django
 
   {% load form_layouts %}
-  {% form form=form %}
+  {% form %}
 
-Have a look at the templates in djc.formrenderingtools/templates/form_layouts/ and
-you will see what templates are used to render the form.
+Now, if you want to customize the "subject" field, create a
+"form_layouts/contact/fields/subject.html" template.
+Write "Hello world!" in this template.
 
-Now, if you want to customize the "subject" field, create a template called
-/form_layouts/contact/fields/subject.html.
-You may copy the default field template for this purpose:
-
-.. code-block:: bash
-  
-  $ cd /path/to/your/template/dir
-  $ mkdir form_layouts
-  $ mkdir form_layouts/contact
-  $ mkdir form_layouts/contact/fields
-  $ cp /path/to/djc.formrenderingtools/templates/form_layouts/default/fields/default.html form_layouts/contact/fields/subject.html
-
-Then you can edit the template and customize it as you want.
-
-By doing this, you have created a "contact" form layout (the directory name).
+By doing this, you have created a "contact" form layout (the directory name)
+and a custom template for the "subject" field.
 So the new template code is:
 
 .. code-block:: django
 
   {% load form_layouts %}
-  {% form form=form layout="contact" %}
+  {% form layout="contact" %}
 
-That's all.
+Refresh your page. You should see "Hello world!" instead of the subject field.
 
 Notice that the template name is important. If the template does not have
 the "good" name, then the template tag will not be able to find it.
+See :doc:`reference/template_names` for details.
 
-Have a look on the "djc.formrenderingtools/templates/form_layouts/default/"
+Have a look on the "djc/formrenderingtools/templates/form_layouts/default/"
 directory to get the default templates used by the "form_layouts" 
 template tags.
 
 
 You can reuse the "contact" form layout for other forms.
 
-You can override the default form layout so that it uses your own best
-practices.
+You can override the default form layout so that it fits your coding
+conventions.
 
-Learn more by reading the :doc:`/reference/index`, :doc:`/examples/index` or
-:doc:`best_practices` sections of this documentation.
+Learn more by reading the :doc:`/reference/index` or :doc:`/demo` sections of
+this documentation.
+
+********
+Concepts
+********
+
+The goal of this application is to provide a pack of template tags which helps
+you render each element in a form: full form, list of fields, non field errors 
+(global errors), field errors (specific errors), field, label, help text...
+It is intended to be simple to learn and easy to extend.
+
+Every form element has a corresponding template tag, which uses templates to
+generate the output. Template designers no longer rely on developers to 
+customize the form output.
+
+This application provides a "form_layouts" template tag library 
+which itself provides the following template tags:
+
+* form: renders a full form, i.e. non field errors, all fields, field
+  errors, labels and help texts
+* form_errors: renders global form errors, i.e. non field errors
+* field_list: renders a set of fields in a form, with corresponding 
+  field errors, labels and help texts
+* field: renders a field, with field errors, label and help text
+* field_errors: renders errors related to a field
+* label: renders a field's label
+* help_text: renders a field's help text
+
+For a deeper description of each template tag, see 
+:doc:`reference/template_tags`.
+
+This application uses a template-naming system that lets you reuse generic 
+templates or use specific ones, depending on your needs. You can reuse built-in 
+templates, override them or create your own templates. See
+:doc:`reference/template_names` for details.

docs/reference/css.txt

 Cascading style sheets
 ######################
 
-The djc.formrenderingtools application uses a set of default CSS classes.
+The django-formrenderingtools application uses a set of default CSS classes.
 So you may want to write a CSS stylesheet. Here is the list of classes 
 that are used.
 

docs/reference/settings.txt

 Settings
 ########
 
-The djc.formrenderingtools settings are prefixed with "FORMRENDERINGTOOLS\_".
+The django-formrenderingtools settings are prefixed with
+"FORMRENDERINGTOOLS\_".
 
 It is recommended not to change the following settings if you are aware of the
 "convention over configuration" practice.
 
-In fact, these settings were originally created for the developer convenience
+These settings were originally created for the developer convenience
 and to enable tests.
 
 *******************************
 
 .. code-block:: python
 
-  FORMRENDERINGTOOLS_DEFAULT_LAYOUT = 'default'
+  FORMRENDERINGTOOLS_DEFAULT_TEMPLATE = 'default.html'
 
 When you call a template tag without specifying the 
-optional "layout" argument, then it fallbacks to 
-settings.FORMRENDERINGTOOLS_DEFAULT_LAYOUT.
+optional "template" argument, then it fallbacks to 
+settings.FORMRENDERINGTOOLS_DEFAULT_TEMPLATE.

docs/reference/template_names.txt

   using {% form template="contact.html" %} will generate implicit calls with 
   default template, as {% field template="default.html" %}.
 
+********
+Priority
+********
+
+As an example, if you didn't change the default template and layout names,
+{% form layout='LAYOUT/DIR' template="TEMPLATE/NAME.html" %} will use the
+first existing template in the following list:
+
+* form_layouts/LAYOUT/DIR/form/TEMPLATE/NAME.html
+* form_layouts/default/form/TEMPLATE/NAME.html
+* form_layouts/LAYOUT/DIR/form/default.html
+* form_layouts/default/form/default.html
+
+Similar rules are used for other elements.
+
 ********************
 Additional variables
 ********************
   that the templates in your project/application have priority over the ones 
   provided by formrenderingtools.
 * settings.FORMRENDERINGTOOLS_TEMPLATE_DIR. A prefix for all templates used by
-  the djc.formrenderingtools application. It is not recommended to change it, 
-  because you should be able to perform the same thing by using one of the 
+  the django-formrenderingtools application. It is not recommended to change
+  it, because you should be able to perform the same thing by using one of the 
   previously described tip.

docs/reference/template_tags.txt

 Template tags
 #############
 
-djc.formrenderingtools provides the "form_layouts" template tag library, 
+django-formrenderingtools provides the "form_layouts" template tag library, 
 which itself provides the following template tags:
 
 * :ref:`form`: renders a full form, with all errors (field and non field 
   errors), fields and labels.
-* form_errors: renders global form errors, i.e. non field errors
-* field_list: renders a list of fields, with field errors, fields and 
+* :ref:`form_errors`: renders global form errors, i.e. non field errors
+* :ref:`field_list`: renders a list of fields, with field errors, fields and 
   labels. By default, uses {% field %}.
-* field: renders a field, with field errors and label. By default, uses 
+* :ref:`field`: renders a field, with field errors and label. By default, uses 
   {% label %}.
-* field_errors: renders errors related to a field
-* label: renders a field's label
-* help_text: renders a field's help text
-
-The template tags allow you to create customized templates for forms, fields or 
-labels. See the global recipe in <./tutorial.html>.
+* :ref:`field_errors`: renders errors related to a field
+* :ref:`label`: renders a field's label
+* :ref:`help_text`: renders a field's help text
 
 .. _form:
 
 Renders a full form, with all errors (field and non field errors), fields and 
 labels.
 
-By default, uses {% field_list %}.
+By default, uses :ref:`field_list`.
 
 Minimal usage
 =============
 * a context variable named "form" is required. You can use {% with %} for this
   purpose.
 * the default layout will be used
-* all fields in the form will be displayed, in the order specified in the form's 
-  python class definition.
+* all fields in the form will be displayed, in the order specified in the
+  form's python class definition.
 
 Usage with options
 ==================
 ================
 
 form
-   optional, a context variable, the form instance to be rendered.
-   If empty, the template tag searches for a context variable named "form".
+    optional, a context variable, the form instance to be rendered.
+    If empty, the template tag searches for a context variable named "form".
 
 layout
-   optional, defaults to settings.FORMRENDERINGTOOLS_DEFAULT_LAYOUT,
-   a context variable or a string, the layout to be used.
-   Through this parameter, you implicitely specify the template directory to 
-   use. See :doc:`/reference/template_names` for details.
+    optional, defaults to settings.FORMRENDERINGTOOLS_DEFAULT_LAYOUT ("default"
+    by default), a context variable or a string, the layout to be used.
+    Through this parameter, you implicitely specify the template directory to 
+    use. See :doc:`/reference/template_names` for details.
 
 fields
-	optional, defaults to None, a list or comma-separated string which 
-	represents the names of fields that you want to be displayed. Only those
-	fields will be displayed. If a field is in both "fields" and 
-	"exclude_fields", then it won't be displayed.
+    optional, defaults to None, a list or comma-separated (no spaces allowed)
+    string which represents the names of fields that you want to be displayed.
+    Only those fields will be displayed. If a field is in both "fields" and
+    "exclude_fields", then it won't be displayed.
 
 exclude_fields
     optional, defaults to None, a list or comma-separated string which 
 template
     optional, defaults to "default.html", a string, the template name to use.
     See :doc:`/reference/template_names` for details.
+
+.. _form_errors:
+
+***********
+form_errors
+***********
+
+Renders non field errors of a form.
+
+Input parameters are the same as the :ref:`form` template tag.
+
+.. _field_list:
+
+**********
+field_list
+**********
+
+Renders several fields.
+
+Input parameters are the same as the :ref:`form` template tag.
+
+.. _field:
+
+*****
+field
+*****
+
+Renders a field: errors, label, field and help_text.
+
+Notice that Django-formrenderingtools is not intended to customize widgets.
+Have a look at `django-floppyforms
+<http://pypi.python.org/pypi/django-floppyforms>`_ for this purpose.
+
+Input parameters
+================
+
+field
+   optional, a context variable, the field instance to be rendered.
+   If empty, the template tag searches for a context variable named "field".
+
+layout
+   optional, defaults to settings.FORMRENDERINGTOOLS_DEFAULT_LAYOUT ("default"
+   by default), a context variable or a string, the layout to be used.
+   Through this parameter, you implicitely specify the template directory to 
+   use. See :doc:`/reference/template_names` for details.
+
+template
+    optional, defaults to "default.html", a string, the template name to use.
+    See :doc:`/reference/template_names` for details.
+
+.. _field_errors:
+
+************
+field_errors
+************
+
+Renders the errors attached to a field.
+
+Input parameters are the same as the :ref:`field` template tag.
+
+.. _label:
+
+*****
+label
+*****
+
+Renders the label of a field.
+
+Input parameters are the same as the :ref:`field` template tag.
+
+.. _help_text:
+
+*********
+help_text
+*********
+
+Renders the help text of a field.
+
+Input parameters are the same as the :ref:`field` template tag.

docs/tutorial.txt

-########
-Tutorial
-########
-
-Here is a step-by-step recipe to start working with djc.formrenderingtools.
-
-*************
-Prerequisites
-*************
-
-* You have a Django project
-* You have installed the djc.formrenderingtools application in your project.
-  See :doc:`install`.
-
-If you already have a Django project with at least one view that renders a form
-via a template, then you may jump to the "Template code" section below.
-
-**************************
-Python code: create a form
-**************************
-
-In Python code, do as always: create a form class, use it in a view and pass 
-it to a template as a template context variable.
-
-A form
-======
-
-In the examples below, we will use the following form class:
-
-.. code-block:: python
-
-  from django import forms
-  
-  class ContactForm(forms.Form):
-      """
-      A sample form, for use in test cases.
-      """
-      subject = forms.CharField(
-          label='Subject',
-          max_length=100,
-      )
-      message = forms.CharField()
-      sender = forms.EmailField()
-      cc_myself = forms.BooleanField(
-          required=False,
-          help_text='Send a copy of the message to the sender.',
-      )
-    
-      def clean(self):
-          """This sample form never validates!"""
-          raise forms.ValidationError('Sorry, but this sample form never validates!')
-
-This is a quite simple form. If you call is_valid(), then a "non field error"
-is always generated.
-
-A view
-======
-
-In the examples below, we suppose you use the form in a view that looks like 
-the following:
-
-.. code-block:: python
-
-  from django.shortcuts import render_to_response
-  from django.template import RequestContext
-
-  def my_view(request):
-  	  if not request.method == 'POST':
-	  	  form = ContactForm()
-	  else:
-	      form = ContactForm(request.POST)
-      template_data = {'my_form': form}
-      render_to_response('my_template.html',
-      					 template_data,
-      					 context_instance=RequestContext(request))
-
-Do not forget to add the view in your URL conf.
-
-*************
-Template code
-*************
-
-You can test your view and template by rendering the form the old way.
-
-Here is what you may used to write in my_template.html:
-
-.. code-block:: django
-
-  <form action="./" method="post">
-    {{ form.as_p }}
-    <input type="submit">
-  </form>
-
-Here is the code required to start using djc.formrenderingtools, so replace
-the previous template code by the following:
-
-.. code-block:: django
-
-  {% load form_layouts %}
-  <form action="./" method="post">
-    {% form form=my_form layout="as_p" %}
-    <input type="submit">
-  </form>
-
-What does {% form form=my_form layout="as_p" %} mean? It means:
-
-* use the form_layouts library to render a form;
-* the form I want to render is named "my_form" in the context;
-* use the "as_p" layout.
-
-Save the template, refresh the page. For now nothing changed.
-Why? Mainly because the layout named "as_p" has been created as an exact 
-replacement of the Django's builtin {{ form.as_p }}. In fact, "as_p", "as_ul"
-and "as_table" layouts provide safe transitional layouts.
-
-******************
-To be continued...
-******************
-
-Unfortunately this tutorial is not complete yet.
-
-However, here are some additional notes:
-
-* in Python code, do as always: create a form class, use it in a view and pass 
-  it to a template as a template context variable
-* load the "form_layouts" template tag library in your template with
-  {% load form_layouts %}
-* insert your form in template with {% form form=your_form_variable %}
-  instead of using {{ your_form_variable.as_p }}
-* you can test the output and customize CSS. The default layout covers the
-  general case.
-* if you want more customization, use the "layout" parameter:
-  {% form form=your_form_variable layout="your_layout" %}
-* copy the default form layout folder (defaults to 
-  /djc.formrenderingtools/templates/form_layouts/default) to a folder of yours and 
-  rename it "your_layout". You get something like 
-  "/your_project_template_dir/templates/form_layouts/your_layout" which 
-  contains a   form.html file, a "fields" folder and a "labels" folder.
-* customize the templates in the "your_layout" folder
-* if you want to customize the layout of a particular field called "your_field",
-  then create a specific "/your_layout/fields/your_field.html" template.
-  You can do the same thing with a label.
 setup(
     name='djc.formrenderingtools',
     version='0.2',
-    url='http://bitbucket.org/benoitbryon/djc.formrenderingtools',
-    download_url='http://bitbucket.org/benoitbryon/djc.formrenderingtools/downloads',
+    url='http://bitbucket.org/benoitbryon/django-formrenderingtools',
+    download_url='http://bitbucket.org/benoitbryon/django-formrenderingtools/downloads',
     author='Benoit Bryon',
     author_email='benoit@marmelune.net',
     license='BSD',
-    description="Rather than using {{ form.as_p }}, set up and reuse " \
-                "templates to render Django's form elements.",
+    description="Template-based rendering of Django forms (excluding widgets).",
     long_description=read_relative_file('README.txt'),
     platforms='Any',
     classifiers = [
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.