Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 1 Getting Started : Tutorial 1: Forms, Panes, and Controls

Tutorial 1: Forms, Panes, and Controls
This tutorial shows how to add panes and controls on a form, and how to move and configure them. This tutorial contains the following tasks:
 
 
Task A: Import the Sample Project
If you have not already done so, install the sample project as previously described in Installing the Forms Tutorial Solutions Project.
Task B: Examine the Claims Process Business Process
The Claims Process business process is used to process an insurance claim for an accident. Examine the process in the Process editor.
Figure 2 Claim Process No Forms: Process Editor
Sample Application: General Description
When you open the sample application Claims Process No Forms, a graphical representation of the business process is displayed in the process editor.
Icons used in the sample application include the following:
A circle icon represents a Start or End Event.
A diamond icon represents a gateway, that is, a point where the process flow is determined by whether or not a certain condition is met.
Task C: Open the Forms
To open the form for a user task, right click the user task and click Form > Open.
The first time a form is opened, a warning pops up to inform you that “The customized form is no longer being automatically kept in sync with the activity interface.” This is because opening a form, rather than simply previewing it, causes the default form to become a customized form. For the tutorials in this chapter, we customize forms rather than using default forms, so ignore the warnings and click OK when you open a given form for the first time.
Open the Capture Claim Form
There are two main tasks displayed in the Capture Claim business process: Capture Claim and Interview Witness.
To compare them in the form editor, open the Interview Witness form the same way you opened the Capture Claim form:
1.
In the Process editor, right-click the Capture Claim task and select Form > Open.
Figure 3 Form Open.
2.
The Capture Claim form in the design view opens, as in Figure 4.
Figure 4 Capture Claim Form, Design Page
There are two tabs on the bottom of the pane, labeled Design and GWT Preview.
The GWT Preview tab is used to see how the form looks like at runtime. For an explanation of the Design tab, which is used for form modeling, and the preview tabs, which are used to preview and test the form, see The Design Tab and Preview Tabs.
3.
Click the GWT Preview tab to see the preview, as in Figure 5.
Figure 5 Capture Claim Form, GWT Preview Page
Open the Interview Witness Form
To generate a form for this user task, do the following:
1.
In the Process editor, right-click the Interview Witness task and select Form > Open.
2.
The Interview Witness form opens in the Form editor, as in Figure 6
 
