You can create and configure two-way forms in web applications
using the communications enabled applications (CEA) TwoWayForm widget.
Before you begin
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
you can load the two-way form you have developed. You 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.
About this task
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.
Attention: 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, you can install the PlantsByWebSphere Ajax Edition for
CEA (PlantsByWebSphereAjax) sample application. For more information
about the sample application, see the supporting documentation that
is provided in the PlantsByWebSphere directory of the CEA samples
package.
- 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 your application.
- 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>
Note: The path after the context
root can be any path you need. The recommended default is/ceadojo.
- 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>
- 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>
- 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>" />
- 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" />
- 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" />
- 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.
- Optional: If you want to use the onsubmit form
event, you cannot specify the action to run in the onsubmit attribute.
Instead, you must 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, you can test whether
the application is working as intended:
- Browse to a page with the embedded Cobrowse widget.
- Click the Create Invitation Link button.
- Select and copy the URI that is returned in the Invitation
Link field.
- Open a separate browser and paste the invitation link into the
web address field.
- 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.
- Once the page loads, click the Send Page button to load
the two-way form into the second browser.
- 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.
Note: 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.
- 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.
- 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