===========
Error Views
===========

Error views are looked up every time a validation error occurs during data
extraction and/or validation. Unfortunately, it was often hard to adjust error
messages based on specific situations. The error view implementation in this
package is designed to provide several high-level features that make
customizing error messages easier.

  >>> from z3c.form import error


Creating and Displaying the Default Error View
----------------------------------------------

Let's create an error view message for the ``TooSmall`` validation error:

  >>> from zope.schema.interfaces import TooSmall, TooBig
  >>> from z3c.form.testing import TestRequest

  >>> view = error.ErrorViewSnippet(
  ...     TooSmall(), TestRequest(), None, None, None, None)
  >>> view
  <ErrorViewSnippet for TooSmall>

The discriminators for an error view are as follows: error, request, widget,
field, form, and content. After updating the view, a test message is available:

  >>> view.update()
  >>> view.message
  u'Value is too small'

And after registering a template for the error view, we can also render the
view:

  >>> import os
  >>> filename = os.path.join(os.path.dirname(error.__file__), 'error.pt')

  >>> import zope.component
  >>> from zope.pagetemplate.interfaces import IPageTemplate
  >>> from z3c.form import interfaces

  >>> zope.component.provideAdapter(
  ...     error.ErrorViewTemplateFactory(filename, 'text/html'),
  ...     (interfaces.IErrorViewSnippet, None), IPageTemplate)

  >>> print view.render()
  <div class="error">Value is too small</div>


Customizing Error Messages
--------------------------

As you can imagine, writing new error views for every scenario can be very
tedious, especially if you only want to provide a specific error *message*. So
let's create somewhat more interesting setup:

  >>> import zope.interface
  >>> import zope.schema
  >>> class IPerson(zope.interface.Interface):
  ...     name = zope.schema.TextLine(title=u'Name')
  ...     age = zope.schema.Int(
  ...         title=u'Age',
  ...         min=0)

You must agree, that the follwoing message is pretty dull when entering a
negative age:

  >>> print view.render()
  <div class="error">Value is too small</div>

So let's register a better message for this particular situation:

  >>> NegativeAgeMessage = error.ErrorViewMessage(
  ...     u'A negative age is not sensible.',
  ...     error=TooSmall, field=IPerson['age'])

  >>> zope.component.provideAdapter(NegativeAgeMessage, name='message')

The created object is a common attribute value for the error view message. The
discriminators are the same as for the error view itself. Now we create an
error view message for ``TooSmall`` of the age field:

  >>> view = error.ErrorViewSnippet(
  ...     TooSmall(), TestRequest(), None, IPerson['age'], None, None)

  >>> view.update()
  >>> print view.render()
  <div class="error">A negative age is not sensible.</div>

Much better, isn't it?

We can also provide dynamic error view messages that are computed each time we
get an error. For example, we have an IAdult interface that have minimal age of
18:

  >>> class IAdult(zope.interface.Interface):
  ...     age = zope.schema.Int(title=u'Age', min=18)

Now, let's create a function that will be called by a message value adapter,
it receives one argument, a special ``z3c.form.value.ComputedValue`` object
that will have all needed attributes: error, request, widget, field, form and
content. Let's use one of them:

  >>> def getAgeTooSmallErrorMessage(value):
  ...     return u'Given age is smaller than %d, you are not adult.' % (
  ...         value.field.min)

Now, register the computed view message:

  >>> ComputedAgeMessage = error.ComputedErrorViewMessage(
  ...     getAgeTooSmallErrorMessage, error=TooSmall, field=IAdult['age'])
  >>> zope.component.provideAdapter(ComputedAgeMessage, name='message')

Now, the error view snippet will show dynamically generated message:

  >>> view = error.ErrorViewSnippet(
  ...     TooSmall(), TestRequest(), None, IAdult['age'], None, None)
  >>> view.update()
  >>> print view.render()
  <div class="error">Given age is smaller than 18, you are not adult.</div>


Registering Custom Error Views
------------------------------

Even though message attribute values will solve most of our customization
needs, sometimes one wishes to register a custom view to have more complex
views. In this example we wish to register a custom error message:

  >>> from z3c.form import ptcompat as viewpagetemplatefile
  >>> from z3c.form import tests

  >>> class NegativeAgeView(error.ErrorViewSnippet):
  ...     template = viewpagetemplatefile.ViewPageTemplateFile(
  ...         'custom_error.pt', os.path.dirname(tests.__file__))

We now need to assert the special discriminators specific to this view:

  >>> error.ErrorViewDiscriminators(
  ...     NegativeAgeView, error=TooSmall, field=IPerson['age'])

After registering the new and default error view, ...

  >>> zope.component.provideAdapter(NegativeAgeView)
  >>> zope.component.provideAdapter(error.ErrorViewSnippet)

we can now make use of it, but only for this particular field and error:

  >>> zope.component.getMultiAdapter(
  ...     (TooSmall(), TestRequest(), None, IPerson['age'], None, None),
  ...     interfaces.IErrorViewSnippet)
  <NegativeAgeView for TooSmall>

Other combinations will return the default screen instead:

  >>> zope.component.getMultiAdapter(
  ...     (TooBig(), TestRequest(), None, IPerson['age'], None, None),
  ...     interfaces.IErrorViewSnippet)
  <ErrorViewSnippet for TooBig>

  >>> zope.component.getMultiAdapter(
  ...     (TooSmall(), TestRequest(), None, IPerson['name'], None, None),
  ...     interfaces.IErrorViewSnippet)
  <ErrorViewSnippet for TooSmall>


Value Error View Snippets
-------------------------

In the previous examples we have always worked with the view of the validation
error. Since data managers can also return value errors, there is also an
error view for them:

  >>> valueError = ValueError(2)
  >>> errorView = error.ValueErrorViewSnippet(
  ...     valueError, TestRequest(), None, None, None, None)

It uses the same template:

  >>> errorView.update()
  >>> print errorView.render()
  <div class="error">The system could not process the given value.</div>

Unfortunately, we cannot make use of the original string representation of the
value error, since it cannot be localized well enough. Thus we provide our own
message. Of course, the message can be overridden:

  >>> CustomMessage = error.ErrorViewMessage(
  ...     u'The entered value is not valid.', error=ValueError)
  >>> zope.component.provideAdapter(CustomMessage, name='message')

Let's now render the snippet again:

  >>> errorView.update()
  >>> print errorView.render()
  <div class="error">The entered value is not valid.</div>


Invalid Error View Snippets
---------------------------

When invariants are used, commonly the ``Invalid`` exception (from the
``zope.interface`` package) is raised from within the invariant, if the
invariant finds a problem. We need a special error view snippet for this class
of errors:

  >>> invalidError = zope.interface.Invalid(u'The data was invalid.')
  >>> errorView = error.InvalidErrorViewSnippet(
  ...     invalidError, TestRequest(), None, None, None, None)

Since the same template as before is used, the error simply renders:

  >>> errorView.update()
  >>> print errorView.render()
  <div class="error">The data was invalid.</div>

As you can see, the first argument to the exception is used as the explanatory
message of the error.