+

Search Tips   |   Advanced Search

Collaborative two-way forms

We can use attributes to customize web-based two-way forms.

The Communication Enabled Applications (CEA) two-way form widget is used to create HTML forms in which two people can collaboratively input text and validate entries. Both users 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.

The reader is the user who is responsible for providing information to the writer. The reader can provide 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.

Two-way form widgets

Any Dijit form widgets and their subclass widgets that are part of a two-way form automatically support two-way editing. A widget supporting two-way editing must have an ID specified. We can specify additional attributes on the widgets to expand their capabilities.

ceaCollabWriteAccess

In a two-way form, fields might exist that only one user should have write access to. For example, a two-way interaction might involve a salesperson who is responsible for submitting the form, designated as the writer, and a customer who is responsible for filling out certain portions of the form, designated as the reader. The reader might be prompted to enter credit card information, for example, in a particular field. This field must not be editable by the writer. To ensure this, 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" />

There might also be input fields that the writer fills out that the reader must not have access to. In this case, 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" />

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

ceaCollabFilter

The ceaCollabFilter attribute is used to specify a JavaScript method used to mask values. This is useful for fields containing sensitive information that only one user should be allowed to see (for example, Social Security numbers). If the attribute has the value default, a default masking function is used that replaces every character of input with an asterisk. Otherwise, the value of the attribute is used to call a method that takes a string (the value of the input field) and is expected to return a masked version of that value.

For example, consider the following JavaScript method, used here as a masking method: 

function mask(value) {
 return "XXXX";
}

We can specify that this masking function be used with a text input field by specifying it in the ceaCollabFilter attribute:

    <input type="text" name="textName" id="textName" value="" size="30" ceadojoType="dijit.form.TextBox" ceaCollabFilter="mask" />

ceaCollabValidation

Two-way form functionality allows for validation to occur on any input field. This means that any change to the input field by one user will require another user to accept or decline the changes. We can submit the form only after all input fields that require validation have been accepted.

By default, the CEA TwoWayForm widget provides for a simple validation widget that appears alongside an input field widget when validation is required. To enable this widget, simply set the value of the ceaCollabValidation attribute on the input field widget to default, for example:

    <input type="text" name="textName" id="textName" value="" size="30" ceadojoType="dijit.form.TextBox" ceaCollabValidation="default" />

In some cases, you might not want to use the default validation widget. We can create our own by subclassing cea.widget.validation.ValidationWidget and overriding methods related to creating, showing, and hiding the validation widget. For more information about how a custom class is implemented, see the JavaScript comments in app_server_root\etc\cea\javascript\ceadojo\cea\widget\validation\ValidationWidget.js.

ceaCollabName

When validation is defined for an input field, an alert notifies the writer when one or more input fields have not been validated by the reader. By default, this alert only lists the input field IDs. If a more descriptive label is needed, use the ceaCollabName attribute on the input field widget, for example:

    <input type="text" name="textName" id="textName" value="" size="30" ceadojoType="dijit.form.TextBox" ceaCollabValidation="default" />

ceaCollabHandleRemoveNotification/ceaCollabHandleShowNotification

When any field in a two-way form changes, the user gets a notification. By default, the field is highlighted, and the appearance of the highlighting is determined by the two-way form CSS (the TwoWayForm.css file referred to earlier in this topic). However, we can change the highlight styling in the following two ways:

  • Change the styling in TwoWayForm.css or, creating a new CSS file that redefines the styles present in TwoWayForm.css

  • Define alternative notification methods

Define alternative notification methods gives you more control over how notifications are presented to the user, if at all. Define two methods, both of which accept a Dijit widget object. The first method is used to control removing the notification, and the second is used to control showing the notification. For example, consider the following JavaScript methods: 

function removeFunc(widget) {
 ceadijit.hideTooltip (widget.domNode);
}
function showFunc(widget) {
 ceadijit.showTooltip ("Value changed", widget.domNode);
}

The alternative notification methods handle showing and hiding a tooltip instead of the default notification method that involves highlighting a field. To use these methods, specify them in the ceaCollabHandleRemoveNotification and ceaCollabHandleShowNotification attributes on the desired input field: 

<input type="text" name="textName" id="textName" value="" size="30"   ceadojoType="dijit.form.TextBox"
 ceaCollabHandleRemoveNotification="removeFunc"   ceaCollabHandleShowNotification="showFunc" />


Related concepts

  • Collaboration Dialog


    Related tasks

  • Implement two-way forms in web applications