Fixed #16597 -- Added Sphinx cross-reference metadata to the form wizard docs. Thanks FunkyBob for the report and jkistler for the patch.
Also, additional fixes in that document and in the WizardView docstrings. git-svn-id: http://code.djangoproject.com/svn/django/trunk@16904 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
parent
3ef1762cb9
commit
735fbcfe8b
|
@ -124,7 +124,7 @@ class WizardView(TemplateView):
|
|||
The key should be equal to the `step_name` in the `form_list` (or
|
||||
the str of the zero based counter - if no step_names added in the
|
||||
`form_list`)
|
||||
* `instance_dict` - contains a dictionary of instance objects. This list
|
||||
* `instance_dict` - contains a dictionary of instance objects. This
|
||||
is only used when `ModelForm`s are used. The key should be equal to
|
||||
the `step_name` in the `form_list`. Same rules as for `initial_dict`
|
||||
apply.
|
||||
|
@ -286,7 +286,7 @@ class WizardView(TemplateView):
|
|||
|
||||
def render_next_step(self, form, **kwargs):
|
||||
"""
|
||||
THis method gets called when the next step/form should be rendered.
|
||||
This method gets called when the next step/form should be rendered.
|
||||
`form` contains the last/current form.
|
||||
"""
|
||||
# get the form instance based on the data from the storage backend
|
||||
|
@ -349,14 +349,14 @@ class WizardView(TemplateView):
|
|||
"""
|
||||
Returns a object which will be passed to the form for `step`
|
||||
as `instance`. If no instance object was provied while initializing
|
||||
the form wizard, None be returned.
|
||||
the form wizard, None will be returned.
|
||||
"""
|
||||
return self.instance_dict.get(step, None)
|
||||
|
||||
def get_form_kwargs(self, step=None):
|
||||
"""
|
||||
Returns the keyword arguments for instantiating the form
|
||||
(or formset) on given step.
|
||||
(or formset) on the given step.
|
||||
"""
|
||||
return {}
|
||||
|
||||
|
@ -404,7 +404,7 @@ class WizardView(TemplateView):
|
|||
def render_revalidation_failure(self, step, form, **kwargs):
|
||||
"""
|
||||
Gets called when a form doesn't validate when rendering the done
|
||||
view. By default, it changed the current step to failing forms step
|
||||
view. By default, it changes the current step to failing forms step
|
||||
and renders the form.
|
||||
"""
|
||||
self.storage.current_step = step
|
||||
|
@ -428,7 +428,7 @@ class WizardView(TemplateView):
|
|||
"""
|
||||
Returns a merged dictionary of all step cleaned_data dictionaries.
|
||||
If a step contains a `FormSet`, the key will be prefixed with formset
|
||||
and contain a list of the formset' cleaned_data dictionaries.
|
||||
and contain a list of the formset cleaned_data dictionaries.
|
||||
"""
|
||||
cleaned_data = {}
|
||||
for form_key in self.get_form_list():
|
||||
|
@ -532,7 +532,7 @@ class WizardView(TemplateView):
|
|||
|
||||
def render(self, form=None, **kwargs):
|
||||
"""
|
||||
Returns a ``HttpResponse`` containing a all needed context data.
|
||||
Returns a ``HttpResponse`` containing all needed context data.
|
||||
"""
|
||||
form = form or self.get_form()
|
||||
context = self.get_context_data(form, **kwargs)
|
||||
|
@ -540,7 +540,7 @@ class WizardView(TemplateView):
|
|||
|
||||
def done(self, form_list, **kwargs):
|
||||
"""
|
||||
This method muss be overrided by a subclass to process to form data
|
||||
This method must be overridden by a subclass to process to form data
|
||||
after processing all steps.
|
||||
"""
|
||||
raise NotImplementedError("Your %s class has not defined a done() "
|
||||
|
|
|
@ -90,9 +90,11 @@ Creating a ``WizardView`` class
|
|||
-------------------------------
|
||||
|
||||
The next step is to create a
|
||||
:class:`django.contrib.formtools.wizard.view.WizardView` subclass. You can
|
||||
also use the :class:`SessionWizardView` or :class:`CookieWizardView` class
|
||||
which preselects the wizard storage backend.
|
||||
:class:`django.contrib.formtools.wizard.views.WizardView` subclass. You can
|
||||
also use the :class:`SessionWizardView` or :class:`CookieWizardView` classes
|
||||
which preselect the backend used for storing information during execution of the
|
||||
wizard (as their names indicate, server-side sessions and browser cookies
|
||||
respectively).
|
||||
|
||||
.. note::
|
||||
|
||||
|
@ -148,7 +150,8 @@ Next, you'll need to create a template that renders the wizard's forms. By
|
|||
default, every form uses a template called
|
||||
:file:`formtools/wizard/wizard_form.html`. You can change this template name
|
||||
by overriding either the :attr:`~WizardView.template_name` attribute or the
|
||||
:meth:`~WizardView.get_template_names()` method, which is documented below.
|
||||
:meth:`~WizardView.get_template_names()` method, which is documented in the
|
||||
:class:`~django.views.generic.base.TemplateResponseMixin` documentation.
|
||||
This hook also allows you to use a different template for each form.
|
||||
|
||||
This template expects a ``wizard`` object that has various items attached to
|
||||
|
@ -171,7 +174,7 @@ it:
|
|||
* ``all`` -- A list of all steps of the wizard.
|
||||
|
||||
You can supply additional context variables by using the
|
||||
:meth:`~FormWizard.get_context_data` method of your :class:`FormWizard`
|
||||
:meth:`~WizardView.get_context_data` method of your :class:`WizardView`
|
||||
subclass.
|
||||
|
||||
Here's a full example template:
|
||||
|
@ -213,7 +216,7 @@ Hooking the wizard into a URLconf
|
|||
---------------------------------
|
||||
|
||||
Finally, we need to specify which forms to use in the wizard, and then
|
||||
deploy the new :class:`WizardView` object a URL in the ``urls.py``. The
|
||||
deploy the new :class:`WizardView` object at an URL in the ``urls.py``. The
|
||||
wizard's :meth:`as_view` method takes a list of your
|
||||
:class:`~django.forms.Form` classes as an argument during instantiation::
|
||||
|
||||
|
@ -262,9 +265,10 @@ Advanced ``WizardView`` methods
|
|||
|
||||
.. method:: WizardView.get_form_initial(step)
|
||||
|
||||
Returns a dictionary which will be passed to the form for ``step`` as
|
||||
``initial``. If no initial data was provided while initializing the
|
||||
form wizard, an empty dictionary should be returned.
|
||||
Returns a dictionary which will be passed as the
|
||||
:attr:`~django.forms.Form.initial` argument when instantiating the Form
|
||||
instance for step ``step``. If no initial data was provided while
|
||||
initializing the form wizard, an empty dictionary should be returned.
|
||||
|
||||
The default implementation::
|
||||
|
||||
|
@ -283,9 +287,13 @@ Advanced ``WizardView`` methods
|
|||
|
||||
.. method:: WizardView.get_form_instance(step)
|
||||
|
||||
Returns an object which will be passed to the form for ``step`` as
|
||||
``instance``. If no instance object was provided while initializing
|
||||
the form wizard, None be returned.
|
||||
This method will be called only if a :class:`~django.forms.ModelForm` is
|
||||
used as the form for step ``step``.
|
||||
|
||||
Returns an :class:`~django.db.models.Model` object which will be passed as
|
||||
the :attr:`~django.forms.ModelForm.instance` argument when instantiating the
|
||||
ModelForm for step ``step``. If no instance object was provided while
|
||||
initializing the form wizard, ``None`` will be returned.
|
||||
|
||||
The default implementation::
|
||||
|
||||
|
@ -358,9 +366,9 @@ Advanced ``WizardView`` methods
|
|||
.. method:: WizardView.process_step(form)
|
||||
|
||||
This method gives you a way to post-process the form data before the data
|
||||
gets stored within the storage backend. By default it just passed the
|
||||
form.data dictionary. You should not manipulate the data here but you can
|
||||
use the data to do some extra work if needed (e.g. set storage extra data).
|
||||
gets stored within the storage backend. By default it just returns the
|
||||
``form.data`` dictionary. You should not manipulate the data here but you
|
||||
can use it to do some extra work if needed (e.g. set storage extra data).
|
||||
|
||||
Default implementation::
|
||||
|
||||
|
@ -370,9 +378,9 @@ Advanced ``WizardView`` methods
|
|||
.. method:: WizardView.process_step_files(form)
|
||||
|
||||
This method gives you a way to post-process the form files before the
|
||||
files gets stored within the storage backend. By default it just passed
|
||||
files gets stored within the storage backend. By default it just returns
|
||||
the ``form.files`` dictionary. You should not manipulate the data here
|
||||
but you can use the data to do some extra work if needed (e.g. set storage
|
||||
but you can use it to do some extra work if needed (e.g. set storage
|
||||
extra data).
|
||||
|
||||
Default implementation::
|
||||
|
@ -382,8 +390,8 @@ Advanced ``WizardView`` methods
|
|||
|
||||
.. method:: WizardView.render_revalidation_failure(step, form, **kwargs)
|
||||
|
||||
When the wizard thinks, all steps passed it revalidates all forms with the
|
||||
data from the backend storage.
|
||||
When the wizard thinks all steps have passed it revalidates all forms with
|
||||
the data from the backend storage.
|
||||
|
||||
If any of the forms don't validate correctly, this method gets called.
|
||||
This method expects two arguments, ``step`` and ``form``.
|
||||
|
@ -399,9 +407,9 @@ Advanced ``WizardView`` methods
|
|||
|
||||
.. method:: WizardView.get_form_step_data(form)
|
||||
|
||||
This method fetches the form data from and returns the dictionary. You
|
||||
can use this method to manipulate the values before the data gets stored
|
||||
in the storage backend.
|
||||
This method fetches the data from the ``form`` Form instance and returns the
|
||||
dictionary. You can use this method to manipulate the values before the data
|
||||
gets stored in the storage backend.
|
||||
|
||||
Default implementation::
|
||||
|
||||
|
@ -420,8 +428,8 @@ Advanced ``WizardView`` methods
|
|||
|
||||
.. method:: WizardView.render(form, **kwargs)
|
||||
|
||||
This method gets called after the get or post request was handled. You can
|
||||
hook in this method to, e.g. change the type of http response.
|
||||
This method gets called after the GET or POST request has been handled. You
|
||||
can hook in this method to, e.g. change the type of HTTP response.
|
||||
|
||||
Default implementation::
|
||||
|
||||
|
@ -467,7 +475,7 @@ Handling files
|
|||
To handle :class:`~django.forms.FileField` within any step form of the wizard,
|
||||
you have to add a :attr:`file_storage` to your :class:`WizardView` subclass.
|
||||
|
||||
This storage will temporarilyy store the uploaded files for the wizard. The
|
||||
This storage will temporarily store the uploaded files for the wizard. The
|
||||
:attr:`file_storage` attribute should be a
|
||||
:class:`~django.core.files.storage.Storage` subclass.
|
||||
|
||||
|
@ -482,9 +490,9 @@ Conditionally view/skip specific steps
|
|||
|
||||
.. attribute:: WizardView.condition_dict
|
||||
|
||||
The :meth:`~WizardView.as_view` accepts a ``condition_dict`` argument. You can pass a
|
||||
dictionary of boolean values or callables. The key should match the steps
|
||||
name (e.g. '0', '1').
|
||||
The :meth:`~WizardView.as_view` method accepts a ``condition_dict`` argument.
|
||||
You can pass a dictionary of boolean values or callables. The key should match
|
||||
the steps names (e.g. '0', '1').
|
||||
|
||||
If the value of a specific step is callable it will be called with the
|
||||
:class:`WizardView` instance as the only argument. If the return value is true,
|
||||
|
@ -493,7 +501,7 @@ the step's form will be used.
|
|||
This example provides a contact form including a condition. The condition is
|
||||
used to show a message form only if a checkbox in the first step was checked.
|
||||
|
||||
The steps are defined in a ``forms.py``::
|
||||
The steps are defined in a ``forms.py`` file::
|
||||
|
||||
from django import forms
|
||||
|
||||
|
@ -546,10 +554,14 @@ As you can see, we defined a ``show_message_form_condition`` next to our
|
|||
How to work with ModelForm and ModelFormSet
|
||||
===========================================
|
||||
|
||||
The WizardView supports :class:`~django.forms.ModelForm` and
|
||||
:class:`~django.forms.ModelFormSet`. Additionally to the ``initial_dict``,
|
||||
the :meth:`~WizardView.as_view` method takes a ``instance_dict`` argument
|
||||
with a list of instances for the ``ModelForm`` and ``ModelFormSet``.
|
||||
.. attribute:: WizardView.instance_dict
|
||||
|
||||
WizardView supports :class:`~django.forms.ModelForm` and
|
||||
:class:`~django.forms.ModelFormSet`. Additionally to the ``initial_dict``, the
|
||||
:meth:`~WizardView.as_view` method takes a ``instance_dict`` argument that
|
||||
should contain instances of ``ModelForm`` and ``ModelFormSet``. Similarly to
|
||||
:attr:`~WizardView.initial_dict`, thos dictionary key values should be equal to
|
||||
the `step_name` in the `form_list`.
|
||||
|
||||
Usage of NamedUrlWizardView
|
||||
===========================
|
||||
|
|
Loading…
Reference in New Issue