Developing Forms (Classic UI)
The basic structure of a form is:
- Form start
- Form elements
- Form end
All of these are realized with a series of default Form components , available in a standard AEM installation.
In addition to developing new components for use on your forms you can also:
Using scripts to extend functionality where necessary.
Preloading Form Values
The form start component provides a field for the Load Path , an optional path that points to a node in the repository.
The Load Path is the path to node properties that is used to load predefined values into multiple fields on the form.
This is an optional field that specifies the path to a node in the repository. When this node has properties that match the field names, then the appropriate fields on the form are preloaded with the value of those properties. If no match exists, then the field contains the default value.
A form action can also set the resource from which to load the initial values. This is done using FormsHelper#setFormLoadResource inside init.jsp .
Only if that is not set, will the form be populated from the path set in the start form component by the author.
Preloading Form Fields with Multiple Values
Various form fields also have the Items Load Path , again an optional path that points to a node in the repository.
The Items Load Path is the path to node properties that is used to load predefined values into that specific field on the form, for example, a drop down list , check box group or radio group .
Example - Preloading A Dropdown List with Multiple Values
A drop down list can be configured with your range of values for selection.
The Items Load Path can be used to access a list from a folder in the repository and preload these into the field:
- Create a new sling folder ( sling:Folder )for example, /etc/designs/<myDesign>/formlistvalues
- Add a new property (for example, myList ) of type multi-value string ( String ) to contain the list of drop down items. Content can also be imported using a script, such as with either a JSP script or cURL in a shell script.
- Use the full path in the Items Load Path field:for example, /etc/designs/geometrixx/formlistvalues/myList
Note that if the values in the String are of the formatted like this:
then AEM will generate the list as:
- <option value="AL">Alabama</option>
- <option value="AK">Alaska</option>
This feature can, for example, be put to good use in a multi-language setting.
Developing your own Form Actions
A form needs an action. An action defines the operation that is executed when the form is submitted with the user data.
A range of actions are provided with a standard AEM installation, these can be seen under:
and in the Action Type list of the Form component:
This section covers how you can develop your own form action for inclusion in this list.
You can add your own action under /apps as follows:
- Create a node of type sling:Folder . Specify a name that reflects the action to be implemented.For example:/apps/myProject/components/customFormAction
- On this node define the following properties, then click Save All to persist your changes:
- sling:resourceType - set as foundation/components/form/action
- componentGroup - define as .hidden
- jcr:title - specify a title of your choice, this will show in the drop-down selection list. If not set then the node name is shown
- jcr:description - enter a description of your choice
- In the folder create a dialog node:
- Add fields so that the author can edit the forms dialog once the action is chosen.
- In the folder create either:
The necessary call is FormsHelper#setForwardPath (2 variants). A typical case is to perform some validation, or logic, to find the target path and then forward to that path, letting the default Sling POST servlet do the actual storage in JCR.There could also be another servlet that does the actual processing, in such a case the form action and the forward.jsp would only act as the "glue" code. An example of this is the mail action at /libs/foundation/components/form/actions/mail , which forwards details to <currentpath>.mail.html where a mail servlet sits.So:
- A post script.The name of the script is post.POST.<extension> , e.g. post.POST.jspThe post script is invoked when a form is submitted to process the form, it contains the code that handles the data arriving from the form POST .
- Add a forward script which is invoked when the form is submitted.The name of the script is forward.<extension >, e.g. forward.jspThis script can define a path. The current request is then forwarded to the specified path.
The order of execution for the scripts is:
- a post.POST.jsp is useful for small operations that are fully done by the action itself
- while the forward.jsp is useful when only delegation is required.
- Upon rendering the form ( GET ):
- for all field's constraints: clientvalidation.jsp
- form's validationRT: clientvalidation.jsp
- form is loaded via load resource if set
- addfields.jsp while inside rendering <form></form>
- upon handling a form POST :
- for all field's constraints: servervalidation.jsp
- form's validationRT: servervalidation.jsp
- if a forward path was set ( FormsHelper.setForwardPath ), forward the request, then call cleanup.jsp
- if no forward path was set, call post.POST.jsp (ends here, no cleanup.jsp called)
- Again in the folder optionally add:
- A script for adding fields.The name of the script is addfields.<extension> , e.g. addfields.jspAn addfields script is invoked immediately after the HTML for the form start is written. This allows the action to add custom input fields or other such HTML inside the form.
- An initialization script.The name of the script is init.<extension> , e.g. init.jspThis script is invoked when the form is rendered. It can be used to initialize action specifics. ``
- A cleanup script.The name of the script is cleanup.<extension> , e.g. cleanup.jspThis script can be used to perform cleanup.
- Use the Forms component in a parsys. The Action Type drop down will now include your new action.To see default actions that are part of the product:/libs/foundation/components/form/actions
Developing your own Form Constraints
Constraints can be imposed at two levels:
Constraints for Individual Fields
You can add your own constraints for an individual field (under /apps ) as follows:
- Create a node of type sling:Folder . Specify a name that reflects the constraint to be implemented.For example:/apps/myProject/components/customFormConstraint
- On this node define the following properties, then click Save All to persist your changes:
- sling:resourceType - set to foundation/components/form/constraint
- constraintMessage - a customized message that will be shown if the field is not valid, according to the constraint, when the form is submitted
- jcr:title - specify a title of your choice, this will show in the selection list. If not set then the node name is shown
- hint - additional information, for the user, on how to use the field
- Inside this folder, you can need the following scripts:
- A server validation script:The name of the script is servervalidation.<extension> , e.g. servervalidation.jspThis is invoked when the form is submitted. It can be used to validate the field on the server after it is submitted.
Sample constraints can be seen under:
The form-global validation is specified by configuring a resource type in the start form component ( validationRT ). For example:
You can then define:
- a clientvalidation.jsp - injected after the field's client validation scripts
- and a servervalidation.jsp - also called after the individual field server validations upon a POST .
Showing and Hiding Form Components
You can configure your form to show or hide form components according to the value of other fields in the form.
Changing the visibility of a form field is useful when the field is needed only under specific conditions. For example, on a feedback form a question asks customers if they want product information sent to them in email. Upon selecting yes, a text field appears to enable the customer to type their email address.
Use the Edit Show/Hide Rules dialog box to specify the conditions under which a form component is shown or hidden.
Use the fields at the top of the dialog box to specify the following information:
- Whether you are specifying conditions for hiding or showing the component.
- Whether any or all of the conditions need to be true to show or hide the component.
One or more conditions appear below these fields. A condition compares the value of another form component (on the same form) to a value. If the actual value in the field satisfies the condition, the condition evaluates to true. Conditions include the following information:
- The Title of the form field that is tested.
- An operator.
- A value against with the field value is compared.
For example, a Radio Group component with the title Receive email notifications? * * contains Yes and No radio buttons. A Text Field component with the title of Email Address uses the following condition so that it is visible if Yes is selected:
((contact == "Yes"))
To show or hide a form component:
- Edit the specific form component.
- Select Show / Hide to open the Edit Show / Hide Rules dialog:
- In the first drop down list select either Show or Hide to specify whether your conditions determine whether to show or hide the component.
- In the drop down list at the end of the top line select:
- all - if all conditions must be true to show or hide the component
- any - if only one or more conditions must be true to show or hide the component
- In the condition line (one is presented as default) select a component, operator, and then specify a value.
- Add more conditions if needed by clicking Add Condition .
- Click OK to save the definition.
- After you saved your definition, an Edit Rules link appears next to the Show / Hide option in the form component properties. Click this link to open the Edit Show / Hide Rules dialog box to make changes.Click OK to save all changes.The effects of Show / Hide definitions can be seen and tested:
- in Preview mode on the author environment (needs a page reload when first switching to preview)
- on the publish environment
Handling Broken Component References
Show/hide conditions use the value of the Element Name property to reference other components in the form. The Show/Hide configuration is invalid when any of the conditions refer to a component that is deleted or has had the Element Name property changed. When this situation occurs, you need to manually update the conditions or an error occurs when the form loads.
Developing Scripts for use with Forms
For more information about the API elements that can be used when writing scripts see the javadocs related to forms .
You can use this for actions such as calling a service before the form is submitted and canceling the service if it fails:
- Define the validation resource type
- Include a script for validation:
- In your JSP, call your web service and create a com.day.cq.wcm.foundation.forms.ValidationInfo object containing your error messages. If there are errors, form data will not be posted.