Data Page Builder

Data Page Builder

In this topic ...

Specifying Inputs
Using Java Beans
Managing Validation

Related Topics ...
Overview: Creating Forms
Example: Simple Forms
Displaying Data
Overriding Settings with Page Automation Properties
Creating Input Forms
Techniques for Data Entry Validation
Using Your Own HTML Form Pages
Specifying CSS Styles for Form Elements
Setting Labels for Form Fields
Standard Formatter Behavior

The Data Page builder creates a structure based on the XML data in a variable and renders this structure as a form (both input and display) on a page. The structure created by the Data Page describes the data to be displayed as well as how to render the data on the form. A schema associated with the data on which the Data Page operates can determine how the data gets displayed as can the HTML page associated with the Data Page.
To alter the form display and behavior further, use a Data Field Modifier Builder to control how the form handles specific elements in the data.
Use the Data Page Builder to create forms that either display data, prompt the user to enter data, or are a combination of the two.
Typically, Data Page is used to display the results of a service call or SQL statement or to create input forms based on an element type defined by a schema and an associated variable.

Specifying Inputs

The Data Page builder takes the inputs described in the table below. For help on inputs common to many or all builders such as those in the Properties and HTML Attributes input groups, see "Using the Builder Call Editor"

Input Name Description
Name Enter a name for this builder call. The Designer displays this name in the Builder Call List.
Variable Specify the variable that contains or returns the data. For example, to specify the results of a service call, use the following indirect reference:
Variables/ServiceCallName_reply
Use the Variable/Schema chooser to specify one of the following as the variable:

Schema typed variable
Xml typed variable
A schema
Create New Variable From HTML/From Input Elements
Create New Variable From HTML/From Input and Empty Span Elements
A variable name with a wildcard

The Data Page builder support Java Beans. If the Variable supplied is of type Object, or a Linked Java Object not of type java.lang.XX (excluding java.lang.Object), Data Page will inspect that Bean class (or Collection of such) and display the related inputs (See below).
Page in Model Choose the page in the model that will be used to display the elements in the variable.
Page Type Specify how elements in the variable will be displayed on the form:

Infer from HTML -- Choose this type to allow the HTML page to determine whether an element will be displayed as a form input or a read-only field. The Data Page Builder will read the HTML directive of the field (input_<field_name>) to determine the field type.
Data Entry -- Choose this type to display elements from the variable as form inputs.
View Only -- Choose this type to display elements from the variable as read-only fields on the page.

Bean Settings
Object Handling If the source Variable is of type Object, this builder input will appear to allow the user to specify how the runtime object is to be treated. Options are:

toString - This option will avoid Bean functionality and treat the objects as Strings in "traditional" Data Page fashion.
Bean - Select this option to specify the Variable will hold a single Bean at runtime
Collection of Beans - Use this option to specify that the Variable will hold a Java object of a type that extends Collection or Iterator.

The actual Bean classname being used is specified in the next builder input. If the source variable is of a type that extends java.util.Collection or java.util.Iterator then Collection is implied and this input is not presented.
If the source variable is not java.lang.XX and is not one that extends java.util.Collection or java.util.Iterator then a Bean class is assumed and neither this builder input nor the Object handling builder input will be displayed.
Java Class Name This input is displayed if the source Variable is of type Object or a type that extends Collection or Iterator.
Use this input to specify the real Bean classname so the underlying Data Page functionality can introspect the class and determine available attributes, setters, etc.
Example: com.bowstreet.qa.beans.OrgChart
If the source variable is not java.lang.XX and is not one that extends java.util.Collection or java.util.Iterator, a Bean class is assumed and neither this builder input nor the Object handling builder input will be displayed.
Created Element Settings (Only apply to surplus elements in the schema)
Make UI from Data If checked, any tags which do not match existing HTML elements will be added.
The Following three inputs are displayed when this input is enabled:
Location for New Tags Available when "Make UI from Data" is enabled.
Location on the page where any new tags to be constructed should go.
HTML Template File Select an HTML Page Automation template file that will be used to generate all pages in the application.
Click here for information about using HTML Page Automation templates.
When an HTML Template files is in use, a number of inputs that have to do with HTML class name generation will not be displayed.
Generate Labels Available when "Make UI from Data" is enabled.
If checked, labels will be generated along with the UI control for the element.
Add Names to HTML Available when "Make UI from Data" is enabled.
Determines whether or not the generated HTML elements will be assigned names. We can choose:

