Forms

Web templates can contain Forms. Capture OnTheGo templates always contain a Form.

To create a Capture OnTheGo template, preferably use a Template Wizard (see Capture OnTheGo template wizards). The Wizard doesn't just add the form, it also adds the necessary Capture OnTheGo form elements (see COTG Elements), style sheets and JavaScript files, and extra pre-made elements.

Adding a Form

This procedure describes how to add a Form element to an existing Web context.

  1. On the Resources pane, expand the Web context and double-click a Web page to open it.

  2. To use the Form Wizard, select the Insert > Form Wizard menu option. The Form Wizard adds a Form to the Web page including the specified fields.
    Alternatively, you can select Insert > Form on the menu to open a dialog that lets you set the Form's properties, validation method and location, but doesn't allow you to specify fields. If you choose this method, skip step 8 and 9 of this procedure and add fields after inserting the Form (see Adding elements to a Form).

  3. Add an ID and/or a class. ID's and classes are particularly useful with regard to variable data (see Personalizing content) and styling (see Styling templates with CSS files).

  4. In the Action field, enter the URL where the form data should be sent. The URL should be a server-side script that can accept form data. The action of a Capture OnTheGo form should specify the Workflow HTTP Server Input task that receives and handles the submitted data. The action will look like this: http://127.0.0.1:8080/action (8080 is Workflow's default port number; 'action' should be replaced by the HTTP action of that particular HTTP Server Input task).The method of a Capture OnTheGo form should be POST to ensure that it doesn't hit a data limit when submitting the form. The GET method adds the data to the URL, and the length of a URL is limited to 2048 characters. Especially forms containing one or more Camera inputs may produce a voluminous data stream that doesn't fit in the URL. GET also leaves data trails in log files, which raises privacy concerns. Therefore POST is the preferred method to use.

  5. Using the the Method drop-down, select whether the form should be sent using the GET or POST method.

  6. Using the next drop-down, select the form's Encryption Type (enctype):

    • application/x-www-form-urlencoded: Default. All characters are encoded before they are sent. Spaces are converted to "+" symbols, and special characters are converted to ASCII HEX values.

    • multipart/form-data: No characters are encoded. This value is required when you are using forms that have a file upload control.

    • text/plain: Spaces are converted to "+" symbols, but no special characters are encoded.

  7. Select a validation method:

    • The Browser validation method leaves it up to the browser to validate the user input. When adding fields to the Form (see the next step) you can only make fields required and set the maximum length as an additional requirement for some fields.

    • Select JQuery Validation to validate using JQuery scripts. This allows you to specify stricter requirements per field and type a different message for each field to display to the user if the input is not valid. This method ensures a more consistent validation as it is browser independent. The necessary JQuery files will be added to the JavaScript folder on the Resources pane when the form is inserted.

  8. Under Fields, click the Add button and click on the desired field type to add a field of that type; see Form Elements.

    A Fieldset is not available in the Form Wizard, because a Fieldset itself can contain multiple different fields. Add the Fieldset after inserting the Form; see Adding elements to a Form.

  9. Double-click each field in the Fields list and change its settings. For an explanation of the settings, see Adding elements to a Form.

  10. The order of the elements in the list under Fields determines in which order the elements will be added to the Form. Use the Move Up and Move Down buttons to change the order of the elements in the list.

  11. Use the Location drop-down to select where to insert the element.

    • At cursor position inserts it where the cursor is located in the template.
    • Before element inserts it before the HTML element in which the cursor is currently located. For example if the cursor is within a paragraph, the insertion point will be before the <p> tag.*
    • After start tag inserts it within the current HTML element, at the beginning, just after the start tag.*
    • Before end tag inserts it within the current HTML element, at the end, just before the end tag.*
    • After element inserts it after the element in which the cursor is currently located. For example if the cursor is within a paragraph, the insertion point will be after the end tag of the paragraph (</p>).*
    • Replace inserts it in place of the currently selected element. (This option is not available when inserting content in a Master Page.)

    * If the current element is located inside another element, use the Elements drop-down to select which element is used for the insertion location. The list displays every element in the breadcrumbs, from the current selection point down to the root of the body.

    Note: HTML has some restrictions as to which types of elements are allowed as children of other elements. For example, a paragraph element is not allowed to have children that are block level elements - like a Div or a Table. If inserting content at the selected location would produce invalid HTML the final result may be different than expected. For example, when you insert a Div into a paragraph, the paragraph gets split in two. This means you end up with two paragraphs with the Div in between.

  12. Close the dialog. Now you can start adding elements to the Form (see Using Form elements, Form Elements, and COTG Elements).

