More information about retail rendering.

docs/retail.rst

@@ -3,6 +3,11 @@
Retail Form Rendering
=====================

.. contents:: :local:

Introduction
------------

In the previous chapter we demonstrated how to use Deform to render a complete
form, including the input fields, the buttons, and so forth.  We used the
:meth:`deform.Field.render()` method, and injected the resulting HTML snippet
@@ -15,9 +20,12 @@ Deform forms.  Often it's easier to use Deform slightly differently, where you
do more work yourself to draw the form within a template, and only use Deform
for some of its features.  We refer to this as "retail form rendering".

.. note::
Live example
------------

`See pop-up example on Deform demo site <http://deformdemo.repoze.org/popup/>`_.

   This feature is new as of Deform 0.9.6.
`Source code <https://github.com/Pylons/deformdemo/blob/master/deformdemo/__init__.py>`_ (search popup).

A Basic Example
---------------

docs/templates.rst

@@ -3,10 +3,37 @@
Templates
=========

.. contents:: :local:

Introduction
------------

A set of :term:`Chameleon` templates is used by the default widget set
present in :mod:`deform` to make it easier to customize the look and
feel of form renderings.

Alternative template engines
----------------------------

Deform is compatible with any template engine.

Even though Deform widgets themselves are rendered in Chameleon, you can place the forms on pages in any template language. For example, `Websauna <https://websauna.org>`_ places Deform forms inside Jinja 2 page templates.

The rendered forms are simply Python strings.

Adding more widget templates
----------------------------

If your application is supplying it own templates for Deform forms, you need to add those template paths to Chameleon lookup. Chameleon template paths are stored in a in-process global variable.

.. code-block:: python

   from deform.renderer import configure_zpt_renderer

   # Make Deform widgets aware of our widget template paths
   configure_zpt_renderer(["websauna.system.form:templates/deform"])


Overriding the default templates
--------------------------------