Add Names - To automatically assign element names
Leave elements nameless - No names will be assigned

Names are helpful if you want to add additional builders to modify the look and behavior of various elements.
Input Control Settings (Does not apply to View Only pages)
Clear data before saving Enable this checkbox if you want the variable containing the form input values to only contain those values specified on the form. If the variable contains data, the Data Page builder call removes that data from the variable, prior to storing the input values.
Infer Control from HTML If checked, the input type will be inferred from the HTML.
Enumerated Controls What should be the default type for enumerated controls (Select, Radio, etc.) that are not inferred from the HTML.
Enumerated Options Specify whether the options for enumerated control types should be determined by the schema, the HTML file, or a combination of both.
Initialize Inputs Use this input if you have data field modifiers that assign an initial value to one or more fields and you want to control initialization.
We can choose one of the following to control when the initialization method is called:

On model load - Default behavior. initialization method runs when page is loaded.
On page load (except for validation errors) - If no validation errors exist when page is loaded, initialization method will be run. Useful when working with a multi-page new-record creation form.
Never - Initialization method is never automatically called. Method (pagename_initialize) is automatically generated, but call it manually.

Required Fields and Input Validation Settings
Validate From Schema Use the type, required, and other schema information to determine whether input values are valid.
Post-Save Method Use this input if you have additional work that you want your code to do after the data is saved from RequestInputs back into your Variable. A Post-Save method can be a hook for you to add your own Java code for this process.
We can add error messages for individual fields in you Post-Save method and control whether or not the Post-Save method is called when other fields have already failed validation.
Post-Save Method Behavior Choose the behavior of the post-save method invocation. We can choose to:

Always call post save method - Method called regardless of validation outcome
Call Post-save only if all fields were valid - Method called when validation is successful

Success Action Choose the page, method, or other model action to execute when all input values are validated.
These entries are used in creating the method inputPage_NextAction, which we can see in the WebApp view. This method tests to see if there were any validation errors for the page and then calls the appropriate action.
Failure Action Choose the page, method, or other model action to execute when input values are invalid. Typically, you want to set this to the action that displays the form. If you have configured the form to display error messages, these will be displayed as well.
If you leave "Failure Action" empty the default failure action is to return to the same page.
Full Error Location Enter the named location (<span /> tag) at which you want the general error message to appear.
Required (*) Placement Choose where to display the Required Prompt Text in relation to the field.
Required Prompt Text Enter a character to denote a required field. The default prompt is *.
Label Translation Settings
Localized Resource This input is available when a Localized Resource Builder is present in the model and positioned above the Data Page builder in the Builder Call List.
Use this input to specify the localized resource to use with this Data Page Builder. We can choose:

Add New localized resource to WebApp - Select this to specify a new resource bundle file to be used by this Data Page Builder.
LocaleData - Select this to use localization information specified in the Localized Resource Builder and stored in the Variable created by that builder. (By default this Variable is named "LocaleData," but that name can be changed.)
Other Data Page Builder Name - Additional selections will be available when other Data Page Builders are present in the model. Select one of these choices to use a resource bundle created by one of these Data Page Builders.

