FormControllerMigrationHowTo
Migration to the new FormController
Rename all related Forms and Scripts
Decide which files you want to work on. Create the .cpy, .vpy and .cpt versions of them. The validators should get the .vpy extension, and the controller scripts the .cpy extension. Create the .cpy.metadata and .cpt.metadata files for them as well.
- Convert validators from .py scripts to .vpy scripts. In the script, rename Script (Python) to Controller Validator.
- Convert non-validators from .py scripts to .cpy scripts. In the script, rename Script (Python) to Controller Python Script.
- For all .cpy and .cpt files, create a .cpy.metadata and .cpt.metadata file
In order to be able to test your implementation, make sure to remove the old files.
Make changes to your edit form
Errors are now passed in as a state parameter from the CPT:
tal:define="errors options/state/getErrors;"
A form always has to point to itself, as the logic for the next transition is always depending on the originating Controlled Page Template. The action of the form is always as follows:
tal:attributes="action python:here.absolute_url()+'/'+template.getId()"
Buttons have to follow the following convention:
name="form.button.Change"
Add a Cancel Button where it is useful
Use the following code for the hidden variable:
<input type="hidden" name="form.submitted" value="1" />
Take care that there is a "." now in "form.submitted", where there was a "_" in "form_submitted" before!
Migrate your old settings in Portal Properties
For the next steps, you should have a look at the existing settings for navigation and validation in portal_properties (%s stands for newsitem, link, image, file, event and document.)
portal_properties.form_properties:
%s_edit_form - validate_id,validate_%s_edit
portal_properties.navigation_properties:
default.%s_edit_form.failure - %s _edit_form
default.%s_edit_form.success - script: %s _edit
default.%s_edit.failure - %s _edit_form
default.%s_edit.success - action:view
Translating the old destinations to the new actions:
url:URL - redirect_to
script:SCRIPT_NAME - traverse_to
PAGE - traverse_to
action:ACTION_NAME - redirect_to_action
The 4 new actions:
traverse_to: traverses to a page/method
Equivalent to: PAGE and script:SCRIPT_NAME
traverse_to_action: looks up an object's CMF action and then does what
traverse_to does
redirect_to: redirects to a page/method
Equivalent to: url:URL
redirect_to_action: looks up an object's CMF action and redirects to it
Equivalent to: action:ACTION_NAME
Settings in the .metadata files
You have to set a validator and an action for all buttons.
Choosing the right action type
Right now there are 4 actions:
- traverse_to (traverses to a page/method),
- traverse_to_action (looks up an object's CMF action and traverses to it),
- redirect_to (redirects to a page/method),
- redirect_to_action (looks up an object's CMF action and redirects to it).
%s_edit_form.cpt.metadata:
[default]<a class="new visualNoPrint" href="http://new.plone.org/events/sprints/castlesprint/wiki/FormControllerMigrationHowTo/createform?page=default" title="create this page">?</a>
title=edit form
[validators]<a class="new visualNoPrint" href="http://new.plone.org/events/sprints/castlesprint/wiki/FormControllerMigrationHowTo/createform?page=validators" title="create this page">?</a>
validators..Change=validate_id,validate_%s_edit
validators..Cancel=
[actions]<a class="new visualNoPrint" href="http://new.plone.org/events/sprints/castlesprint/wiki/FormControllerMigrationHowTo/createform?page=actions" title="create this page">?</a>
action.success..Change=traverse_to:string:%s_edit
action.success..Cancel=redirect_to:string:view
action.failure=traverse_to:string:%s_edit_form
The edit script metadata does not differentiate between context types and buttons, but simply specifies which validators are supposed to have been run before and what to do in case of success or failure or any other state.:
%s_edit.cpy.metadata:
[validators]<a class="new visualNoPrint" href="http://new.plone.org/events/sprints/castlesprint/wiki/FormControllerMigrationHowTo/createform?page=validators" title="create this page">?</a>
validators=validate_id,validate_%s_edit
[actions]<a class="new visualNoPrint" href="http://new.plone.org/events/sprints/castlesprint/wiki/FormControllerMigrationHowTo/createform?page=actions" title="create this page">?</a>
action.success = redirect_to:string:view
action.failure = traverse_to:string:%s_edit_form
Migration of the Validation Script
Change the title "Script (Python)" to "Controller Validator"
The state object is available from the bindings. The script parameter is not commonly used, and comes from the standard Python Script bindings.::
When you use the validation provided by Formulator, you can do the following:
validator = context.portal_form.createForm()
validator.addField('title', 'String', required=1)
errors=validator.validate(context.REQUEST)
for fieldid, error in errors.items():
state.setError(fieldid, error)
You set the errors manually where it is needed:
state.setError(fieldid, error)
You check whether there have been any errors. If so, you return a failure, if everything is ok, return the state as is, which is success by default.:
if state.getErrors():
return state.set(status='failure',
portal_status_message='Please correct the indicated errors.')
else:
return state
You can also bail out at any point doing the following:
return state.set(status='failure',
portal_status_message='Please check an item or items to rename.')
Migration of the edit script:
Change the title "Script (Python)" to "Controller Python Script"
If there goes something wrong in the middle, you can always return a failed state:
return state.set(status='failure',
portal_status_message='You are not allowed to send this link.')
Set the state at the end of the edit script:
return state.set(portal_status_message='Mail sent.')
Remove old templates
Remove the old implementation Files.
Customization of actions and validators
It is possible to customize the actions and validators. Just go to the file in portal_skins, and use the Actions and Validation Tabs to override the actions and validations. The customizations will not be saved in the files themselves, put in the portal_form_controller tool. The tool stores overrides to the default actions and validators specified in .metadata files.