Figure 6 Interview Witness Form, Design Page
3.
Click the GWT Preview tab to see the preview, as in Figure 5.
Figure 7 Interview Witness Form, GWT Preview Page
4.
form://ProcessPackage/ClaimsProcessNoForms/InterviewWitness/ InterviewWitness.form
Save the process model with this new URL by typing Ctrl+S or clicking Save.
Task D: View Forms
Business processes modeled with TIBCO Business Studio generally include elements called user tasks and gateways. In this task, examine the user tasks and gateways in the sample business process.
User Tasks
The two main user tasks in the sample business process are the Capture Claim task and the Interview Witness task, which differ in the kinds of user task parameters that are associated with some of the fields on these forms.
Capture Claim
The Capture Claim user task captures information about the customer, such as name and phone number, along with information about the accident, such as a description, the time it occurred, and whether any third party was involved. It appears at the beginning of the process, before any data have been collected.
To see the task parameter mode:
1.
Open the Claims Process No Forms in the Process editor.
2.
Select the Capture Claim task.
3.
Figure 8 Capture Claim Form, Interface Properties
If you want to remove any explicitly associated data, select the No interface data association required check box. By default, this option is cleared. If you select this check box, the text in the table below is set to [No Process Data].
You can keep the No interface data association required check box cleared as the user task needs to be associated with the parameters.
The mode for all of the parameters for this user task is Out.
The Capture Claim is the first user task in the business process and has only Outbound Parameters. This is because when the user task begins at runtime, no data is yet gathered for the business process.
Interview Witness
The Interview Witness user task is associated with a form that captures information provided by the witness, including a description of the accident. It is provided with data that were gathered in the Capture Claim form, in addition to having data fields for new information. To see the task parameter mode:
1.
Open the Claims Process No Forms process in the Process editor.
2.
Select the Interview Witness task.
3.
Figure 9 Interview Witness Form, Interface Tab
You can keep the No interface data association required check box cleared.
The interface of the Interview Witness user task includes a mixture of In, Out, and In/Out parameters:
The Inbound Parameters are associated with data that is already specified in the Capture Claim form.
The Outbound Parameters are associated with fields that collect new data on the Interview Witness form.
The Inbound/Outbound Parameters are associated with fields that can be revised on the Interview Witness form from the values that were previously specified on the Capture Claim form.
These parameters provide information gathered on the Capture Claim form that is helpful to the interviewer performing the Interview Witness user task:
The data for these fields appears on the form (in the appropriate form fields) when the Interview Witness form shown in Figure 10 is opened.
4.
Look now at the Interview Witness form detail.
Figure 10 Interview Witness Task, Form Detail
In mode   These parameters are bound on the Interview Witness form to form fields that are disabled for editing. In this tutorial, these fields are:
AccTime (value appears in the Accident Time form field)
AccDescription (value appears in the Accident Description form field)
In/Out mode   These fields are editable and in this tutorial they are:
While their initial values are provided by the Capture Claim user task , the name and phone number of the witness may have changed from what they were when the Capture Claim user task was performed. Because they are In/Out parameters, their current values appear when the Interview Witness form opens, but the interviewer can edit those values if necessary.
Out mode   Two additional user task parameters in the Interview Witness user task are defined as Out mode parameters only are:
WitDescription (Witness Description), which is the witness’s description of the accident to be specified on the form during the interview
WitStatus (Witness Status), which is the status of the witness and is set programmatically based on buttons clicked by the interviewer.
Note how Out mode user task parameters correspond to In/Out mode form parameters. This is necessary to allow the form to be opened and saved multiple times. If the form parameter was Out mode, you would lose the previously typed text if you subsequently reopened the form before marking the work item as complete.
Gateways
In addition to the two user tasks, there are three gateways, indicated by diamond-shaped icons in the process diagram. When a gateway is reached, the flow of the process is determined by the value of a data item. This data item is based on information gathered from user input on the form associated with the user task that precedes the gateway:
The first gateway, after the Capture Claim user task, is determined by the amount of the claim. If the claim is for a sum less than $500, then the process flow continues directly to the End Event. However, if the claim is for $500 or more, then the process flow continues to the next gateway.
The second gateway is based on whether a witness is available to be interviewed; that is, if the Witness Available check box is selected on the Capture Claim form. If so, the process flow continues to the Interview Witness user task. If not, the process flow continues to the End Event.
The third gateway is determined by whether the witness is to be interviewed again. If the interviewer clicks Completed, the process proceeds to the End Event. If the interviewer clicks Failed - Try again, the process returns to the Interview Witness user task. But if attempts to contact the witness have failed repeatedly, the interviewer needs to click Failed - Do not try again, and the business process proceeds to the End Event without the witness’s description having been captured on the form.
For more about how to use gateways in a business process, see TIBCO Business Studio Process Modeling User's Guide.
The tutorials that follow explain how to create two forms. By performing these tutorials, you learn about panes, controls, how to configure their properties, and how to enhance your forms with validation scripts and action scripts.
Task E: Add New Panes to the Capture Claim Form
When forms are first generated, all of the automatically generated controls (corresponding to the user task parameters) appear in a single vertical pane. Creating more panes and moving related controls into each of them helps you organize the information on the form and control its visual layout, enhancing the usability of the form.
In addition to one vertical pane containing all the controls for the user task parameters, the generated form contains a message pane for displaying validation error messages and a horizontal pane for the Cancel, Close, and Submit buttons.
Now we add three new vertical panes in addition to the original vertical pane, and distribute the controls among the four resulting panes as follows:
Customer Information Controls that gather information about the customer making the claim.
Accident Information Controls that gather information about the accident.
Third Party Information Controls that gather information about another person involved in the accident, if any.
Witness Information Controls for capturing contact information for a witness to the accident, if any.
Create a New Pane
To create new panes and redistribute the controls among them, follow these steps:
1.
Click the Design tab for the Capture Claim form on the Form Designer so that the form is visible in the Form Designer.
2.
a.
Figure 11 Show/Hide the Palette
b.
Select Window > Show View... > Palette to open a Palette View that is shared between all open graphical editors.
3.
Click the Vertical Pane item in the palette.
4.
Figure 12 Add New Pane: No Location Selected
5.
Figure 13 Placing a New Pane Above the Existing One
If you click with the mouse over the highlighted drop zone above the current pane, the new pane will be placed above the current pane.
If you click with the mouse over the highlighted area inside the current pane, the new pane will be nested within the current pane.
If you click with the mouse above the current pane without a highlighted drop zone showing up, the new pane will be placed under the current pane.
For this tutorial, click with the mouse in the highlighted drop zone above the current pane.
6.
Repeat step 5 three times.
When panes are added, your form will look as in Figure 14.
Figure 14 Untitled Panes Added
7.
Click the Save icon to save the project.
Task F: Modify Names and Labels of Panes
The values in the Name fields for panes and controls are particularly important and must be typed exactly because they are used in scripts to refer to these objects. Labeling panes to indicate the function of the controls they contain helps users to understand your forms quickly.
Careful labeling at the pane level also allows you to use shorter labels for the controls. For instance, by using the label Customer Information for the pane, you can include controls within it labeled Name and Phone, instead of Customer Name and Customer Phone.
1.
2.
In the Properties View General tab of each of the untitled panes:
Click Rename to type the new names in the Name field, and click Finish.
You can also rename from the Outline view, or canvas context menu, or you can also use the standard F2 accelerator key.
Starting with the top-most pane, use the new names as shown in Table 2.
Table 2 Name Labels
3.
Save the form by typing Ctrl+S or clicking the Save button.
Task G: Drag Controls into Appropriate Panes
Once you have named and labeled the new vertical panes, drag each control to its appropriate pane and position the controls in the order in which they are listed. You can select multiple controls with Shift-Click or Ctrl-Click and drag at once.
Controls are listed below by their default labels; that is, by the text that appears within the control.
Modify these labels in subsequent steps:
1.
Drag the following controls into the Customer Information pane:
a.
b.
c.
d.
e.
f.
g.
2.
Drag the following controls into the Accident Information pane:
a.
b.
c.
d.
e.
3.
Drag the following controls into the Third Party Information pane:
a.
b.
c.
d.
4.
a.
b.
Modify Control Properties: Labels, Required, and Hint Values
The next step is to modify the labels and, in some cases, the Required and Hint properties of the controls by editing values on the controls’ property sheets.
1.
Click the Customer Name control.
On the General tab of the control’s Properties View, change the value in the Label field to Name.
The Required check box is already selected as the parameter CustName is defined as Mandatory at user task interface level.
Figure 15 Customer Name Parameter Defined as Mandatory
2.
Similarly, change the label Customer Phone to Phone.
3.
Add the following text to the Hint field for this control to illustrate the format that our application requires for phone numbers: Example (888) 888-8888.
In a real world situation, the required format for a phone number would be an application-specific requirement.
4.
Change the label for Customer Email to Email.
You want to require that a value be typed for either the Phone or the Email field, but both values will not be required. This functionality is best configured with a script, which will be presented in a later tutorial. You can leave the Required check box cleared for both Phone and Email.
5.
Change the label for Birth Date to Date of Birth.
6.
Make sure that the Required check box is selected, so that a value is required at runtime for this field.
Since you placed the above controls in a pane labeled Customer Information, it is not necessary to repeat the word Customer in the label for each control. This is generally a good practice because it results in a cleaner, easier-to-use form.
7.
Change the label for Customer Age to Age.
8.
The Label and Required properties for the Guardian Name field do not need to be changed. However, you want to add the following text to the Hint field for this control to explain that a guardian’s name must be supplied if the customer is under 21 years old: If age is less than 21.
9.
Change the label for Accident Time to Time of Accident.
Make sure that the Required check box is selected, so that a value is required at runtime.
10.
Change the label for Accident Description to Customer Description.
11.
Change the label for Insurance Name to Insurance Company.
12.
Add the following text to the Hint field for the Witness Phone control to illustrate the format that our application requires for phone numbers: Example (888) 888-8888.
Modify Control Properties: Type and Enabled
In this step, you will modify other properties of selected controls in order to enhance the functionality of the Capture Claim form. The type of control that is generated from user task parameters, for instance, depends upon the type of the data fields from which those parameters are derived. The eight basic types for data fields in TIBCO Business Studio result in the following control types:
Often the generated control types are best, but there are many other control types to consider. In this part of the tutorial, you will change the type of several controls and configure the properties of the new types.
The first control you will modify is Date of Birth, which was generated as a Date-Time control. The customer’s date of birth has a bearing on the insurance claim but the time does not. Therefore, you will change the type for this control from Date-Time to Date.
Changing Control Type
1.
The type of the Age field is Text, which doesn’t need to be changed. But you want the value for this field to be calculated dynamically at runtime based on the value specified for the Date of Birth field. This means that you do not want a value to be typed by the user.
Disabling a Control
To make the field uneditable, clear the check box for the Enabled property for this control.
Figure 16 Making the Field CustAge Uneditable
2.
The type of the Personal Injury field is Text and you will change it to Radiogroup, which ensures that a valid value will be specified, since the value will be chosen from among those you provide.
Click the optionlist for Control Type and select Radiogroup.
3.
For a Radiogroup control the values of the radio buttons must be configured.
On the Properties tab, select auto for Choice Layout.
Figure 17 Add Values and Labels for Personal Injury
4.
Specify the following values and labels, clicking the + (plus) next to each value/label pair once it is specified:
5.
The control type of the Customer Description field is Text. Change it to Text Area in the General tab to allow space for a longer description.
Click the Properties tab of the Properties View and type the values of 4 for Rows and 60 for Columns.
6.
The type of the Insurance Company field is Text and you will change it to Optionlist, to ensure that a user will choose among the names that you provide.
Click the optionlist for Control Type and select Optionlist. For an Optionlist control the values in the list must be configured.
7.
Click the Properties tab for the Insurance Company control and type the following values and labels, clicking the Add button as needed next to the last value/label pair to add space for an additional empty optionlist value:
8.
Modify Pane Properties: Visibility
Sometimes, the usability of your forms can be enhanced if you hide portions that do not apply to certain instances of the business process. If the relevance of a particular set of controls depends on a condition that is determined at runtime, you can place the dependent controls together in a pane and control the Visible property for that pane.
The tutorial will show you how binding can help configure the visibility of third party information pane based on third party involved parameter value. If there is no third party involved in the accident, the form should not show controls for reporting details about it. You will also configure the Witness Information pane to be visible based on whether the Witness Available parameter value is true or false. If no witness is available, the form should not show controls that gather information about the witness.
In this section you will begin configuring this functionality by binding the Visible property of the panes to corresponding parameter values. Binding can be added either from the General tab using the Add Binding icon or from the Mappings tab of the Properties view.
For information about bindings, see Bindings.
Bindings are created automatically between the controls and the parameter values when form is generated; for example, a two-way binding between Customer Name(CustName) parameter value and Name(CustName) control value. When a parameter value changes, the control value is updated automatically, and vice versa.
Setting Visibility of Panes from the General Properties Tab
Set Third Party Information Pane
1.
Click the Third Party Information pane so that its Properties View is displayed.
2.
Click the Add Binding button next to the Visible check box.
Figure 18 Add Binding to Configure Pane Visibility
This will open Create Binding dialog.
3.
Select Create a binding for this property and click Next.
The Select Binding Endpoint page opens.
Figure 19 Select Binding Endpoint Page
4.
Select Third Party Involved (ThirdPInvolved) parameter that will be bound to Visible property of Third Party Information pane.
5.
Click Finish.
Note that the binding icon has changed in the Properties View next to the Visible check box to denote that a binding is present.
Figure 20 Binding Created for the Visible Property
Set Witness Information Pane
6.
Click the Witness Information pane so that its Properties View is displayed.
7.
Click the Add Binding button next to Visible check box.
8.
Select Create a binding for this property and click Next.
9.
Select the Witness Available (WitAvailable) parameter that will be bound to Visible property of Witness Information pane.
10.
Click Finish.
Note that the binding icon has changed to denote that a binding is present.
Setting Visibility of Panes from the Mappings Tab
Perform the following steps to bind the Visible property of the Third Party Information pane to the Third Party Involved (ThirdPInvolved) parameter value using the Mappings tab:
1.
Click the Third Party Information pane so that its Properties view is displayed.
2.
Click the Mappings tab in the selected pane’s Properties view.
3.
In the Mappings tab view, the right pane displays the bindable properties of the selected Third Party Information pane. The left pane displays the bindable source properties to which the target elements are bound. It displays the Third Party Information pane and its ancestors all the way up to the containing form and also includes the form parameters and data fields.
4.
Drag the Third Party Involved (ThirdPInvolved) parameter from the source tree and drop it over the Third Party Information pane’s Visible property in the target tree.
5.
6.
7.
Select is updated by Third Party Involved (ThirdPInvolved) option.
8.
Click Finish.
9.
Figure 21 Adding Binding from the Mappings Tab
Configure the Interview Witness Form
Make the following changes to the Interview Witness form:
1.
2.
Change the new pane’s Name property to witness_info_pane and the Label property to Witness Contact Information.
3.
4.
Change its Name property (root) to accident_info_pane and the Label property to Accident Information.
5.
Drag the following controls from the Accident Information pane to the Witness Contact Information pane: Witness Name and Witness Phone.
6.
7.
8.
Change the type of the Customer Description and Witness Description controls from Text to Text Area. On the Properties tab, specify values of 4 for Rows and 60 for Columns for each.
Add a Button
Add a button to the row of buttons at the bottom of the form.
1.
Select the button type Close in the Palette and drag it and drop between the Close and Submit buttons in the Navigation pane.
Figure 22 Add a Button
Rename Buttons
2.
Cancel    leave as is
Close    Change label into Failed - Try Again
Close  (the new button) Specify label as Failed - Do Not Try Again
Submit   into Completed
With their new labels, the configured buttons should now look like this:
Summary of Tutorial 1
In this tutorial, you learned how to generate forms from user tasks in a business process, organize and rearrange the objects on a form, and configure the panes and controls on the form by modifying their properties on the property views.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved