JSF Mutable Form Requirements Specification

1. Scope
1.1 Overview
This component provides the ability to alter an HTML form at the client side. The component
does not integrate deeply with JSF, but it does support the alteration of JSF elements (at the
client side). The client side interprets text instructions to hide, show, and change HTML
elements. Hiding and showing is done by adding and removing elements from the DOM tree.
Alteration will only extend to form input elements.

The main initial use of this component will be through AJAX driven events. As an example, a user
may enter a coupon code. The blur event will initiate an AJAX call to verify the coupon code.
The validation result may include some instructions to the Mutable Form component, for instance
hiding or showing a “bonus” JSF panel or other form element.
1.2 Logic Requirements

1.2.1 JavaServer Faces

The component must be implemented as a JavaServer Faces component. Other issues with JSF
are noted as applicable below.
1.2.2 Element Hiding
Any named element within the mutable form must be able to be hidden. Hiding entails removing
the object from the DOM tree (with JavaScript) – it is not sufficient to set the “visible” style.
1.2.3 Element Marking and Reset
When hiding an INPUT or SELECT element, the component must support “marking” the element
for reset. A marked element is set to a specified value – either the default or a user-specified
value – at a component provided JavaScript call. The intention behind this requirement is to clear
hidden fields at page submit; however, the component should not limit hidden element reset to
submit – it may be useful to integrate the reset with a traditional form reset.
1.2.4 Element Showing
Any previously hidden element must be able to be re-inserted into the DOM tree, and thus shown
again.
1.2.5 Element Alteration
There are somewhat different approaches to different HTML elements in terms of operation.
They are enumerated below.
1.2.5.1 Text INPUT Element Alteration
The component must support changing both hidden and shown text INPUT elements.
1.2.5.2 List INPUT Element Alteration
List item selections must be supported.
1.2.5.3 Check/radio INPUT Element Alteration
Check box and radio box items must be supported.
1.2.5.4 Text Element Alteration
Like INPUT elements, named elements such as DIV and SPAN must be able to have their inner
text set.
1.2.5.5 SELECT Element Alteration
Selection by value must be supported.

Confidential ©TopCoder Software, Inc. 2002 Page 1

1.2.6 Initialization
The component must provide a JavaScript call to perform a set of operations at initialization
(page load).
1.2.7 Finalization
The component must provide a JavaScript function to the user that will finalize the form and
prepare the form for submission. This will require reinserting all hidden INPUT/SELECT
elements, so that their values are included in the form post. The reset described in 1.2.3 should
be included in this function.
1.2.8 Element Addressing
JSF elements are not necessarily addressed by their literal names per the JSP source. The JSF
rendering process changes certain element names (such as input elements); for instance a
textbox may be present in the JSP as “firstname”, but will be rendered as “id0:firstname”, based
on the form it is contained within. This component must support a simple user interface to hide
this detail. It is up to the designer to decide the best method to accomplish this task. Acceptable
solutions include, for instance, searching the DOM by postfix, identifying the form name at the top
level, and so forth.
1.2.9 Message Format
Messages to the Mutable Form will be in JSON format. Operations will be in the form of an array;
{ command, id [, value, …] }. For instance, to show “firstname”, the command would be { “show”,
“firstname” }. To set the value of that same field, the command would be { “set”, “firstname”,
“Greg” }. To select some values in a select box, the command would be { “select”, “state”, “FL”,
“AK”, “AL” }.

The command naming is up to the designers discretion, but the goal is to make the messaging
easy to be read and understood by humans. The message format is relatively flexible, but please
post to the forum before making any significant changes. The messaging format should be JSON
compatible for easy interoperability with other JSON aware applications.
1.3 Required Algorithms
The basic algorithm for managing elements at the client side must be included with the design.
1.4 Example of the Software Usage
A user registration form uses the mutable form to dynamically adjust its interface with the client,
without requiring a full page round trip. For instance, when the user selects P.O. Box, the P.O.
Box section of the form can be shown, and the street address can be hidden.
1.5 Future Component Direction
No future direction at this time. Potential enhancements would be to use more complex
operations or mutations.
2. Interface Requirements
2.1.1 Graphical User Interface Requirements
The component itself has no user interface, but the effects of this component should be visible to
the user. Hidden elements must leave no indication of their state, from the literal user view, and
shown elements should be identical to their state before being hidden.
2.1.2 External Interfaces
The required external interfaces are detailed above. They include:
• Message format
• Initialize call
• Finalize call

Confidential ©TopCoder Software, Inc. 2002 Page 2

 • Reset call
2.1.3 Environment Requirements
• Development language: Java1.4
• Compile target: Java1.4
2.1.4 Package Structure
com.topcoder.web.ui.jsf.form.mutable
3. Software Requirements
3.1 Administration Requirements

3.1.1 What elements of the application need to be configurable?

None.
3.2 Technical Constraints

3.2.1 Are there particular frameworks or standards that are required?

• JSF 1.2
3.2.2 TopCoder Software Component Dependencies:
None.
**Please review the TopCoder Software component catalog for existing components that can be
used in the design.
3.2.3 Third Party Component, Library, or Product Dependencies:
• Browsers: IE5.5, IE6.0, FireFox 1.5, Netscape 7.0
• MyFaces 1.1.1+ (JSF 1.2)
• Facelets 1.0.8+
• Dojo 0.3+ (should be used for DOM manipulation)
3.2.4 QA Environment:
• RedHat Linux 7.1
• Windows 2003
3.3 Design Constraints
The component design and development solutions must adhere to the guidelines as outlined in
the TopCoder Software Component Guidelines.
3.4 Required Documentation

3.4.1 Design Documentation

• Use-Case Diagram
• Class Diagram
• Sequence Diagram
• Component Specification
3.4.2 Help / User Documentation
• Design documents must clearly define intended component usage in the ‘Documentation’ tab
of Poseidon.

Confidential ©TopCoder Software, Inc. 2002 Page 3