Changing a Form's properties and validation method

Once a Form has been added, you can of course edit its HTML code directly in the Source view of the workspace. Apart from that, there are a number of dialogs to change a Form's properties and validation settings.

Changing a Form's properties

  1. Select the form (see Selecting an element).

  2. On the Attributes pane you can change:

    • The ID and/or class. ID's and classes are particularly useful with regard to variable data (see Personalizing content) and styling (see Styling templates with CSS files).
    • An Action: the URL where the form data should be sent. The URL should be a server-side script that can accept form data (a Workflow process that starts with a Server Input task, for example).
    • A Method: this defines whether the form should be sent using the GET or POST method.
    • An Encryption Type (enctype):
      • application/x-www-form-urlencoded: Default. All characters are encoded before they are sent. Spaces are converted to "+" symbols, and special characters are converted to ASCII HEX values.
      • multipart/form-data: No characters are encoded. This value is required when you are using forms that have a file upload control.
      • text/plain: Spaces are converted to "+" symbols, but no special characters are encoded.

Changing a Form's validation method

In Connect PReS Connect, there are two ways in which a Form's input can be validated:

  • The Browser validation method leaves it up to the browser to validate the user input. When adding fields to the Form (see the next step) you can only make fields required and set the maximum length as an additional requirement for some fields.

  • JQuery Validation validates input using JQuery scripts. This allows for stricter requirements per field and a different message for each field to display to the user if the input is not valid. This method ensures a more consistent validation, as it is browser independent. The necessary JQuery files will be added to the JavaScript folder on the Resources pane when this option is chosen.

To change a Form's validation method:

  1. Right-click on the Form element and choose Validation settings.

  2. Choose a validation type (see above).

  3. Double-click each field in the list to edit their validation settings:

    • Required: Check if the field is required to submit the form. If a field is required but contains no data, a message will be shown to the user.

    • Minimum length: Enter a numerical value for the minimum character length required for this field.

    • Maximum length: Enter a numerical value for the minimum character length accepted for this field.

    • Equal to: Use the drop-down to select another field that is already added to the same Form. The contents of both fields must match for the data to be validated. This is useful for confirmation fields such as for passwords, email addresses etc.

    Which of these options are available depends on the validation method of the form: with Browser validation you can only make a field required and set a maximum length.

Changing a Form's validation in HTML

In HTML, the validation method is stored in the data-validation-method attribute of the <form> element, with the value "browser" or "jquery-validation".
A custom message to be shown when validation of a particular Form element has failed, can be stored in the data-custom-message attribute of the Form element, for example:
<input id="email1" name="email1" data-custom-message="Enter a valid email address." type="email" required="">

Validation in Connect 1.0.0

In Connect 1.0.0, the validation method of the template was stored using the names "standard" and "custom". Standard has changed to "browser" and custom is now "jquery-validation". When you open a template made with that version of the software, the template will be migrated to use the new attribute values for the data-validation-method attribute of the <form> element. The JavaScript file web-form-validation.js will not be migrated: delete that file and then change the Form's validation method to jQuery Validation, as described above. When you click OK, the new version of the web-form-validation.js file will be added.

Submitting a Form

When a form is submitted, by clicking or touching the Submit button, the name and value of form elements are sent to the address that is specified in the Form's action (see Adding a Form or Changing a Form's properties). If the name attribute is omitted, the data of that input field will not be sent at all.

The Form's validation should ensure that the data that the user submits is valid.