Ticket #9200: wizard_patch.txt

File wizard_patch.txt, 16.7 KB (added by David Durham, 17 years ago)
Line 
1Index: /home/david/work/django/django-trunk/django/contrib/formtools/wizard.py
2===================================================================
3--- /home/david/work/django/django-trunk/django/contrib/formtools/wizard.py (revision 9084)
4+++ /home/david/work/django/django-trunk/django/contrib/formtools/wizard.py (working copy)
5@@ -1,21 +1,22 @@
6-"""
7-FormWizard class -- implements a multi-page form, validating between each
8-step and storing the form's state as HTML hidden fields so that no state is
9-stored on the server side.
10-"""
11-
12 import cPickle as pickle
13
14 from django import forms
15 from django.conf import settings
16 from django.http import Http404
17+from django.http import HttpResponseRedirect
18 from django.shortcuts import render_to_response
19 from django.template.context import RequestContext
20 from django.utils.hashcompat import md5_constructor
21 from django.utils.translation import ugettext_lazy as _
22 from django.contrib.formtools.utils import security_hash
23
24+
25 class FormWizard(object):
26+ """
27+ FormWizard class -- implements a multi-page form, validating between each
28+ step and storing the form's state as HTML hidden fields so that no state is
29+ stored on the server side.
30+ """
31 # Dictionary of extra template context variables.
32 extra_context = {}
33
34@@ -239,3 +240,399 @@
35 data.
36 """
37 raise NotImplementedError("Your %s class has not defined a done() method, which is required." % self.__class__.__name__)
38+
39+
40+class SessionWizard(object):
41+ """
42+ SessionWizard class -- implements multi-page forms with the following
43+ characteristics:
44+
45+ 1) easily supports navigation to arbitrary pages in the wizard
46+ 2) uses GETs to display forms (caveat validation errors) and POSTs for
47+ form submissions
48+
49+ Pros are support for back-button and arbitrary navigation within pages
50+ (including the oddity of someone clicking on the refresh button)
51+
52+ The major Con is use of the session scope. In particular, zero
53+ consideration has been given to multipart form data.
54+ """
55+
56+ # keys used to store wizard data in sessions
57+ __form_list_key = 'form_list'
58+ __cleaned_data_key = 'cleaned_data'
59+ __POST_data_key = 'POST_data'
60+ __page_infos_key = 'page_infos'
61+
62+ def __init__(self, form_list):
63+ """form_list should be a list of Form classes (not instances)."""
64+ self.base_form_list = form_list[:]
65+
66+ def _init_form_list(self, request):
67+ """
68+ Copy self.base_form_list to the session scope so that subclasses can
69+ manipulate the form_list for individual users.
70+ """
71+ session_key = self.get_wizard_data_key(request)
72+ if session_key not in request.session:
73+ request.session[session_key] = {
74+ self.__form_list_key : self.base_form_list[:],
75+ self.__cleaned_data_key : [],
76+ self.__POST_data_key : [],
77+ self.__page_infos_key : [],
78+ }
79+
80+ def __call__(self, request, *args, **kwargs):
81+ """
82+ Initialize the form_list for a session if needed and call GET or
83+ POST depending on the http method.
84+ """
85+ self._init_form_list(request)
86+ page0 = int(kwargs['page0'])
87+
88+ if request.method == 'POST':
89+ return self.POST(request)
90+ else:
91+ return self.GET(request, page0)
92+
93+
94+ def GET(self, request, page0):
95+ """
96+ Display the form/page for the page identified by page0
97+ """
98+ page_data = self._get_cleaned_data(request.session, page0)
99+ if page_data is None:
100+ form = self._get_form_list(request.session)[page0]()
101+ else:
102+ form_class = self._get_form_list(request.session)[page0]
103+ if issubclass(form_class, forms.ModelForm):
104+ form = form_class(instance=form_class.Meta.model(**page_data))
105+ else:
106+ form = form_class(initial=page_data)
107+ return self._show_form(request, page0, form)
108+
109+ def POST(self, request):
110+ """
111+ Validate form submission, and redirect to GET the next form or return
112+ the response from self.done().
113+ """
114+ page0 = int(request.POST['page0'])
115+ url_base = self.get_URL_base(request, page0)
116+ self._set_POST_data(request.session, request.POST, page0)
117+ form_list = self._get_form_list(request.session)
118+ form = form_list[page0](request.POST)
119+ new_page0 = self.preprocess_submit_form(request, page0, form)
120+
121+ if new_page0 is not None:
122+ return HttpResponseRedirect(url_base + str(new_page0))
123+ else:
124+ if form.is_valid():
125+ self._set_cleaned_data(request.session, page0,
126+ form.cleaned_data)
127+ self._set_page_info(request.session, page0, True)
128+ is_done = self.process_submit_form(request, page0, form)
129+ if (is_done is None or is_done == False) and \
130+ len(form_list) > page0 + 1:
131+ return HttpResponseRedirect(url_base + str(page0 + 1))
132+ else:
133+ first_broken_page, form = \
134+ self._validate_all_forms(request.session)
135+ if first_broken_page is not None:
136+ return self._show_form(request, first_broken_page,
137+ form)
138+ else:
139+ return self.done(request)
140+ else:
141+ self._set_page_info(request.session, page0, False)
142+
143+ return self._show_form(request, page0, form)
144+
145+
146+ # form util methods #
147+ def _validate_all_forms(self, session):
148+ """
149+ Iterate through the session form list and validate based on the POST
150+ data stored in the session for this wizard. Return the page index and
151+ the form of the first invalid form or None, None if all forms are valid.
152+ """
153+ i = 0
154+ for form_class in self._get_form_list(session):
155+ form = form_class(self._get_POST_data(session, i))
156+ if not form.is_valid():
157+ return i, form
158+ else:
159+ i = i + 1
160+ return None, None
161+
162+ def _show_form(self, request, page0, form):
163+ """
164+ Show the form associated with indicated page index.
165+ """
166+ url_base = self.get_URL_base(request, page0)
167+ extra_context = self.process_show_form(request, page0, form)
168+ self._set_current_page(request.session, page0)
169+ page_infos = self._get_page_infos(request.session)
170+ return render_to_response(self.get_template(page0),
171+ {'page0' : page0,
172+ 'page' : page0 + 1,
173+ 'form' : form,
174+ 'page_infos' : page_infos,
175+ 'url_base' : url_base,
176+ 'extra_context' : extra_context
177+ }, RequestContext(request))
178+
179+ def _get_form_list(self, session):
180+ """
181+ Return the list of form classes stored in the provided session.
182+ """
183+ return session[self.get_wizard_data_key(session)][self.__form_list_key]
184+
185+ def _insert_form(self, session, page0, form_class):
186+ """
187+ Insert a form class into the provided session's form list at index
188+ page0.
189+ """
190+ form_list = self._get_form_list(session)
191+ form_list.insert(page0, form_class)
192+ self._insert_wizard_data(session, self.__form_list_key, form_list)
193+
194+ def _remove_form(self, session, page0):
195+ """
196+ Remove the form at index page0 from the provided sessions form list.
197+ """
198+ self._del_wizard_data(session, self.__form_list_key, page0)
199+ # end form util methods #
200+
201+
202+ # Form data methods #
203+ def _get_POST_data(self, session, page0):
204+ """
205+ Return the POST data for a given page index page0, stored in the
206+ provided session.
207+ """
208+ post_data = self._get_all_POST_data(session)
209+ if len(post_data) > page0:
210+ return post_data[page0]
211+ else:
212+ return {}
213+
214+ def _set_POST_data(self, session, data, page0, force_insert=False):
215+ """
216+ Set the POST data for a given page index and session to the 'data'
217+ provided. If force_insert is True then the data assignment is forced
218+ as an list.insert(page0, data) call.
219+ """
220+ post_data = self._get_all_POST_data(session)
221+ if force_insert or len(post_data) <= page0:
222+ post_data.insert(page0, data)
223+ else:
224+ post_data[page0] = data
225+ self._insert_wizard_data(session, self.__POST_data_key, post_data)
226+
227+ def _remove_POST_data(self, session, page0):
228+ """
229+ Remove the POST data stored in the session at index page0.
230+ """
231+ self._del_wizard_data(session, self.__POST_data_key, page0)
232+
233+ def _get_all_POST_data(self, session):
234+ """
235+ Return the list of all POST data for this wizard from the provided
236+ session.
237+ """
238+ return session[self.get_wizard_data_key(session)][self.__POST_data_key]
239+
240+ def _get_cleaned_data(self, session, page0):
241+ """
242+ Return all cleaned data for this wizard from the provided session.
243+ """
244+ cleaned_data = self._get_all_cleaned_data(session)
245+ if len(cleaned_data) > page0:
246+ return cleaned_data[page0]
247+ else:
248+ return {}
249+
250+ def _set_cleaned_data(self, session, page0, data, force_insert=False):
251+ """
252+ Assign the cleaned data for this wizard in the session at index page0,
253+ optionally forcing a call a list insert call based on the
254+ 'force_insert' argument.
255+ """
256+ cleaned_data = self._get_all_cleaned_data(session)
257+ if force_insert or len(cleaned_data) <= page0:
258+ cleaned_data.insert(page0, data)
259+ else:
260+ cleaned_data[page0] = data
261+ self._insert_wizard_data(session, self.__cleaned_data_key, cleaned_data)
262+
263+
264+ def _get_all_cleaned_data(self, session):
265+ """
266+ Return a list of all the cleaned data in the session for this wizard.
267+ """
268+ wizard_data = session[self.get_wizard_data_key(session)]
269+ return wizard_data[self.__cleaned_data_key]
270+
271+ def _remove_cleaned_data(self, session, page0):
272+ """
273+ Remove the cleaned data at index page0 for this wizard from the
274+ provided session.
275+ """
276+ self._del_wizard_data(session, self.__cleaned_data_key, page0)
277+ # end Form data methods #
278+
279+
280+ # page methods #
281+ def _set_current_page(self, session, page0):
282+ """
283+ Iterate through the page info dicts in the session and set
284+ 'current_page' to True for the page_info corresponding to page0 and
285+ False for all others.
286+ """
287+ page_infos = self._get_page_infos(session)
288+ for i in range(len(page_infos)):
289+ if i == page0:
290+ page_infos[i]['current_page'] = True
291+ else:
292+ page_infos[i]['current_page'] = False
293+
294+ def _get_page_infos(self, session):
295+ """
296+ Return the list of page info dicts stored in the provided session for
297+ this wizard.
298+ """
299+ return session[self.get_wizard_data_key(session)][self.__page_infos_key]
300+
301+ def _remove_page(self, session, page0):
302+ """
303+ Remove the page for this wizard indicated by the page0 argument from
304+ the provided session.
305+ """
306+ self._remove_form(session, page0)
307+ self._remove_page_info(session, page0)
308+ self._remove_cleaned_data(session, page0)
309+ self._remove_POST_data(session, page0)
310+
311+ def _remove_page_info(self, session, page0):
312+ """
313+ Remove the page info dict for this wizard stored at the page0 index
314+ from the provided session.
315+ """
316+ self._del_wizard_data(session, self.__page_infos_key, page0)
317+
318+ def _insert_page(self, session, page0, form_class):
319+ """
320+ Insert a page into this wizard, storing required session structures.
321+ """
322+ self._insert_form(session, page0, form_class)
323+ self._set_page_info(session, page0, False, True)
324+ self._set_cleaned_data(session, page0, {}, True)
325+ self._set_POST_data(session, {}, page0, True)
326+
327+ def _set_page_info(self, session, page0, valid, force_insert=False):
328+ """
329+ Set the page info in this wizard for a page at index page0 and stored
330+ in the provided session.
331+ """
332+ page_info = {
333+ 'valid' : valid,
334+ 'title' : self.get_page_title(session, page0)
335+ }
336+ page_infos = self._get_page_infos(session)
337+ if force_insert or len(page_infos) <= page0:
338+ page_infos.insert(page0, page_info)
339+ else:
340+ page_infos[page0] = page_info
341+ self._insert_wizard_data(session, self.__page_infos_key, page_infos)
342+ # end page methods #
343+
344+ # start wizard data utils #
345+ def _clear_wizard_data_from_session(self, session):
346+ """
347+ Clear the session data used by this wizard from the provided session.
348+ """
349+ del session[self.get_wizard_data_key(session)]
350+
351+ def _insert_wizard_data(self, session, key, data):
352+ """
353+ Inserts wizard data into the provided session at the provided key.
354+ """
355+ wizard_data = session[self.get_wizard_data_key(session)]
356+ wizard_data[key] = data
357+ session[self.get_wizard_data_key(session)] = wizard_data
358+
359+ def _del_wizard_data(self, session, key, page0):
360+ """
361+ Deletes wizard data from the provided session at the key and page0
362+ index.
363+ """
364+ wizard_data = session[self.get_wizard_data_key(session)]
365+ sub_set = wizard_data[key]
366+ if len(sub_set) > page0:
367+ del sub_set[page0]
368+ wizard_data[key] = sub_set
369+ session[self.get_wizard_data_key(session)] = wizard_data
370+
371+ # end wizard data utils #
372+
373+ # typically overriden methods #
374+ def get_wizard_data_key(self, session):
375+ """
376+ Return a session key for this wizard. The provided session could be
377+ used to prevent overlapping keys in the case that someone needs
378+ multiple instances of this wizard at one time.
379+ """
380+ return 'session_wizard_data'
381+
382+ def get_URL_base(self, request, page0):
383+ """
384+ Return the URL to this wizard minus the "page0" parto of the URL. This
385+ value is passed to template as url_base.
386+ """
387+ return request.path.replace("/" + str(page0), "/")
388+
389+ def get_page_title(self, session, page0):
390+ """
391+ Return a user friendly title for the page at index page0.
392+ """
393+ return 'Page %s' % str(page0 + 1)
394+
395+ def process_show_form(self, request, page0, form):
396+ """
397+ Called before rendering a form either from a GET or when a form submit
398+ is invalid.
399+ """
400+
401+ def preprocess_submit_form(self, request, page0, form):
402+ """
403+ Called when a form is POSTed, but before form is validated. If this
404+ function returns None then form submission continues, else it should
405+ return a new page index that will be redirected to as a GET.
406+ """
407+
408+ def process_submit_form(self, request, page0, form):
409+ """
410+ Called when a form is POSTed. This is only called if the form data is
411+ valid. If this method returns True, the done() method is called,
412+ otherwise the wizard continues. Note that it is possible that this
413+ method would not return True, and done() would still be called because
414+ there are no more forms left in the form_list.
415+ """
416+
417+ def get_template(self, page0):
418+ """
419+ Hook for specifying the name of the template to use for a given page.
420+ Note that this can return a tuple of template names if you'd like to
421+ use the template system's select_template() hook.
422+ """
423+ return 'forms/session_wizard.html'
424+
425+ def done(self, request):
426+ """
427+ Hook for doing something with the validated data. This is responsible
428+ for the final processing including clearing the session scope of items
429+ created by this wizard.
430+ """
431+ raise NotImplementedError("Your %s class has not defined a done() " + \
432+ "method, which is required." \
433+ % self.__class__.__name__)
Back to Top