(You can read this RFC online if you prefer:
https://github.com/gregmuellegger/gsoc2011-stuff/blob/master/rfc_syntax.rst )
Hi,
like you might know I've prepared as pre-work to my GSoC project a repository
[1] with examples for two different approaches to my upcoming work on the form
rendering. The first approach is called "single_tag" [2] the second one
"modifier_tags" [3]. I agreed with my mentor Carl that we will follow a
"hybrid" style of both proposals [4].
I tried here to summarize a bit how the new tags will look like. I call now
for comments and will really appreciate any feedback on them. Being it about
their naming or if you have ideas for other tags. Be picky, this is something
lots of people will use -- and though we want it to be as easy as possible to
get started with.
::
{% renderform <form instance> [<field name> ...] [hidden <field
name> ...] [exclude <field name> ...] %}
The renderform tag renders the complete form::
{% renderform my_form %}
You can influence which fields will be used, sparing some fields out
if you want that. Examples::
{% renderform my_form "username" "password" %}
Renders only my_form.username and my_form.password and ignoring all other
fields on the form. ::
{% renderform my_form exclude "first_name" "last_name" %}
Render all fields but my_form.first_name and my_form.last_name. ::
{% renderform my_form hidden "honeypot" %}
Render all fields but outputs the my_form.honeypot field as a hidden field.
Thats it in what the renderform takes on arguments. You can influence it's
rendering behaviour in more detail by using *form modifier tags*.
One such modifier tag is the formlayout tag::
{% formlayout <layout name> %}
Every {% renderform %} that is following in the templates will use the
specified layout for rendering. We will provide layouts called "table", "ul"
and "p". Users can specify new layouts just by putting some templates in the
right template path.
The {% form %} tag is limiting the scope of these modifier tags. If a modifier
tag is wrapped in such a form-block, then it will lose its influence on form
rendering outside of the form tag. ::
{% form %}
{% formlayout "table" %}
{% renderform my_form %} {# will use table layout #}
{% endform %}
{% renderform my_form %} {# will use default layout #}
The description of the form tag implies that the modifier tags are able to
set/modify the global state in the current template. That is something that is
explicitly wanted. This way you can set a "formlayout" in the head of your
base template and any other extending template will have this default for the
form rendering.
Another tag to modify the rendering is the widget tag::
{% widget [<widget class or instance>] [using <template name>] for
<field type> [with <varname>=<varvalue> ...] %}
In this syntax description <field type> means that you can specify one of
three things as argument:
1. A bound field, means that the widget will be rendered only for this field.
2. A field class/type that will match for all fields that are using this
formfield class. Example::
{% widget widgets.PasswordInput for formfields.CharField %}
will render a <input type="password" /> for all charfields.
3. A field name (string). This will apply to all fields that have that
particular field name. It's only useful if the option should apply to more
than one form or as convenience for short reference of a field.
Some examples::
{% widget widgets.Textarea for my_form.comment %} (1. case)
{% widget widgets.DatePicker for formfields.DateField %} (2. case)
{% widget widgets.PasswordInput for "password" %} (3. case)
You can also change the template that will be used to render the widget with
the using keyword (we assume at this point that until this GSoC project is
finished we will likely have template based widget rendering like currently
developed by Bruno [5]), an example::
{% widget using "my_textarea_widget.html" for my_form.comment %}
It's actually possible to specify a special template for the widget *and* to
change the widget class itself with the tag::
{% widget widgets.DatePicker using
"widgets/alternative_datepicker.html" for my_form.birthday %}
The "with varname=varvalue" bit in the widget tag is meant as possibility to
pass extra arguments into the template that will be used to render the widget.
This will use the same syntax as django's ``include`` tag [6]::
{% widget for my_form.text with rows=10 cols=20 %}
{% widget using "widgets/tinymce.html" for my_form.comment with
theme="advanced" %}
At the end a short word to the meanings of widgets.Textarea etc. This
will basically be a template variable referencing the Textarea widget. So we
don't use special syntax for this in the tag, we just pull out the "widgets"
template variable that will be passed in via a context processor.
The "widgets" and "formfields" variables will be modifiable by users, so that
they can register their own widgets in their reusable apps, then usable in all
templates.
Thanks if you have read so far. Now please start commenting :-)
Gregor
| [1] https://github.com/gregmuellegger/django-form-rendering-api
| [2]
https://github.com/gregmuellegger/django-form-rendering-api/blob/master/formapi/templates/api_samples/single_tag.html
| [3]
https://github.com/gregmuellegger/django-form-rendering-api/blob/master/formapi/templates/api_samples/modifier_tags.html
| [4]
https://github.com/gregmuellegger/django-form-rendering-api/blob/master/formapi/templates/api_samples/hybrid.html
| [5] http://code.djangoproject.com/ticket/15667
| [6]
http://docs.djangoproject.com/en/dev/ref/templates/builtins/#std:templatetag-include
--
You received this message because you are subscribed to the Google Groups
"Django developers" group.
To post to this group, send email to django-developers@googlegroups.com.
To unsubscribe from this group, send email to
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/django-developers?hl=en.
