Implement two-way forms in web applications

We can create and configure two-way forms in web applications using the communications enabled applications (CEA) TwoWayForm widget. Using the two-way form widget requires that you first set up the other widgets (ClickToCall and CallNotification, or Cobrowse) to establish a collaboration dialog (CollaborationDialog) into which we can load the two-way form we have developed. We must use the following libraries to implement the CEA TwoWayForm widget:

• Dojo JavaScript™ library

• Dijit form widget library

Restriction: Only configurations that use these libraries from the Dojo Toolkit included with the CEA feature are supported.

The CEA two-way form widget enables you to create an HTML form in which two people, operating as a reader and a writer, can collaboratively edit and validate fields. Both parties can see the same form. The fields in the form change in response to input provided by either person.

The writer is the user who is responsible for driving the interaction between the two users. In a typical scenario, the writer is usually the customer service representative who is responsible for collecting information from the customer and submitting the form.

The reader is the user who is responsible for providing information to the writer. The reader provides information verbally to the writer, who copies the information into the fields of the form.. Since updates to the fields are visible to the reader, the reader can confirm or validate the correctness of the information. The reader can be prompted to enter sensitive information into the form, such as credit card numbers. Such private information is generally filtered so that the writer cannot see it.

This task lists the steps required to implement the two-way forms technique in an existing application. To quickly learn how the two-way forms technique works in an online application, we can install the PlantsByWebSphere Ajax Edition for CEA (PlantsByWebSphereAjax) sample application. For more information about the sample application, see the supporting documentation provided in the PlantsByWebSphere directory of the CEA samples package.

1. Copy the CEA widgets into the application you are enhancing.

   The CEA widgets are included in the Dojo Toolkit installed at app_server_root/etc/cea/javascript. Copy the ceadojo directory into the WebContent directory of the application.

2. Import the TwoWayForm widget. Add the following JavaScript code to import the Dojo Toolkit included with the CEA widgets. For the purposes of this procedure, the contextRoot is the context root of the application. For example, an application that is accessed with the URL http://localhost:9080/MyApp will have a context root of MyApp. The following code is required to import the two-way form widget:

   <script type="text/javascript" src="<contextRoot>/ceadojo/dojo/dojo.js"
    djconfig="parseOnLoad: true, isDebug: false"></script>

   The path after the context root can be any path we need. The recommended default is/ceadojo.

3. Optional: If the page is already using a version of Dojo add the following JavaScript code instead of the previous step to enable multiple versions of the Dojo on the same page. See the reference information on multiple versions of Dojo on a page.

   <script type="text/javascript">
       var djConfig = { baseUrl:"<contextRoot>/ceadojo/dojo/" };
   </script>
    <script type="text/javascript" src="<contextRoot>/ceadojo/dojo/dojo.js"></script>

4. Import the two-way-form widget CSS definitions. The following code is required to import the two-way form widget CSS:

   <style>
    @import "<contextRoot>/cea/widget/TwoWayForm/TwoWayForm.css";
   </style>

5. Create a <form> element and indicate that it is a two-way form by declaring the type cea.widget.TwoWayForm and specifying an ID, as follows:
   <form ceadojoType="cea.widget.TwoWayForm" name="<formName>" id="<formID>" />

6. Optional: To prevent fields from being editable by the reader, specify the input field setting for the ceaCollabWriteAccess attribute to writer:
   <input type="text" name="textName" id="textName" value="" size="30" ceadojoType="dijit.form.TextBox" ceaCollabWriteAccess="writer" />

7. Optional: To prevent fields from being editable by the writer, specify the input field setting for the ceaCollabWriteAccess attribute to reader:
   <input type="text" name="textName" id="textName" value="" size="30" ceadojoType="dijit.form.TextBox" ceaCollabWriteAccess="reader" />

8. Optional: To enforce validation of any changed fields, set the value of the ceaCollabValidation attribute on the input field widget to default.
   <input type="text" name="textName" id="textName" value="" size="30" ceadojoType="dijit.form.TextBox" ceaCollabValidation="default" />

   Important: Use this attribute with the ceaCollabWriteAccess attribute to ensure that only one user can change a particular field; thereby preventing both users from being able to validate the same field.

9. Optional: To use the onsubmit form event, we cannot specify the action to run in the onsubmit attribute. Instead, specify the action in the ceaCollabOnSubmit attribute, as in the following example:
   <form ceadojoType="cea.widget.TwoWayForm" name="<formName>" id="<formID>" ceaCollabOnSubmit="return myAction()" />

Results

You have created a two-way form that can be used interactively by two users to capture information. After you install and start the updated application containing the two-way forms, we can test whether the application is working as intended:

1. Browse to a page with the embedded Cobrowse widget.

2. Click the Create Invitation Link button.

3. Select and copy the URI returned in the Invitation Link field.

4. Open a separate browser and paste the invitation link into the web address field.

5. From the first browser, within the modal window, enter the URL to the page containing the newly created two-way form into the location bar and click enter.

6. Once the page loads, click the Send Page button to load the two-way form into the second browser.

7. The first browser is the writer and will be able to edit all fields with writer access. Make changes to the fields and verify that the changes are reflected in the second browser's form.

   The first browser is the writer and the second is the reader. Whenever the form is loaded, whichever browser is controlling collaboration becomes the writer. The passive peer then becomes the reader.

8. The second browser is the reader. Click the accept checkmark for all fields that are enabled for validation. Verify that the status of the accepted fields is updated in the first browser.

9. To end, exit either modal window, and click the End Collaboration button.

Avoid trouble:

• When you test the widgets, use two completely separate browsers, or the same browser on two separate machines. Using tabs in the same browser, or even launching separate instances of the same browser on the same machine, will cause session issues.

gotcha

Related concepts

Collaborative two-way forms

Collaboration Dialog

Related tasks

Collaborating and cobrowsing in web applications

Making phone calls in web applications

Receiving call notifications in web applications

Samples documentation