~launchpad-pqm/launchpad/devel

= LaunchpadFormView =

LaunchpadFormView is a base class for form views in Launchpad.  It is
intended as a replacement for GeneralFormView.

There are a number of things that need to be customised when creating
a LaunchpadFormView based view class:

 * the "schema" attribute should be set to a schema defining the
   fields used in the form.

 * if only a subset of the fields are to be displayed in the form, the
   "field_names" attribute should be set.

 * if any fields require custom widgets, the "custom_widgets"
   attribute should be set to a dictionary mapping field names to
   widget factories.

 * one or more actions must be provided by the form if it is to
   support submission.

 * if form wide validation is needed, the validate() method should be
   overriden. Errors are reported using the addError() and
   setFieldError() methods.

 * if a form contains multiple actions, the validate_widgets method
   can be used to validate that action's subset of the form's widgets.

 * the "next_url" attribute should be set to the URL to redirect to on
   successful form submission.  If this is a computed value, you might
   want to use a property.

 * the "initial_focus_widget" attribute specifies which element should be
   focused by default.

Views using LaunchpadFormView can be registered with the standard
<browser:page> ZCML directive.

There is also a LaunchpadEditFormView class to make it easier to write
edit views.


== The Schema ==

The schema can be an interface implemented by your content object, or
an interface specifically tailored for data entry.  Below is an
example schema:

  >>> from zope.interface import Interface, implements
  >>> from zope.schema import TextLine

  >>> class IFormTest(Interface):
  ...     name = TextLine(title=u"Name")
  ...     displayname = TextLine(title=u"Title")
  ...     password = TextLine(title=u"Password")

  >>> class FormTest:
  ...     implements(IFormTest)
  ...     name = 'fred'
  ...     displayname = 'Fred'
  ...     password = 'password'


A form that handles all fields in the schema needs only set the
"schema" attribute:

  >>> from lp.app.browser.launchpadform import LaunchpadFormView
  >>> from lp.services.webapp.servers import LaunchpadTestRequest

  >>> class FormTestView1(LaunchpadFormView):
  ...     schema = IFormTest

  >>> context = FormTest()
  >>> request = LaunchpadTestRequest()
  >>> view = FormTestView1(context, request)
  >>> view.setUpFields()
  >>> [field.__name__ for field in view.form_fields]
  ['name', 'displayname', 'password']


== Restricting Displayed Fields ==

The list of fields can be restricted with the "field_names" attribute:

  >>> class FormTestView2(LaunchpadFormView):
  ...     schema = IFormTest
  ...     field_names = ['name', 'displayname']

  >>> context = FormTest()
  >>> request = LaunchpadTestRequest()
  >>> view = FormTestView2(context, request)
  >>> view.setUpFields()
  >>> [field.__name__ for field in view.form_fields]
  ['name', 'displayname']


== Custom Adapters ==

Sometimes a schema is used for a form that is not actually implemented
by the context widget.  This can be handled by providing some custom
adapters for the form.

  >>> class IFormTest2(Interface):
  ...     name = TextLine(title=u"Name")
  >>> class FormAdaptersTestView(LaunchpadFormView):
  ...     schema = IFormTest2
  ...     @property
  ...     def adapters(self):
  ...         return {IFormTest2: self.context}

  >>> context = FormTest()
  >>> request = LaunchpadTestRequest()
  >>> IFormTest2.providedBy(context)
  False
  >>> view = FormAdaptersTestView(context, request)
  >>> view.setUpFields()
  >>> view.setUpWidgets()

We now check to see that the widget is bound to our FormTest
instance.  The context for the widget is a bound field object, who
should in turn have the FormTest instance as a context:

  >>> view.widgets['name'].context.context is context
  True


== Custom Widgets ==