When specifying a Column Heading Resource Key, make sure the key contains only legal XML characters. For example, underscores are allowed in a key name but dots (.) are not.
Create Resource Bundle This input is available when Add New localized resource to WebApp is selected as the Localized Resource above.
Click the Create Resource Bundle button to create a properties file that contains the label name and default value for each element used in the form.
We can use this generated property file as the basis for creating the final resource bundle used by this page.
Be sure that the name you enter for the properties file includes the .properties extension.
Resource Bundle Name Enter the fully-qualified name of the property file or Java class that serves as the default Resource Bundle. For example, enter com.acme.LabelResources for the property file stored as, WEB-INF/work/source/com/acme/LabelResources.properties
Resource Key Prefix This input is available if you are using a Resource Bundle, either by specifying one directly in the input above, or by referring to a Localized Resource Builder in the model.
This input allows you to have a single resource bundle for an entire Model, or even several models, while avoiding name conflicts. Enter a prefix to be placed before existing element names when applying that name to the resource bundle, and all elements generated by this Data Page Builder will incorporate that prefix into their names.
Example:
If the value in this input is "DP3_" ,and one of the elements generated by this Data Page Builder is "CUSTOMER", the Resource Key that this Builder will use in the resource bundle will be "DP3_CUSTOMER."
Another Data Page Builder in the model can also generate an element named "CUSTOMER," and use the same resource bundle and access a non-prefixed resource key for CUSTOMER while avoiding a name conflict.
Translate HTML-based labels Enable to support translation of label text in HTML content. The localization resource specified above will be used as the basis for translation.
Advanced
Create Sample HTML Click the Create Sample HTML button to create an HTML page based on the elements in the variable and the Page Type you specified. The Data Page builder saves the generated HTML file to the directory you specified when you click OK or Apply in the Data Page builder call editor.
We can use this generated page to provide an HTML designer with a start to the final HTML page. Import the generated page into the model by using an Imported Page builder call.
Create Sample HTML adds class names to certain types of fields. See HTML Class Settings in Data Field Modifier help to view a list of classes and the builder inputs that control the naming of them.
Relative URLs (such as those used to define images) imported during the course of this builder's operation will be converted to absolute URLs. This might preclude the use of images in certain situations.
Disable Submit Event Enable this check box to prevent the builder from running a submit event and saving data.
You might want to disable this feature to allow an external event provided by the caller to determine control flow and resulting save behavior.

Using Java Beans

If the Variable supplied is a Variable typed as "Object", the Bean Settings input group will be displayed. The "Object handling" input allows you to specify that the runtime object will be a Java object that has attributes retrievable and settable with Bean-style getter and setter methods. Another option on "Object handling" allows you to specify that a Collection of beans will be in the Variable at runtime.
When working with Java beans, use the "Java class name" input to identify the actual classname of the bean. The builder will use this classname to inspect the bean and construct a UI for the Bean or Collection of Beans, much as it would for Schema-typed XML variables.

Managing Data Entry Validation

There are a variety of techniques we can use to manage the validation of user input to a page crated by Data Page. See the help topic Techniques for Data Entry Validation for a broad-ranging discussion of and examples of these validation techniques.

