The form fields used in the Action Steps are configured in two different places:
- Use the 'edit schema' tab to define the fields (name, description/help text, field type, validation, size, default value, etc.)
- Use the Layout Elements to place and order the fields on specific pages in the Action Process
Defining the 'Action Fields'
Default 'Action Fields' already exist for any [Action Edition]? you set-up. While these will fit most actions, your action or organisation may require additional fields, fewer fields or the default fields to be different than the original settings.
All fields are grouped into 'schematas'. This is mainly a convenience for grouping different types of fields together, however it also affects the 'sub-section' the fields appears on when manually adding an 'Action Record' (a very rare activity)
To add, remove or modify fields:
Go to the 'edit schemas' tab of your 'Action Edition'. Since the default 'schematas' selected is 'campaigning', under 'fields' you have 'firstname', 'lastname', etc.
Select the 'emailaddress' field. You'll now see it's 'field definition'. The key ones for general use are:
- 'Type': the type of data to be stored
- 'Widget' the style of field to be displayed
- 'Label': the field's label (note: except for special cases, it is better to set this once in the po files. See Multilingual Set-up)
- 'Description' the field's 'description' or 'help' text displayed under the field (note: except for special cases, it is better to set this once in the po files. See Multilingual Set-up)
- 'Default': the default value of the field (usually blank)
- 'Size': the size of the field (note: this can differs depending on field 'type')
- 'Validators': that the submitted data should be validated against
- 'Visible (Edit)': if the field should be editable or uneditable
- 'Visible (View)': if the field should be visible or hidden
- 'Required': if the field is required to be completed or is optional
The 'Storage' feature is not currently used (unless you do custom development for it) and the 'Create index' means the field is indexed in Zope and is not generally needed for 'Action Records'. The up and down arrows next to 'schematas' and 'fields' only change the order in the schema editor, not on the form.
By exploring the different 'fields' and their settings, you should get a sense of how each field's definitions is currently set and how it could be modified.
To add a field, simply select the 'schemata' you wish it to appear under and then type the field name in the box to the left of the '+' sign. Then you'll need to define it according to your needs.
If you want to validate the field, the most useful pre-set validators are:
- isEmail: The argument must be a valid email address.
- isValidDate: The argument must be a Date-Time or a string that converts to a Date-Time.
- isDecimal: The argument must be decimal, may be positive or negative, may be in scientific notation.
- isInt: The argument must be an integer, may be positive or negative.
- isURL: The argument must be a valid URL (including protocol, no spaces or newlines).
You can see detailed documentation on the Schema Editor at: http://dev.plone.org/archetypes/browser/Archetypes/trunk/docs/quickref.rst
To delete a field, simply press the 'x' to the left of the field name.
Placing the 'Action Fields'
The default 'Action Fields' are already placed in either the 'Action Page' or in the 'Address Page'. This is achieved by adding the fields to 'Layout Elements' as 'Field Blocks'. This allows you to determine what part of each page each field will appear on and the order in which it will appear in each 'Layout Element'.
To place, move, remove, or re-order fields:
Select the 'contents' tab of the Action Step you wish to edit to get a list of that various 'Action Elements' including the 'Layout Elements'.
Click on the 'Layout Element' that contains your fields. This will usually be the 'content' Layout Elements (vs. Header of Footer)
You should see a list of fields that display in the Action Step. The order they display is the order they appear on the relevant page.
You use normal Plone functionality to:
- Change the field display order (arrows or drag-and-drop)
- Delete fields from the view
- Cut, past or copy fields between 'Layout Elements'
To add fields simply:
- Select 'Field Block' from the 'add new item' menu
- Select the field name from the drop-down list. A short name does not need to be specified (if this option appears).
- Save, return to contents view and re-order as necessary
Note that:
- All field configuration except for placement and order is set in the 'schema editor'
- A 'Field Block' can not only contain fields from the 'schema editor', but a programmer can also make other content appear in this block using the 'Custom data accessor'
You can mix other content in with the 'Field Blocks' so that you could:
- Make headers and footer within each 'Layout Element' using 'HTML Blocks'
- Include HTML code between fields using 'HTML Blocks'
- Include the 'Target Person' or 'Target Organisation' information in a 'Layout Element'
- Add a before, after or between fields using a 'Link'
You can also add 'Images' within a 'Layout Element' so that it can be referenced in an 'HTML Block'
Adding Dynamic Data in Context
While the above options provide you with the ability to highly customise the design of the Action Process, they all deal with static elements: fields, html, links, etc. Using the functionality of Data Merge and Conditional Blocks in conjunction with 'HTML Blocks', Field Blocka and other Action Edition elements, you can include dynamic, personalised content in each stage of the Action Process.
