Buttons are a method to declare actions for a form. Like fields describe widgets within a form, buttons describe actions. The symmetry goes even further; like fields, buttons are schema fields within schema. When the form is instantiated and updated, the buttons are converted to actions.
>>> from z3c.form import button
Let’s now create a schema that describes the buttons of a form. Having button schemas allows one to more easily reuse button declarations and to group them logically. Button objects are just a simple extension to Field objects, so they behave identical within a schema:
>>> import zope.interface
>>> class IButtons(zope.interface.Interface):
... apply = button.Button(title=u'Apply')
... cancel = button.Button(title=u'Cancel')
In reality, only the title and name is relevant. Let’s now create a form that provides those buttons.
>>> from z3c.form import interfaces
>>> class Form(object):
... zope.interface.implements(
... interfaces.IButtonForm, interfaces.IHandlerForm)
... buttons = button.Buttons(IButtons)
... prefix = 'form'
...
... @button.handler(IButtons['apply'])
... def apply(self, action):
... print 'successfully applied'
...
... @button.handler(IButtons['cancel'])
... def cancel(self, action):
... self.request.response.redirect('index.html')
Let’s now create an action manager for the button manager in the form. To do that we first need a request and a form instance:
>>> from z3c.form.testing import TestRequest
>>> request = TestRequest()
>>> form = Form()
We also have to register a button action factory for the buttons:
>>> zope.component.provideAdapter(
... button.ButtonAction, provides=interfaces.IButtonAction)
Action managers are instantiated using the form, request, and context/content. A special button-action-manager implementation is available in the button package:
>>> actions = button.ButtonActions(form, request, None)
>>> actions.update()
Once the action manager is updated, the buttons should be available as actions:
>>> actions.keys() ['apply', 'cancel']>>> actions['apply'] <ButtonAction 'form.buttons.apply' u'Apply'>
It is possible to customize how a button is transformed into an action by registering an adapter for the request and the button that provides IButtonAction.
>>> import zope.component >>> from zope.publisher.interfaces.browser import IBrowserRequest >>> class CustomButtonAction(button.ButtonAction): ... """Custom Button Action Class.""">>> zope.component.provideAdapter( ... CustomButtonAction, provides=interfaces.IButtonAction)
Now if we rerun update we will get this other ButtonAction implementation. Note, there are two strategies what now could happen. We can remove the existing action and get the new adapter based action or we can reuse the existing action. Since the ButtonActions class offers an API for remove existing actions, we reuse the existing action because it very uncommon to replace existing action during an for update call with an adapter. If someone really will add an action adapter during process time via directly provided interface, he is also responsible for remove existing actions.
As you can see we still will get the old button action if we only call update:
>>> actions.update() >>> actions.keys() ['apply', 'cancel']>>> actions['apply'] <ButtonAction 'form.buttons.apply' u'Apply'>
This means we have to remove the previous action before we call update:
>>> del actions['apply']
>>> actions.update()
Make sure we do not append a button twice to the key and value lists by calling update twice:
>>> actions.keys() ['apply', 'cancel']>>> actions['apply'] <CustomButtonAction 'form.buttons.apply' u'Apply'>
Alternatively, customize an individual button by setting its actionFactory attribute.
>>> def customButtonActionFactory(request, field): ... print "This button factory creates a button only once." ... button = CustomButtonAction(request, field) ... button.css = "happy" ... return button>>> form.buttons['apply'].actionFactory = customButtonActionFactory
Again, remove the old button action befor we call update:
>>> del actions['apply'] >>> actions.update() This button factory creates a button only once.>>> actions.update() >>> actions['apply'].css 'happy'
Since we only create a button once from an adapter or a factory, we can change the button attributes without to lose changes:
>>> actions['apply'].css = 'very happy' >>> actions['apply'].css 'very happy'>>> actions.update() >>> actions['apply'].css 'very happy'
But let’s not digress too much and get rid of this customization
>>> form.buttons['apply'].actionFactory = None
>>> actions.update()
Button actions are locations:
>>> apply = actions['apply']
>>> apply.__name__
'apply'
>>> apply.__parent__
<ButtonActions None>
A button action is also a submit widget. The attributes translate as follows:
>>> interfaces.ISubmitWidget.providedBy(apply) True>>> apply.value == apply.title True >>> apply.id == apply.name.replace('.', '-') True
Next we want to display our button actions. To be able to do this, we have to register a template for the submit widget:
>>> from z3c.form import testing, widget >>> templatePath = testing.getPath('submit_input.pt') >>> factory = widget.WidgetTemplateFactory(templatePath, 'text/html')>>> from zope.pagetemplate.interfaces import IPageTemplate >>> zope.component.provideAdapter(factory, ... (zope.interface.Interface, TestRequest, None, None, ... interfaces.ISubmitWidget), ... IPageTemplate, name='input')
A widget template has many discriminators: context, request, view, field, and widget. We can now render each action:
>>> print actions['apply'].render()
<input type="submit" id="form-buttons-apply"
name="form.buttons.apply" class="submit-widget button-field"
value="Apply" />
So displaying is nice, but how do button handlers get executed? The action manager provides attributes and method to check whether actions were executed. Initially there are no executed actions:
>>> list(actions.executedActions)
[]
So in this case executing the actions does not do anything:
>>> actions.execute()
But if the request contains the information that the button was pressed, the execution works:
>>> request = TestRequest(form={'form.buttons.apply': 'Apply'})>>> actions = button.ButtonActions(form, request, None) >>> actions.update() >>> actions.execute()
Aehm, something should have happened. But in order for the system to look at the handlers declared in the form, a special action handler has to be registered with the system:
>>> zope.component.provideAdapter(button.ButtonActionHandler)
And voila, the execution works:
>>> actions.execute()
successfully applied
Finally, if there is no handler for a button, then the button click is silently ignored:
>>> form.handlers = button.Handlers()
>>> actions.execute()
While this might seem awkward at first, this is an intended feature. Sometimes there are several sub-forms that listen to a particular button and one form or another might simply not care about the button at all and not provide a handler.
Some readers might find it cumbersome to declare a full schema just to create some buttons. A faster method is to write simple arguments to the button manager:
>>> class Form(object):
... zope.interface.implements(
... interfaces.IButtonForm, interfaces.IHandlerForm)
... buttons = button.Buttons(
... button.Button('apply', title=u'Apply'))
... prefix = 'form.'
...
... @button.handler(buttons['apply'])
... def apply(self, action):
... print 'successfully applied'
The first argument of the Button class constructor is the name of the button. Optionally, this can also be one of the following keyword arguments:
>>> button.Button(name='apply').__name__
'apply'
>>> button.Button(__name__='apply').__name__
'apply'
If no name is specified, the button will not have a name immediately, ...
>>> button.Button(title=u'Apply').__name__
''
because if the button is created within an interface, the name is assigned later:
>>> class IActions(zope.interface.Interface): ... apply = button.Button(title=u'Apply')>>> IActions['apply'].__name__ 'apply'
However, once the button is added to a button manager, a name will be assigned:
>>> btns = button.Buttons(button.Button(title=u'Apply')) >>> btns['apply'].__name__ 'apply'>>> btns = button.Buttons(button.Button(title=u'Apply and more')) >>> btns['4170706c7920616e64206d6f7265'].__name__ '4170706c7920616e64206d6f7265'
This declaration behaves identical to the one before:
>>> form = Form() >>> request = TestRequest()>>> actions = button.ButtonActions(form, request, None) >>> actions.update() >>> actions.execute()
When sending in the right information, the actions are executed:
>>> request = TestRequest(form={'form.buttons.apply': 'Apply'})
>>> actions = button.ButtonActions(form, request, None)
>>> actions.update()
>>> actions.execute()
successfully applied
An even simpler method – resembling closest the API provided by formlib – is to create the button and handler at the same time:
>>> class Form(object):
... zope.interface.implements(
... interfaces.IButtonForm, interfaces.IHandlerForm)
... prefix = 'form.'
...
... @button.buttonAndHandler(u'Apply')
... def apply(self, action):
... print 'successfully applied'
In this case the buttonAndHandler decorator creates a button and a handler for it. By default the name is computed from the title of the button, which is required. All (keyword) arguments are forwarded to the button constructor. Let’s now render the form:
>>> request = TestRequest(form={'form.buttons.apply': 'Apply'})
>>> actions = button.ButtonActions(form, request, None)
>>> actions.update()
>>> actions.execute()
successfully applied
If the title is a more complex string, then the name of the button becomes a hex-encoded string:
>>> class Form(object): ... ... @button.buttonAndHandler(u'Apply and Next') ... def apply(self, action): ... print 'successfully applied'>>> Form.buttons.keys() ['4170706c7920616e64204e657874']
Of course, you can use the __name__ argument to specify a name yourself. The decorator, however, also allows the keyword name:
>>> class Form(object): ... ... @button.buttonAndHandler(u'Apply and Next', name='applyNext') ... def apply(self, action): ... print 'successfully applied'>>> Form.buttons.keys() ['applyNext']
This helper function also supports a keyword argument provides, which allows the developer to specify a sequence of interfaces that the generated button should directly provide. Those provided interfaces can be used for a multitude of things, including handler discrimination and UI layout:
>>> class IMyButton(zope.interface.Interface): ... pass>>> class Form(object): ... ... @button.buttonAndHandler(u'Apply', provides=(IMyButton,)) ... def apply(self, action): ... print 'successfully applied'>>> IMyButton.providedBy(Form.buttons['apply']) True
Sometimes it is desirable to only show a button when a certain condition is fulfilled. The Button field supports conditions via a simple argument. The condition argument must be a callable taking the form as argument and returning a truth-value. If the condition is not fulfilled, the button will not be converted to an action:
>>> class Form(object):
... prefix='form'
... showApply = True
...
... @button.buttonAndHandler(
... u'Apply', condition=lambda form: form.showApply)
... def apply(self, action):
... print 'successfully applied'
In this case a form variable specifies the availability. Initially the button is available as action:
>>> myform = Form()
>>> actions = button.ButtonActions(myform, TestRequest(), None)
>>> actions.update()
>>> actions.keys()
['apply']
If we set the show-apply attribute to false, the action will not be available.
>>> myform.showApply = False
>>> actions = button.ButtonActions(myform, TestRequest(), None)
>>> actions.update()
>>> actions.keys()
[]
This feature is very helpful in multi-forms and wizards.
As for widgets, it is often desirable to change attributes of the button actions without altering any original code. Again we will be using attribute value adapters to complete the task. Originally, our title is as follows:
>>> myform = Form()
>>> actions = button.ButtonActions(myform, TestRequest(), None)
>>> actions.update()
>>> actions['apply'].title
u'Apply'
Let’s now create a custom label for the action:
>>> ApplyLabel = button.StaticButtonActionAttribute(
... u'Apply now', button=myform.buttons['apply'])
>>> zope.component.provideAdapter(ApplyLabel, name='title')
Once the button action manager is updated, the new title is chosen:
>>> actions.update()
>>> actions['apply'].title
u'Apply now'
The button manager contains several additional API methods that make the management of buttons easy.
First, you are able to add button managers:
>>> bm1 = button.Buttons(IButtons) >>> bm2 = button.Buttons(button.Button('help', title=u'Help'))>>> bm1 + bm2 <z3c.form.button.Buttons object at ...> >>> list(bm1 + bm2) ['apply', 'cancel', 'help']
The result of the addition is another button manager. Also note that the order of the buttons is preserved throughout the addition. Adding anything else is not well-defined:
>>> bm1 + 1
Traceback (most recent call last):
...
TypeError: unsupported operand type(s) for +: 'Buttons' and 'int'
Second, you can select the buttons in a particular order:
>>> bm = bm1 + bm2 >>> list(bm) ['apply', 'cancel', 'help']>>> list(bm.select('help', 'apply', 'cancel')) ['help', 'apply', 'cancel']
The select() method can also be used to eliminate another button:
>>> list(bm.select('help', 'apply'))
['help', 'apply']
Of course, in the example above we eliminated one and reorganized the buttons.
Third, you can omit one or more buttons:
>>> list(bm.omit('cancel'))
['apply', 'help']
Finally, while the constructor is very flexible, you cannot just pass in anything:
>>> button.Buttons(1, 2)
Traceback (most recent call last):
...
TypeError: ('Unrecognized argument type', 1)
When creating a new form derived from another, you often want to keep existing buttons and add new ones. In order not to change the super-form class, you need to copy the button manager:
>>> bm.keys()
['apply', 'cancel', 'help']
>>> bm.copy().keys()
['apply', 'cancel', 'help']
All handlers of a form are collected in the handlers attribute, which is a Handlers instance:
>>> isinstance(form.handlers, button.Handlers)
True
>>> form.handlers
<Handlers [<Handler for <Button 'apply' u'Apply'>>]>
Internally the object uses an adapter registry to manage the handlers for buttons. If a handler is registered for a button, it simply behaves as an instance-adapter.
The object itself is pretty simple. You can get a handler as follows:
>>> apply = form.buttons['apply']
>>> form.handlers.getHandler(apply)
<Handler for <Button 'apply' u'Apply'>>
But you can also register handlers for groups of buttons, either by interface or class:
>>> class SpecialButton(button.Button): ... pass>>> def handleSpecialButton(form, action): ... return 'Special button action'>>> form.handlers.addHandler( ... SpecialButton, button.Handler(SpecialButton, handleSpecialButton))>>> form.handlers <Handlers [<Handler for <Button 'apply' u'Apply'>>, <Handler for <class 'SpecialButton'>>]>
Now all special buttons should use that handler:
>>> button1 = SpecialButton(name='button1', title=u'Button 1') >>> button2 = SpecialButton(name='button2', title=u'Button 2')>>> form.handlers.getHandler(button1)(form, None) 'Special button action' >>> form.handlers.getHandler(button2)(form, None) 'Special button action'
However, registering a more specific handler for button 1 will override the general handler:
>>> def handleButton1(form, action): ... return 'Button 1 action'>>> form.handlers.addHandler( ... button1, button.Handler(button1, handleButton1))>>> form.handlers.getHandler(button1)(form, None) 'Button 1 action' >>> form.handlers.getHandler(button2)(form, None) 'Special button action'
You can also add handlers objects:
>>> handlers2 = button.Handlers()>>> button3 = SpecialButton(name='button3', title=u'Button 3') >>> handlers2.addHandler( ... button3, button.Handler(button3, None))>>> form.handlers + handlers2 <Handlers [<Handler for <Button 'apply' u'Apply'>>, <Handler for <class 'SpecialButton'>>, <Handler for <SpecialButton 'button1' u'Button 1'>>, <Handler for <SpecialButton 'button3' u'Button 3'>>]>
However, adding other components is not supported:
>>> form.handlers + 1
Traceback (most recent call last):
...
NotImplementedError
The handlers also provide a method to copy the handlers to a new instance:
>>> copy = form.handlers.copy()
>>> isinstance(copy, button.Handlers)
True
>>> copy is form.handlers
False
This is commonly needed when one wants to extend the handlers of a super-form.
A special type of button is the image button. Instead of creating a “submit”- or “button”-type input, an “image” button is created. An image button is a simple extension of a button, requiring an image argument to the constructor:
>>> imgSubmit = button.ImageButton(
... name='submit',
... title=u'Submit',
... image=u'submit.png')
>>> imgSubmit
<ImageButton 'submit' u'submit.png'>
Some browsers do not submit the value of the input, but only the coordinates of the image where the mouse click occurred. Thus we also need a special button action:
>>> from zope.publisher.browser import TestRequest >>> request = TestRequest()>>> imgSubmitAction = button.ImageButtonAction(request, imgSubmit) >>> imgSubmitAction <ImageButtonAction 'submit' u'Submit'>
Initially, we did not click on the image:
>>> imgSubmitAction.isExecuted()
False
Now the button is clicked:
>>> request = TestRequest(form={'submit.x': '3', 'submit.y': '4'})>>> imgSubmitAction = button.ImageButtonAction(request, imgSubmit) >>> imgSubmitAction.isExecuted() True
The “image” type of the “input”-element also requires there to be a src attribute, which is the URL to the image to be used. The attribute is also supported by the Python API. However, in order for the attribute to work, the image must be available as a resource, so let’s do that now:
# Traversing setup >>> from zope.traversing import testing >>> testing.setUp()
# Resource namespace >>> import zope.component >>> from zope.traversing.interfaces import ITraversable >>> from zope.traversing.namespace import resource >>> zope.component.provideAdapter( ... resource, (None,), ITraversable, name=”resource”) >>> zope.component.provideAdapter( ... resource, (None, None), ITraversable, name=”resource”)
# New absolute URL adapter for resources, if available >>> import zope.app.publisher.browser.resource >>> if hasattr(zope.app.publisher.browser.resource, ‘AbsoluteURL’): ... zope.component.provideAdapter( ... zope.app.publisher.browser.resource.AbsoluteURL)
# Register the “submit.png” resource >>> from zope.app.publisher.browser.resource import Resource >>> testing.browserResource(‘submit.png’, Resource)
Now the attribute can be called:
>>> imgSubmitAction.src
u'http://127.0.0.1/@@/submit.png'