In some cases we will want to use a custom widget for a particular
field.  These can be installed easily with the "custom_widgets"
attribute:

  >>> from zope.app.form.browser import TextWidget
  >>> from lp.services.webapp import custom_widget
  >>> from lp.app.widgets.password import PasswordChangeWidget

  >>> class FormTestView3(LaunchpadFormView):
  ...     schema = IFormTest
  ...     custom_widget('password', PasswordChangeWidget)
  ...     custom_widget('displayname', TextWidget, displayWidth=50)

  >>> context = FormTest()
  >>> request = LaunchpadTestRequest()
  >>> view = FormTestView3(context, request)
  >>> view.setUpFields()
  >>> view.setUpWidgets()
  >>> view.widgets['displayname']
  <...TextWidget object at ...>
  >>> view.widgets['displayname'].displayWidth
  50
  >>> view.widgets['password']
  <...PasswordChangeWidget object at ...>


== Using Another Context ==

setUpWidgets() uses the view's context by default when setting up the
widgets, but it's also possible to specify the context explicitly.

  >>> view_context = FormTest()
  >>> another_context = FormTest()
  >>> request = LaunchpadTestRequest()
  >>> view = FormTestView3(view_context, request)
  >>> view.setUpFields()
  >>> view.setUpWidgets(context=another_context)
  >>> view.widgets['displayname'].context.context is view_context
  False
  >>> view.widgets['displayname'].context.context is another_context
  True


== Actions ==

In order for a form to accept submissions, it will need one or more
submit actions.  These are added to the view class using the "action"
decorator:

  >>> from lp.services.webapp import action
  >>> class FormTestView4(LaunchpadFormView):
  ...     schema = IFormTest
  ...     field_names = ['displayname']
  ...
  ...     @action(u"Change Name", name="change")
  ...     def change_action(self, action, data):
  ...         self.context.displayname = data['displayname']

This will create a submit button at the bottom of the form labeled
"Change Name", and cause change_action() to be called when the form is
submitted with that button.

  >>> context = FormTest()
  >>> request = LaunchpadTestRequest(
  ...     method='POST',
  ...     form={'field.displayname': 'bob',
  ...           'field.actions.change': 'Change Name'})
  >>> view = FormTestView4(context, request)
  >>> view.initialize()
  >>> print context.displayname
  bob

Note that input validation should not be performed inside the action
method.  Instead, it should be performed in the validate() method, or
in per-field validators.


== Form Wide Validation ==

While constraints on individual fields and schema invariants can catch
the majority of input errors, in some cases it is necessary to
implement some custom validators for the form.

This can be done by overriding the validate() method of
LaunchpadFormView.  If validity errors are detected, they should be
reported using the addError() method (for form wide errors) or the
setFieldError() method (for errors specific to a field):

  >>> class FormTestView5(LaunchpadFormView):
  ...     schema = IFormTest
  ...     field_names = ['name', 'password']
  ...
  ...     def validate(self, data):
  ...         if data.get('name') == data.get('password'):
  ...             self.addError('your password may not be the same '
  ...                           'as your name')
  ...         if data.get('password') == 'password':
  ...             self.setFieldError('password',
  ...                                'your password must not be "password"')

  >>> context = FormTest()
  >>> request = LaunchpadTestRequest(
  ...     method='POST',
  ...     form={'field.name': 'fred', 'field.password': '12345'})
  >>> view = FormTestView5(context, request)
  >>> view.setUpFields()
  >>> view.setUpWidgets()
  >>> data = {}
  >>> view._validate(None, data)
  []


Check that form wide errors can be reported:

  >>> request = LaunchpadTestRequest(
  ...     method='POST',
  ...     form={'field.name': 'fred', 'field.password': 'fred'})
  >>> view = FormTestView5(context, request)
  >>> view.setUpFields()
  >>> view.setUpWidgets()
  >>> data = {}
  >>> view._validate(None, data)
  [u'your password may not be the same as your name']
  >>> view.form_wide_errors
  [u'your password may not be the same as your name']

