Developing Forms (Classic UI) developing-forms-classic-ui

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

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

• Optionally:

  • 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:

1. Add fields so that the author can edit the forms dialog once the action is chosen.

In the folder create either:

1. A post script.

   The name of the script is post.POST.<extension>, e.g. post.POST.jsp

   The 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.

2. Add a forward script which is invoked when the form is submitted.

   The name of the script is forward.<extension>, e.g. forward.jsp

   This script can define a path. The current request is then forwarded to the specified path.

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.htmlwhere a mail servlet sits.

So:

• 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.

The order of execution for the scripts is:

• Upon rendering the form ( GET):

  1. init.jsp
  2. for all field’s constraints: clientvalidation.jsp
  3. form’s validationRT: clientvalidation.jsp
  4. form is loaded via load resource if set
  5. addfields.jsp while inside rendering <form></form>

• upon handling a form POST:

  1. init.jsp
  2. for all field’s constraints: servervalidation.jsp
  3. form’s validationRT: servervalidation.jsp
  4. forward.jsp
  5. if a forward path was set ( FormsHelper.setForwardPath), forward the request, then call cleanup.jsp
  6. if no forward path was set, call post.POST.jsp (ends here, no cleanup.jsp called)

Again in the folder optionally add:

1. A script for adding fields.

   The name of the script is addfields.<extension>, e.g. addfields.jsp

   An 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.

2. An initialization script.

   The name of the script is init.<extension>, e.g. init.jsp

   This script is invoked when the form is rendered. It can be used to initialize action specifics. ``

3. A cleanup script.

   The name of the script is cleanup.<extension>, e.g. cleanup.jsp

   This 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.

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

• Optionally:

  • 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 client validation script:

  The name of the script is clientvalidation.<extension>, e.g. clientvalidation.jsp

  This is invoked when the form field is rendered. It can be used to create client javascript to validate the field on the client.

• A server validation script:

  The name of the script is servervalidation.<extension>, e.g. servervalidation.jsp

  This is invoked when the form is submitted. It can be used to validate the field on the server after it is submitted.

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.

For example:

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.