Create input forms
We can create forms that prompt the user for input using the Data Page builder to automate the display of input controls and the processing of inputs. Also, because the Data Page builder uses a schema to control its behavior, we can change the form simply by altering the schema that defines the form input.
To create an input form with the Data Page builder:
- Add a page to your model that you will use to display the data. This HTML page can be as simple or as sophisticated as the data or your use cases require.
- Add a Data Page builder call to your model, specifying the page on which to display the data and the variable that contains the data.
- Add a Button builder call (or other action builder that submits the form) and set its Action Type to "Submit form and invoke action," and set its Action to the pageName_NextAction method, where "pageName" is the name of the page on which the Data Page builder call operates.
- Run the model.
The sections below describe each of these steps in detail.
Add an HTML Page to the Model
The Data Page builder inserts the input form at a named location on a page in the model. This page can be as simple as the "page1" page included in the "Main and Page" base model or it can be an imported page that has been created by HTML designer. If the page contains input elements the Data Page builder can map the elements in an XML variable to these inputs. We can also configure the Data Page builder to determine the input fields to display based on a schema associated with the variable or a combination of the input fields defined on the page and the elements defined by the schema.
Using the Data Page Builder to Create a Sample HTML Page for the Form
The Data Page builder also allows you to create a sample HTML page for the input form. We can generate this sample page and then import that generated page into you model. An HTML designer can take this page, re-design according to the project requirements. As long as the designer does not remove or change the named <span /> tag on which the Data Page operates, everything will work.
To create a sample HTML page using the Data Page Builder:
- In the Data Page builder call editor, expand the Advanced inputs section.
- Click on the Create Sample HTML button.
- In the Create Sample HTML dialog, specify a location for the page and click Create.
- The page is not created until you save the builder call. To save the builder call, click Apply or OK in the Data Page builder call editor.
Add the Data Page Builder Call to the Model
Once you have a page on which the Data Page can place (or work with) a form, we need to configure the Data Page builder call to implement the form behavior you want. The Data Page builder can operate on input forms, view-only forms, or forms that mix input and view-only fields. These instructions pertain to creating an input form.
To configure the Data Page builder call to create an input form:
- In the Data Page builder call editor, specify the variable to which you want to save the data. If the inputs are not defined by the HTML page, associate this variable with a schema element that describes the fields to be included in the form.
- Enable the Data Entry radio button for the Page Type input. This prompts the Data Page builder to insert <input /> tags for each element in the data on which the Data Page operates.
- (Optional) Expand the Input Control Settings input section specify values for the inputs. These inputs determine how the page renders input controls.
- Expand the Required Field and Input Validation Settings input section and specify values for the Success Action and Failure Action inputs. Doing so prompts the Data Page builder call to add a DataPageName_NextAction method to the WebApp. You will specify this method as the value for submit control's Action input.
Add a Builder Call to Submit the Form
Like any other HTML form page, the page on which the Data Page builder operates needs to have some UI control that allows the user to submit the form. We can use a Button or Link builder call to add the corresponding control to the page or you could use an HTML Event Action to allow the user to submit the form when they cause a particular HTML event to be fired (for example, clicking on a control or changing the value of a text box).
To add a control that allows the user to submit the form:
- Determine how you want to allow the user to submit the form. This example uses the Button builder as an example. Use the settings for Action Type and Action described here for a Link, HTML Event Action, or Image Button builder.
- Set the Action Type value to "Submit form and invoke action."
- Set the Action value to "DataPageName_NextAction."
To perform any server-side validation, specify the name of that method for the submit control's Action value. In the method that performs the validation, make sure that you call the DataPageName_NextAction method as the last action to perform.
Modify the Input Form
The form generated by the Data Page builder can be modified by in the following ways:
- Changing Field Labels -- In the Data Page builder call, open the Label Translation Settings input group and click the Generate Resource Bundle button. Modify the generated properties file so that each of the listed elements have an appropriate label. See "Setting Labels for Form Fields," for more information.
- Formatting and Validating Form Values -- Use a Data Field Modifier builder call and a "formatter" class to format user input into a "data-friendly" format, translate data into "user-friendly" formats, and perform server-side validation for the submitted inputs. See "Formatting and Validating Form Elements," for more information.
- Controlling the Appearance of the Form -- We can control the appearance of the form by specifying CSS styles in a stylesheet and associating that style sheet with the page on which the form appears. See "Specifying CSS Styles for Form Elements," for more information.
- Altering the Layout of the Form -- Use a Data Field Modifier builder call to hide or change the display orientation of the form elements. See "Altering Form Layout," for more information. To control the display of repeated elements in the form, see "How to Use the Data Column Modifier" for more information.