Check that widget specific errors can be reported:

  >>> request = LaunchpadTestRequest(
  ...     method='POST',
  ...     form={'field.name': 'fred', 'field.password': 'password'})
  >>> view = FormTestView5(context, request)
  >>> view.setUpFields()
  >>> view.setUpWidgets()
  >>> data = {}
  >>> view._validate(None, data)
  [u'your password must not be "password"']
  >>> view.widget_errors
  {'password': u'your password must not be "password"'}

The base template used for LaunchpadFormView classes takes care of
displaying these errors in the appropriate locations.


== Widget Validation ===

A form may contain multiple actions, and a widget used for action A
might not be used for action B. The validate_widgets() method makes it
easy for an action to validate its widgets, while ignoring widgets
that belong to other actions. Here, we'll define a form with two
required fields, and show how to validate one field at a time.

  >>> class INameAndPasswordForm(Interface):
  ...     name = TextLine(title=u"Name", required=True)
  ...     password = TextLine(title=u"Password", required=True)

  >>> class FormViewForWidgetValidation(LaunchpadFormView):
  ...     schema = INameAndPasswordForm

  >>> def print_widget_validation(names):
  ...     data = {'field.name': '', 'field.password': ''}
  ...     context = FormTest()
  ...     request = LaunchpadTestRequest(method='POST', form=data)
  ...     view = FormViewForWidgetValidation(context, request)
  ...     view.setUpFields()
  ...     view.setUpWidgets()
  ...     for error in view.validate_widgets(data, names=names):
  ...         if isinstance(error, str):
  ...            print error
  ...         else:
  ...             print "%s: %s" % (error.widget_title, error.doc())

Only the fields we specify will be validated:

  >>> print_widget_validation(['name'])
  Name: Required input is missing.

  >>> print_widget_validation(['password'])
  Password: Required input is missing.

  >>> print_widget_validation(['name', 'password'])
  Name: Required input is missing.
  Password: Required input is missing.

The default behavior is to validate all widgets.

  >>> print_widget_validation(None)
  Name: Required input is missing.
  Password: Required input is missing.


== Redirect URL ==

If the form is successfully posted, then LaunchpadFormView will
redirect the user to another URL.  The URL is specified by the
"next_url" attribute:

  >>> from zope.formlib.form import action
  >>> class FormTestView6(LaunchpadFormView):
  ...     schema = IFormTest
  ...     field_names = ['displayname']
  ...     next_url = 'http://www.ubuntu.com/'
  ...
  ...     @action(u"Change Name", name="change")
  ...     def change_action(self, action, data):
  ...         self.context.displayname = data['displayname']

  >>> context = FormTest()
  >>> request = LaunchpadTestRequest(
  ...     method='POST',
  ...     form={'field.displayname': 'bob',
  ...           'field.actions.change': 'Change Name'})
  >>> view = FormTestView6(context, request)
  >>> view.initialize()
  >>> request.response.getStatus()
  302
  >>> print request.response.getHeader('location')
  http://www.ubuntu.com/


