Action Managers

Action managers are components that manage all actions that can be taken within a view, usually a form. They are also responsible for executing actions when asked to do so.

Creating an action manager

An action manager is a form-related adapter that has the following discriminator: form, request, and content. While there is a base implementation for an action manager, the action module does not provide a full implementation.

So we first have to build a simple implementation based on the Actions manager base class which allows us to add actions. Note that the following implementation is for demonstration purposes. If you want to see a real action manager implementation, then have a look at ButtonActions. Let’s now implement our simple action manager:

>>> from z3c.form import action
>>> class SimpleActions(action.Actions):
...     """Simple sample."""
...
...     def append(self, name, action):
...         """See z3c.form.interfaces.IActions."""
...         if not name in self:
...             self._data_keys.append(name)
...         self._data_values.append(action)
...         self._data[name] = action

Before we can initialise the action manager, we have to create instances for our three discriminators, just enough to get it working:

>>> import zope.interface
>>> from z3c.form import interfaces
>>> class Form(object):
...     zope.interface.implements(interfaces.IForm)
>>> form = Form()

>>> class Content(object):
...     zope.interface.implements(zope.interface.Interface)
>>> content = Content()

>>> from z3c.form.testing import TestRequest
>>> request = TestRequest()

We are now ready to create the action manager, which is a simple triple-adapter:

>>> manager = SimpleActions(form, request, content)
>>> manager
<SimpleActions None>

As we can see in the manager representation above, the name of the manager is None, since we have not specified one:

>>> manager.__name__ = 'example'
>>> manager
<SimpleActions 'example'>

Managing and Accessing Actions

Initially there are no actions in the manager:

>>> manager.keys()
[]

Our simple implementation of has an additional append() method, which we will use to add actions:

>>> apply = action.Action(request, u'Apply')
>>> manager.append(apply.name, apply)

The action is added immediately:

>>> manager.keys()
['apply']

However, you should not rely on it being added, and always update the manager once all actions were defined:

>>> manager.update()

Note: If the title of the action is a more complex unicode string and no name is specified for the action, then a hexadecimal name is created from the title:

>>> action.Action(request, u'Apply Now!').name
'4170706c79204e6f7721'

Since the action manager is an enumerable mapping, ...

>>> from zope.interface.common.mapping import IEnumerableMapping
>>> IEnumerableMapping.providedBy(manager)
True

there are several API methods available:

>>> manager['apply']
<Action 'apply' u'Apply'>
>>> manager['foo']
Traceback (most recent call last):
...
KeyError: 'foo'

>>> manager.get('apply')
<Action 'apply' u'Apply'>
>>> manager.get('foo', 'default')
'default'

>>> 'apply' in manager
True
>>> 'foo' in manager
False

>>> manager.values()
[<Action 'apply' u'Apply'>]

>>> manager.items()
[('apply', <Action 'apply' u'Apply'>)]

>>> len(manager)
1

Executing actions

When an action is executed, an execution adapter is looked up. If there is no adapter, nothing happens. So let’s create a request that submits the apply button:

>>> request = TestRequest(form={'apply': 'Apply'})
>>> manager = SimpleActions(form, request, content)

We also want to have two buttons in this case, so that we can ensure that only one is executed:

>>> apply = action.Action(request, u'Apply')
>>> manager.append(apply.name, apply)

>>> cancel = action.Action(request, u'Cancel')
>>> manager.append(cancel.name, cancel)
>>> manager.update()

Now that the manager is updated, we can ask it for the “executed” actions:

>>> manager.executedActions
[<Action 'apply' u'Apply'>]

Executing the actions does nothing, because there are no handlers yet:

>>> manager.execute()

Let’s now register an action handler that listens to the “Apply” action. An action handler has four discriminators: form, request, content, and action. All those objects are available to the handler under those names. When using the base action handler from the action module, __call__() is the only method that needs to be implemented:

>>> from z3c.form import util

>>> class SimpleActionHandler(action.ActionHandlerBase):
...     zope.component.adapts(
...         None, TestRequest, None, util.getSpecification(apply))
...     def __call__(self):
...         print 'successfully applied'

>>> zope.component.provideAdapter(SimpleActionHandler)

As you can see, we registered the action specifically for the apply action. Now, executing the actions calls this handler:

>>> manager.execute()
successfully applied

Of course it only works for the “Apply” action and not “”Cancel”:

>>> request = TestRequest(form={'cancel': 'Cancel'})
>>> manager.request = apply.request = cancel.request = request
>>> manager.execute()

Further, when a handler is successfully executed, an event is sent out, so let’s register an event handler:

>>> eventlog = []
>>> @zope.component.adapter(interfaces.IActionEvent)
... def handleEvent(event):
...     eventlog.append(event)

>>> zope.component.provideHandler(handleEvent)

Let’s now execute the “Apply” action again:

>>> request = TestRequest(form={'apply': 'Apply'})
>>> manager.request = apply.request = cancel.request = request
>>> manager.execute()
successfully applied

>>> eventlog[-1]
<ActionSuccessful for <Action 'apply' u'Apply'>>

Action handlers, however, can also raise action errors. These action errors are caught and an event is created notifying the system of the problem. The error is not further propagated. Other errors are not handled by the system to avoid hiding real failures of the code.

Let’s see how action errors can be used by implementing a handler for the cancel action:

>>> class ErrorActionHandler(action.ActionHandlerBase):
...     zope.component.adapts(
...         None, TestRequest, None, util.getSpecification(cancel))
...     def __call__(self):
...         raise interfaces.ActionExecutionError(
...             zope.interface.Invalid('Something went wrong'))

>>> zope.component.provideAdapter(ErrorActionHandler)

As you can see, the action execution error wraps some other execption, in this case a simple invalid error.

Executing the “Cancel” action now produces the action error event:

>>> request = TestRequest(form={'cancel': 'Cancel'})
>>> manager.request = apply.request = cancel.request = request
>>> manager.execute()

>>> eventlog[-1]
<ActionErrorOccurred for <Action 'cancel' u'Cancel'>>

>>> eventlog[-1].error
<ActionExecutionError wrapping ...Invalid...>