Input Name	Description
Name	Enter a name for this builder call. The Designer displays this name in the Builder Call List.
Variable	Specify the variable that contains or returns the data. For example, to specify the results of a service call, use the following indirect reference: Variables/ServiceCallName_reply Use the Variable/Schema chooser to specify one of the following as the variable: Schema typed variable Xml typed variable A schema Create New Variable From HTML/From Input Elements Create New Variable From HTML/From Input and Empty Span Elements A variable name with a wildcard The Data Page builder support Java Beans. If the Variable supplied is of type Object, or a Linked Java Object not of type java.lang.XX (excluding java.lang.Object), Data Page will inspect that Bean class (or Collection of such) and display the related inputs (See below).
Page in Model	Choose the page in the model that will be used to display the elements in the variable.
Page Type	Specify how elements in the variable will be displayed on the form: Infer from HTML -- Choose this type to allow the HTML page to determine whether an element will be displayed as a form input or a read-only field. The Data Page Builder will read the HTML directive of the field (input_<field_name>) to determine the field type. Data Entry -- Choose this type to display elements from the variable as form inputs. View Only -- Choose this type to display elements from the variable as read-only fields on the page.
Bean Settings
Object Handling	If the source Variable is of type Object, this builder input will appear to allow the user to specify how the runtime object is to be treated. Options are: toString - This option will avoid Bean functionality and treat the objects as Strings in "traditional" Data Page fashion. Bean - Select this option to specify the Variable will hold a single Bean at runtime Collection of Beans - Use this option to specify that the Variable will hold a Java object of a type that extends Collection or Iterator. The actual Bean classname being used is specified in the next builder input. If the source variable is of a type that extends java.util.Collection or java.util.Iterator then Collection is implied and this input is not presented. If the source variable is not java.lang.XX and is not one that extends java.util.Collection or java.util.Iterator then a Bean class is assumed and neither this builder input nor the Object handling builder input will be displayed.
Java Class Name	This input is displayed if the source Variable is of type Object or a type that extends Collection or Iterator. Use this input to specify the real Bean classname so the underlying Data Page functionality can introspect the class and determine available attributes, setters, etc. Example: com.bowstreet.qa.beans.OrgChart If the source variable is not java.lang.XX and is not one that extends java.util.Collection or java.util.Iterator, a Bean class is assumed and neither this builder input nor the Object handling builder input will be displayed.
Created Element Settings (Only apply to surplus elements in the schema)
Make UI from Data	If checked, any tags which do not match existing HTML elements will be added. The Following three inputs are displayed when this input is enabled:
Location for New Tags	Available when "Make UI from Data" is enabled. Location on the page where any new tags to be constructed should go.
HTML Template File	Select an HTML Page Automation template file that will be used to generate all pages in the application. Click here for information about using HTML Page Automation templates. When an HTML Template files is in use, a number of inputs that have to do with HTML class name generation will not be displayed.
Generate Labels	Available when "Make UI from Data" is enabled. If checked, labels will be generated along with the UI control for the element.
Add Names to HTML	Available when "Make UI from Data" is enabled. Determines whether or not the generated HTML elements will be assigned names. We can choose: Add Names - To automatically assign element names Leave elements nameless - No names will be assigned Names are helpful if you want to add additional builders to modify the look and behavior of various elements.
Input Control Settings (Does not apply to View Only pages)
Clear data before saving	Enable this checkbox if you want the variable containing the form input values to only contain those values specified on the form. If the variable contains data, the Data Page builder call removes that data from the variable, prior to storing the input values.
Infer Control from HTML	If checked, the input type will be inferred from the HTML.
Enumerated Controls	What should be the default type for enumerated controls (Select, Radio, etc.) that are not inferred from the HTML.
Enumerated Options	Specify whether the options for enumerated control types should be determined by the schema, the HTML file, or a combination of both.
Initialize Inputs	Use this input if you have data field modifiers that assign an initial value to one or more fields and you want to control initialization. We can choose one of the following to control when the initialization method is called: On model load - Default behavior. initialization method runs when page is loaded. On page load (except for validation errors) - If no validation errors exist when page is loaded, initialization method will be run. Useful when working with a multi-page new-record creation form. Never - Initialization method is never automatically called. Method (pagename_initialize) is automatically generated, but call it manually.
Required Fields and Input Validation Settings
Validate From Schema	Use the type, required, and other schema information to determine whether input values are valid.
Post-Save Method	Use this input if you have additional work that you want your code to do after the data is saved from RequestInputs back into your Variable. A Post-Save method can be a hook for you to add your own Java code for this process. We can add error messages for individual fields in you Post-Save method and control whether or not the Post-Save method is called when other fields have already failed validation.
Post-Save Method Behavior	Choose the behavior of the post-save method invocation. We can choose to: Always call post save method - Method called regardless of validation outcome Call Post-save only if all fields were valid - Method called when validation is successful
Success Action	Choose the page, method, or other model action to execute when all input values are validated. These entries are used in creating the method inputPage_NextAction, which we can see in the WebApp view. This method tests to see if there were any validation errors for the page and then calls the appropriate action.
Failure Action	Choose the page, method, or other model action to execute when input values are invalid. Typically, you want to set this to the action that displays the form. If you have configured the form to display error messages, these will be displayed as well. If you leave "Failure Action" empty the default failure action is to return to the same page.
Full Error Location	Enter the named location (<span /> tag) at which you want the general error message to appear.
Required (*) Placement	Choose where to display the Required Prompt Text in relation to the field.
Required Prompt Text	Enter a character to denote a required field. The default prompt is *.
Label Translation Settings
Localized Resource	This input is available when a Localized Resource Builder is present in the model and positioned above the Data Page builder in the Builder Call List. Use this input to specify the localized resource to use with this Data Page Builder. We can choose: Add New localized resource to WebApp - Select this to specify a new resource bundle file to be used by this Data Page Builder. LocaleData - Select this to use localization information specified in the Localized Resource Builder and stored in the Variable created by that builder. (By default this Variable is named "LocaleData," but that name can be changed.) Other Data Page Builder Name - Additional selections will be available when other Data Page Builders are present in the model. Select one of these choices to use a resource bundle created by one of these Data Page Builders. When specifying a Column Heading Resource Key, make sure the key contains only legal XML characters. For example, underscores are allowed in a key name but dots (.) are not.
Create Resource Bundle	This input is available when Add New localized resource to WebApp is selected as the Localized Resource above. Click the Create Resource Bundle button to create a properties file that contains the label name and default value for each element used in the form. We can use this generated property file as the basis for creating the final resource bundle used by this page. Be sure that the name you enter for the properties file includes the .properties extension.
Resource Bundle Name	Enter the fully-qualified name of the property file or Java class that serves as the default Resource Bundle. For example, enter com.acme.LabelResources for the property file stored as, WEB-INF/work/source/com/acme/LabelResources.properties
Resource Key Prefix	This input is available if you are using a Resource Bundle, either by specifying one directly in the input above, or by referring to a Localized Resource Builder in the model. This input allows you to have a single resource bundle for an entire Model, or even several models, while avoiding name conflicts. Enter a prefix to be placed before existing element names when applying that name to the resource bundle, and all elements generated by this Data Page Builder will incorporate that prefix into their names. Example: If the value in this input is "DP3_" ,and one of the elements generated by this Data Page Builder is "CUSTOMER", the Resource Key that this Builder will use in the resource bundle will be "DP3_CUSTOMER." Another Data Page Builder in the model can also generate an element named "CUSTOMER," and use the same resource bundle and access a non-prefixed resource key for CUSTOMER while avoiding a name conflict.
Translate HTML-based labels	Enable to support translation of label text in HTML content. The localization resource specified above will be used as the basis for translation.
Advanced
Create Sample HTML	Click the Create Sample HTML button to create an HTML page based on the elements in the variable and the Page Type you specified. The Data Page builder saves the generated HTML file to the directory you specified when you click OK or Apply in the Data Page builder call editor. We can use this generated page to provide an HTML designer with a start to the final HTML page. Import the generated page into the model by using an Imported Page builder call. Create Sample HTML adds class names to certain types of fields. See HTML Class Settings in Data Field Modifier help to view a list of classes and the builder inputs that control the naming of them. Relative URLs (such as those used to define images) imported during the course of this builder's operation will be converted to absolute URLs. This might preclude the use of images in certain situations.
Disable Submit Event	Enable this check box to prevent the builder from running a submit event and saving data. You might want to disable this feature to allow an external event provided by the caller to determine control flow and resulting save behavior.