~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.app.browser.launchpadform 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.app.browser.launchpadform 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.app.browser.launchpadform 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.app.browser.launchpadform 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'