= The Project Scope Widget =

Many application front pages contain a search form. The search
can usually be across the whole Launchpad or only in one project.
The ProjectScopeWidget is used to select that scope. The scope type
is actually determined by the field's vocabulary. In this example,
we will use the Project vocabulary which allows any project to be
selected.

    >>> from zope.schema import Choice
    >>> from canonical.launchpad.webapp.servers import LaunchpadTestRequest
    >>> from canonical.launchpad.webapp.testing import verifyObject
    >>> from lp.app.widgets.project import ProjectScopeWidget

    >>> empty_request = LaunchpadTestRequest()
    >>> scope_field = Choice(
    ...     __name__='scope', vocabulary='ProjectGroup', required=False)
    >>> scope_field = scope_field.bind(object())
    >>> widget = ProjectScopeWidget(
    ...     scope_field, scope_field.vocabulary, empty_request)

The widget complies to both IInputWidget and IBrowserWidget.

    >>> from zope.app.form.browser.interfaces import IBrowserWidget
    >>> from zope.app.form.interfaces import IInputWidget
    >>> verifyObject(IInputWidget, widget)
    True
    >>> verifyObject(IBrowserWidget, widget)
    True

When the request is empty, the widget doesn't have any input:

    >>> widget.hasInput()
    False
    >>> widget.hasValidInput()
    False

It's a radio widget, so it assumes that it always will have input. If
the widget isn't required, getInputValue() returns None if there
isn't any input.

    >>> widget.required
    False
    >>> widget.getInputValue() is None
    True

If the widget is required, getInputValue() raises UnexpectedFormData if
there is no input.

    >>> widget.required = True
    >>> widget.getInputValue()
    Traceback (most recent call last):
    ...
    UnexpectedFormData: No valid option was selected.

By default, the 'All projects' scope is selected:

    >>> print widget()
    <label>
      <input class="radioType" checked="checked"
             id="field.scope.option.all" name="field.scope"
             type="radio" value="all" />
      All projects
    </label>
    <label>
      <input class="radioType" id="field.scope.option.project"
             name="field.scope"
             onclick="document.getElementById('field.scope.target').focus();"
             type="radio" value="project"
             />
      One project:
    ...

== Selecting All Projects ==

When the 'All projects' option is selected, the widget returns None.

    >>> form = {'field.scope': 'all',
    ...         'field.scope.target': ''}
    >>> widget = ProjectScopeWidget(
    ...     scope_field, scope_field.vocabulary,
    ...     LaunchpadTestRequest(form=form))
    >>> widget.hasInput()
    True
    >>> widget.getInputValue() is None
    True

== Selecting One Project ==

If we select a project, the project with that name is returned
by getInputValue().

    >>> form = {'field.scope': 'project',
    ...         'field.scope.target': 'mozilla'}
    >>> from lp.registry.interfaces.projectgroup import IProjectGroup
    >>> widget = ProjectScopeWidget(
    ...     scope_field, scope_field.vocabulary,
    ...     LaunchpadTestRequest(form=form))
    >>> widget.hasInput()
    True
    >>> selected_scope = widget.getInputValue()
    >>> IProjectGroup.providedBy(selected_scope)
    True
    >>> selected_scope.name
    u'mozilla'

If an non-existant distribution name is provided, a widget error is
raised:

    >>> form['field.scope.target'] = 'invalid'
    >>> widget = ProjectScopeWidget(
    ...     scope_field, scope_field.vocabulary,
    ...     LaunchpadTestRequest(form=form))
    >>> widget.hasInput()
    True
    >>> selected_scope = widget.getInputValue()
    Traceback (most recent call last):
    ...
    LaunchpadValidationError: There is no project named 'invalid'
                              registered in Launchpad

The same error text is returned by error():

    >>> print widget.error()
    There is no project named 'invalid' registered in Launchpad

If no project name is given at all, a widget error is also raised:

    >>> form['field.scope.target'] = ''
    >>> widget = ProjectScopeWidget(
    ...     scope_field, scope_field.vocabulary,
    ...     LaunchpadTestRequest(form=form))
    >>> widget.hasInput()
    True
    >>> selected_scope = widget.getInputValue()
    Traceback (most recent call last):
    ...
    LaunchpadValidationError: Please enter a project name

    >>> print widget.error()
    Please enter a project name

    >>> del form['field.scope.target']
    >>> widget = ProjectScopeWidget(
    ...     scope_field, scope_field.vocabulary,
    ...     LaunchpadTestRequest(form=form))
    >>> widget.hasInput()
    True
    >>> selected_scope = widget.getInputValue()
    Traceback (most recent call last):
    ...
    LaunchpadValidationError: Please enter a project name

    >>> print widget.error()
    Please enter a project name

== setRenderedValue() ==

In order to initialize the widget with a value, setRenderedValue() is
used. Passing a product to it will select the 'One project' radio
button, as well as displaying the product name in the project widget.

    >>> from lp.registry.interfaces.projectgroup import IProjectGroupSet
    >>> widget = ProjectScopeWidget(
    ...     scope_field, scope_field.vocabulary, empty_request)
    >>> projectgroups = getUtility(IProjectGroupSet)
    >>> widget.setRenderedValue(projectgroups.getByName('mozilla'))
    >>> print widget()
    <label>
      <input class="radioType" id="field.scope.option.all"
             name="field.scope" type="radio" value="all" />
    ...
      <input class="radioType" checked="checked"
             id="field.scope.option.project" name="field.scope"
             onclick="document.getElementById('field.scope.target').focus();"
             type="radio" value="project" />
    ...
      <input type="text" value="mozilla" id="field.scope.target"
             name="field.scope.target" size="20"
             maxlength=""
             onKeyPress="selectWidget('field.scope.option.project', event)" style=""
             class="" />
    ...

Setting the scope to None, will default to the 'All projects' option.

    >>> widget.setRenderedValue(None)
    >>> print widget()
    <label>
      <input class="radioType" checked="checked"
             id="field.scope.option.all" name="field.scope"
             type="radio" value="all" />
    ...

== getScope() and partial queries ==

In some cases, forms with a ProjectScopeWidget are requested by bots
which incorrectly build the query string without without the `scope`
parameter. A method, `getScope` is provided, which returns the value
of the scope option, or `None` if no scope was selected.

    >>> form = {'field.scope': 'project',
    ...         'field.scope.target': 'mozilla'}
    >>> widget = ProjectScopeWidget(
    ...     scope_field, scope_field.vocabulary,
    ...     LaunchpadTestRequest(form=form))
    >>> print widget.getScope()
    project

    >>> form = {'field.scope': 'all',
    ...         'field.scope.target': ''}
    >>> widget = ProjectScopeWidget(
    ...     scope_field, scope_field.vocabulary,
    ...     LaunchpadTestRequest(form=form))
    >>> print widget.getScope()
    all

    >>> form = {'field.scope.target': ''}
    >>> widget = ProjectScopeWidget(
    ...     scope_field, scope_field.vocabulary,
    ...     LaunchpadTestRequest(form=form))
    >>> print widget.getScope()
    None