== Form Rendering ==

  (Let's define the view for the rendering tests.)
  >>> class RenderFormTest(LaunchpadFormView):
  ...     schema = IFormTest
  ...     field_names = ['displayname']
  ...
  ...     def template(self):
  ...         return u'Content that comes from a ZCML registered template.'
  ...
  ...     @action(u'Redirect', name='redirect')
  ...     def redirect_action(self, action, data):
  ...         self.next_url = 'http://launchpad.dev/'
  ...
  ...     def handleUpdateFailure(self, action, data, errors):
  ...         return u'Some errors occured.'
  ...
  ...     @action(u'Update', name='update', failure=handleUpdateFailure)
  ...     def update_action(self, action, data):
  ...         return u'Display name changed to: %s.' % data['displayname']

Like with LaunchpadView, the view content will usually be rendered by
executing the template attribute (which can be set from ZCML):

  >>> context = FormTest()
  >>> view = RenderFormTest(context, LaunchpadTestRequest(form={}))
  >>> view()
  u'Content that comes from a ZCML registered template.'

When a redirection is done (either by calling
self.request.response.redirect() or setting the next_url attribute), the
rendered content is always the empty string.

  >>> context = FormTest()
  >>> request = LaunchpadTestRequest(
  ...     method='POST',
  ...     form={'field.displayname': 'bob',
  ...           'field.actions.redirect': 'Redirect'})
  >>> view = RenderFormTest(context, request)
  >>> view()
  u''

As an alternative to executing the template attribute, an action handler
can directly return the rendered content:

  >>> context = FormTest()
  >>> request = LaunchpadTestRequest(
  ...     method='POST',
  ...     form={'field.displayname': 'bob',
  ...           'field.actions.update': 'Update'})
  >>> view = RenderFormTest(context, request)
  >>> view()
  u'Display name changed to: bob.'

This is also true of failure handlers:

  >>> context = FormTest()
  >>> request = LaunchpadTestRequest(
  ...     method='POST',
  ...     form={'field.displayname': '',
  ...           'field.actions.update': 'Update'})
  >>> view = RenderFormTest(context, request)
  >>> view()
  u'Some errors occured.'


== Initial Focused Widget ==

The standard template for LaunchpadFormView can set the initial focus
on a form element.  This is achieved by some javascript that gets run
on page load.  By default, the first form widget will be focused:

  >>> context = FormTest()
  >>> request = LaunchpadTestRequest()
  >>> view = FormTestView5(context, request)
  >>> view.initialize()
  >>> print view.focusedElementScript()
  <!--
  setFocusByName('field.name');
  // -->

The focus can also be set explicitly by overriding initial_focus_widget:

  >>> class FormTestView7(LaunchpadFormView):
  ...     schema = IFormTest
  ...     field_names = ['name', 'password']
  ...     initial_focus_widget = 'password'
  >>> context = FormTest()
  >>> request = LaunchpadTestRequest()
  >>> view = FormTestView7(context, request)
  >>> view.initialize()
  >>> print view.focusedElementScript()
  <!--
  setFocusByName('field.password');
  // -->

If initial_focus_widget is set to None, then no element will be focused
initially:

  >>> view.initial_focus_widget = None
  >>> view.focusedElementScript()
  ''

Note that if the form is being redisplayed because of a validation
error, the generated script will focus the first widget with an error:

  >>> view.setFieldError('password', 'Bad password')
  >>> print view.focusedElementScript()
  <!--
  setFocusByName('field.password');
  // -->


== Hidden widgets ==

Any widget can be hidden in a LaunchpadFormView while still having its
value POSTed with the values of the other (visible) ones. The widget's
visibility is controlled by its 'visible' attribute, which can be set
through a custom_widget() call.

First we'll create a fake pagetemplate which doesn't use Launchpad's main
template and thus is way simpler.

  >>> from StringIO import StringIO
  >>> from tempfile import mkstemp
  >>> from z3c.ptcompat import ViewPageTemplateFile
  >>> file, filename = mkstemp()
  >>> f = open(filename, 'w')
  >>> f.write(u'<div metal:use-macro="context/@@launchpad_form/form" />')
  >>> f.close()

By default, all widgets are visible.

  >>> class TestWidgetVisibility(LaunchpadFormView):
  ...     schema = IFormTest
  ...     field_names = ['displayname']
  ...     template = ViewPageTemplateFile(filename)

  >>> context = FormTest()
  >>> request = LaunchpadTestRequest()
  >>> view = TestWidgetVisibility(context, request)

  >>> from BeautifulSoup import BeautifulSoup
  >>> soup = BeautifulSoup(view())
  >>> for input in soup.findAll('input'):
  ...     print input
  <input ... name="field.displayname" ... type="text" ...

If we change a widget's 'visible' flag to False, that widget is rendered
using its hidden() method, which should return a hidden <input> tag.

  >>> class TestWidgetVisibility2(TestWidgetVisibility):
  ...     custom_widget('displayname', TextWidget, visible=False)

  >>> view = TestWidgetVisibility2(context, request)

  >>> soup = BeautifulSoup(view())
  >>> for input in soup.findAll('input'):
  ...     print input
  <input ... name="field.displayname" type="hidden" ...

  >>> import os
  >>> os.remove(filename)


== Safe Actions ==

By default, LaunchpadFormView requires that form submissions be done
via POST requests.  There are a number of reasons for this:

 * Form submissions usually classed as "unsafe" (according to the HTTP
   definition), so should not be performed with a GET.
 * If we keep all GET requests readonly, we can potentially run them
   on read-only database transactions in the future.
 * We do not want remote sites posting our forms, as it leaves
   Launchpad open to Cross-site Request Forgery (XSRF) attacks.  We
   perform additional checks on POST requests, and don't want them
   skipped by submitting the form with GET.

However, there are cases where a form action is safe (e.g. a "search"
action).  Those actions can be marked as such:

  >>> from lp.services.webapp import safe_action
  >>> class UnsafeActionTestView(LaunchpadFormView):
  ...     schema = IFormTest
  ...     field_names = ['name']
  ...
  ...     @action(u'Change', name='change')
  ...     def redirect_action(self, action, data):
  ...         print 'Change'
  ...
  ...     @safe_action
  ...     @action(u'Search', name='search')
  ...     def search_action(self, action, data):
  ...         print 'Search'
  >>> context = FormTest()

With this form, the "change" action can only be submitted with a POST
request:

  >>> request = LaunchpadTestRequest(
  ...     environ={'REQUEST_METHOD': 'GET'},
  ...     form={'field.name': 'foo',
  ...           'field.actions.change': 'Change'})
  >>> view = UnsafeActionTestView(context, request)
  >>> view.initialize()
  Traceback (most recent call last):
    ...
  UnsafeFormGetSubmissionError: field.actions.change

  >>> request = LaunchpadTestRequest(
  ...     method='POST',
  ...     form={'field.name': 'foo',
  ...           'field.actions.change': 'Change'})
  >>> view = UnsafeActionTestView(context, request)
  >>> view.initialize()
  Change


In contrast, the "search" action can be submitted with a GET request:

  >>> request = LaunchpadTestRequest(
  ...     environ={'REQUEST_METHOD': 'GET'},
  ...     form={'field.name': 'foo',
  ...           'field.actions.search': 'Search'})
  >>> view = UnsafeActionTestView(context, request)
  >>> view.initialize()
  Search



== LaunchpadEditFormView ==

The LaunchpadEditFormView differs from LaunchpadFormView in the
following ways:

 * fields take their default values from the context object.
 * a updateContextFromData() method is provided to apply the changes
   in the action method.

In other respects, it is used the same way as LaunchpadFormView:

  >>> from lp.services.webapp import LaunchpadEditFormView
  >>> class FormTestView8(LaunchpadEditFormView):
  ...     schema = IFormTest
  ...     field_names = ['displayname']
  ...     next_url = 'http://www.ubuntu.com/'
  ...
  ...     @action(u"Change Name", name="change")
  ...     def change_action(self, action, data):
  ...         if self.updateContextFromData(data):
  ...             print 'Context was updated'

  >>> context = FormTest()
  >>> request = LaunchpadTestRequest()
  >>> view = FormTestView8(context, request)
  >>> view.initialize()


The field values take their defaults from the context object:

  >>> print view.widgets['displayname']()
  <input...value="Fred"...

The updateContextFromData() method takes care of updating the context
object for us too:

  >>> context = FormTest()
  >>> request = LaunchpadTestRequest(
  ...     method='POST',
  ...     form={'field.displayname': 'James Henstridge',
  ...           'field.actions.change': 'Change Name'})
  >>> view = FormTestView8(context, request)
  >>> view.initialize()
  Context was updated

  >>> request.response.getStatus()
  302

  >>> context.displayname
  u'James Henstridge'

By default updateContextFromData() uses the view's context, but it's
possible to pass in a specific context to use instead:

  >>> custom_context = FormTest()
  >>> view.updateContextFromData({'displayname': u'New name'}, custom_context)
  True
  >>> custom_context.displayname
  u'New name'