You can create and configure two-way forms in Web applications
using the Communications Enabled Applications (CEA) TwoWayForm widget.
Before you begin
Avoid trouble: For a list of restrictions that are
changed based on various service levels of the product, see the topic
What is new in the Feature Pack for CEA.
gotcha
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 Pack are supported.
About this task
The CEA two-way form widget allows 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 form's fields. 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 needed to implement the two-way forms technique
in an existing application. To quickly learn how the two-way forms
technqiue 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 with the Feature Pack for CEA at app_server_root/feature_packs/cea/samples/plantsbywebsphere/documentation/index.html.
Attention: This task lists the steps
needed to implement the two-way forms technique in an existing application.
To quickly learn how the two-way forms technqiue 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 with the Feature Pack for CEA at app_server_root/feature_packs/cea/samples/plantsbywebsphere/documentation/index.html,
as well as the topic Setting up a CEA Feature Pack demonstration environment.
- Copy the CEA widgets into the application you are enhancing.
The CEA widgets are included in the Dojo Toolkit installed
with the CEA Feature Pack at app_server_root/feature_packs/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 in conjunction 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.
- You might see different product versions of the Plants By WebSphere® sample application
installed in your machine environment. Make sure that you install
the edition that comes with the Feature Pack for CEA entitled PlantsByWebSphere
Ajax Edition for CEA (PlantsByWebSphereAjax).
- Different versions of the PlantsByWebSphere sample application
are supplied with the Feature Pack for Communications Enabled Applications
(CEA) and the Feature Pack for Web 2.0. However, the sample application
from these two feature packs cannot coexist on the same application
server. This problem is due to Java™ Naming Directory Interface (JNDI)
name and context root conflicts. To avoid this problem, do not install
both the CEA and Web 2.0 versions of the PlantsByWebSphere sample
application on the same application server.
gotcha