Using JSP Form Control Templates

This chapter provides overviews of form control templates; properties, parameters, and attributes; and form control templates, and discusses how to:

• Use configuration form control templates.

• Specify the model and locale properties for the solution.

• Application page example.

• Configure a form control template.

• Register custom form control templates.

• Custom form control template example.

• Common errors.

Understanding Form Control Templates

Each decision point in the model maps to a selection point for the client and can be implemented by an HTML form control. This chapter describes the configurator templates for the form controls that are supported in the Configuration Client, which is the midtier application. A form control template is a separate Java Server Page (JSP) page that generates a form control, using the selection point data, for a web page. Configurator provides a JSP template file for each type of form control.

Your application JSP pages can contain form controls if you include their corresponding form control templates.

Note. All form control templates, Configurator-specific related scriptlets, and Java code should be inserted between the inclusion of the CalicoStartFormInc.jsp and CalicoEndFormInc.jsp processor pages. The JSP initializing method, jspInit(), must precede CalicoStartFormInc.jsp.

You can modify the appearance and behavior of the form control display in the following ways:

• Application scope: Modifying the definitions of display properties in a configuration file that an application page passes to the form control templates.

• Form control scope:

  • Setting parameters in the application pages.

  • Configuring a Configurator template: Extending the form control template by copying the JSP template, modifying that copy, and saving it as a configured template file that you can include in the application pages.

With the existing Configurator form-control templates, you can set either the HTML-level display properties, such as the text color of the display data and selection state of the form control item, or configure the presentation of the data of the form control.

You can specify the data display in the form control to:

• Display domain member attribute information.

• Sort the form control items.

• Eliminate form control items of eliminated domain members.

• Eliminate the form control items of the eliminated domain members whose elimination levels are beyond an inclusionary range.

• Display delta pricing and the total price.

Understanding Properties, Parameters, and Attributes

The presentation of a form control is determined by the display properties of the HTML for the application, by the included display properties and data of the HTML for the form control and its data, and by the display attributes of the domain member of the decision point.

Properties

The properties for a form control are the configurable display characteristics of the form control items that present their selection states and their delta pricing. All form controls properties are located in the CalicoUI.properties file. These properties are available application-wide, but to be used by a form control, they must be passed to the form control as parameters.

Parameters

The parameters for a form control are both HTML and data presentation characteristics that your application pages pass to included form control templates. Typically, the properties are passed to the templates as parameter values.

Attributes

The attributes for a form control are determined by the attributes in the model for the domain members. Typically, the attributes are passed to the templates as parameter values. Use the PARAM_ATTRIBUTES parameter to display the data for the specified attributes.

Understanding JSP Code Templates

PeopleSoft Advanced Configurator provides a JSP code template for all HTML-compatible form controls. This section describes the usage and behavior of each. JSP code and the HTML output is located in the referenced appendix for each.

Note. The filenames for the form control templates are in mixed case, that is, SingleSelectGroup.jsp. For the deployments running on Solaris systems, make sure the characters of the filename match correctly (case-sensitive) with the template filenames.

Single-Select Group

The single-select group form control SingleSelectGroup.jsp consists of a list of form control items, of which only one can be chosen. If one item in a list is selected, any previously selected item in the same list is deselected. The items of a form control are displayed as radio buttons.

You can create the following single-select group form control for the decision point OSSelection, with the caption Operating System, and the Generate None option.

The following code generates the previous form control:

<!-- METADATA TYPE="CalicoControl" startspan-->
<%
	if (params != null)
	{
		params.clear();
		params.put(PARAM_OBJECTNAME, "[MyComputerConfig].OSSelection");
		params.put(PARAM_ATTRIBUTES, "Desc");
		params.put(PARAM_CONTROLID, "OSSelectionCtrl");
		params.put(PARAM_CAPTION, "Operating System");
		params.put(PARAM_GENERATENONEMODE, "1");
		params.put(PARAM_GENERATENONETEXT, "None");
		generateSingleSelectGroup(params, request, out);
	}
%>
<!-- METADATA TYPE="CalicoControl" endspan -->

See Single-Select Group Form Control.

MultiSelect Group

A multiselect group form control consists of a list of form control items, of which more than one item can be chosen. The items of a form control are displayed as check boxes. Each item can be either selected or deselected.

You can create the following multiselect option group form control for the decision point CDSelection with the caption Multimedia.

The following code generates the control in the figure:

<!-- METADATA TYPE="CalicoControl" startspan-->
<%
	if (params != null)
	{
		params.clear();
		params.put(PARAM_OBJECTNAME, "[MyComputerConfig].CDSelection");
		params.put(PARAM_ATTRIBUTES, "Desc");
		params.put(PARAM_CONTROLID, "CDSelectionCtrl");
		params.put(PARAM_CAPTION, "Multimedia");
		generateMultiSelectGroup(params, request, out);
	}
%>
<!-- METADATA TYPE="CalicoControl" endspan -->

See Multi-Select Group Form Control.

Single-Select List

A single-select list form control consists of form control items in a drop-down list, of which only one can be chosen. It’s similar in functionality to a single-select group form control, but it requires less form control space for the display.

The StateTag indicates the domain member state of the form control item in the drop-down list. The following table shows the default text symbols that are used to connote the domain member states:

Note. You can configure these state tags by modifying the property values in the CalicoUI.properties file, which is located in your application directory.

You can create the following single-select list form control for the decision point OSSelection with the caption Operating System and the None option.

The following code generates the form control in the figure:

<!-- METADATA TYPE="CalicoControl" startspan-->
<%
	if (params != null)
	{
		params.clear();
		params.put(PARAM_OBJECTNAME, "[MyComputerConfig].OSSelection");
		params.put(PARAM_ATTRIBUTES, "Desc");
		params.put(PARAM_CONTROLID, "OSSelectionCtrl");
		params.put(PARAM_CAPTION, "Operating System");
		params.put(PARAM_GENERATENONEMODE, "1");
		params.put(PARAM_GENERATENONETEXT, "None");
		generateSingleSelectList(params, request, out);
	}
%>
<!-- METADATA TYPE="CalicoControl" endspan -->

See Single-Select List Form Control.

Multi-Select List

A multi-select list form control consists of form control items in a list, of which more than one item can be chosen. To select or deselect more than one item, a user presses the Ctrl/Shift keys and clicks the subsequent items to select them or clicks (selected items) to deselect them.

The StateTag indicates the domain member state of the form control item in the drop-down list. The following table shows the default text symbols that are used to connote the domain member states:

Note. You can configure these state tags by modifying the property values in the CalicoUI.properties file, which is located in your application directory.

You can create the following multiselect list form control for the decision point CDSelection with the caption Multimedia.

The following code generates the previous form control:

<!-- METADATA TYPE="CalicoControl" startspan-->
<%
	if (params != null)
	{
		params.clear();
		params.put(PARAM_OBJECTNAME, "[MyComputerConfig].CDSelection");
		params.put(PARAM_ATTRIBUTES, "Desc");
		params.put(PARAM_CONTROLID, "CDSelectionCtrl");
		params.put(PARAM_CAPTION, "Multimedia");
		generateMultiSelectList(params, request, out);
	}
	%>
<!-- METADATA TYPE="CalicoControl" endspan -->

See Multi-Select List Form Control.

Single-Select Table

A single-select table form control consists of form control items in the row or column format based on radio buttons and table HTML elements. Each row in the table contains a radio button and attributes for each available form control item. Only one of the form control items can be chosen at a time.

You can create the following single-select table form control for the decision point OSSelection with the caption Multimedia and the None option.

The following code generates the form control in the figure:

<!-- METADATA TYPE="CalicoControl" startspan-->
<%
	if (params != null)
	{
		params.clear();
		params.put(PARAM_OBJECTNAME, "[MyComputerConfig].OSSelection");
		params.put(PARAM_ATTRIBUTES, "Desc, PN, UC");
		params.put(PARAM_CONTROLID, "OSSelectionCtrl");
		params.put(PARAM_CAPTIONIMAGE, "/MyComputer/images/cd.gif");
		params.put(PARAM_COLUMNHEADINGS, "Description, Part Number, Unit Cost");
		params.put(PARAM_GENERATENONEMODE, "1");
		params.put(PARAM_GENERATENONETEXT, "None");
		generateSingleSelectTable(params, request, out);
	}
%>
<!-- METADATA TYPE="CalicoControl" endspan -->

In the preceding code block, the PARAM_OBJECTNAME example value [MyComputerConfig].OSSelection is the name of a decision point in the model. MyComputer is the model name, appended with the string, Config. MyComputerConfig must be bracketed between [ and ] characters. [MyComputerConfig] OSSelection is the decision point name.

See Single-Select List Form Control.

Multi-Select Table

A multi-select table form control consists of form control items in the row or column format based on check boxes and table HTML elements. Each row in the table contains a check box and attributes for each available form control item. More than one of the form control items can be chosen at a time.

You can create the following multi-select table form control for the decision point CDSelection with the caption Multimedia.

The following code generates the form control in the figure:

<!-- METADATA TYPE="CalicoControl" startspan-->
<%
	if (params != null)
	{
		params.clear();
		params.put(PARAM_OBJECTNAME, "[MyComputerConfig].CDSelection");
		params.put(PARAM_ATTRIBUTES, "Desc, PN, UC");
		params.put(PARAM_CONTROLID, "CDSelectionCtrl");
		params.put(PARAM_CAPTION, "MultiMedia");
		params.put(PARAM_COLUMNHEADINGS, "Description, Part Number, Unit Cost");
		generateMultiSelectTable(params, request, out);
	}
%>
<!-- METADATA TYPE="CalicoControl" endspan -->

See Multi-Select Table Form Control.

Single-Select Image

The single-select image template places an image on the page where you indicate, to select a domain member. Specify an image and location for each domain member of the selection point. At runtime, selecting one image deselects another. Include the template for the single-select image in the following way:

<%@ include file="/calico/templates/html/SingleSelectImage.jsp" %>

For example, you can create the following single-select image controls for a selection point with three domain members.

When you select and submit the selectable blue image, it is replaced by a corresponding selected blue image.

Note. Single-select images can be placed on the page where you specify. If you do not specify a location, they are placed on a line, bottom-aligned.

The following code generates the first (the blue image) of the two controls in the figure.

<!-- METADATA TYPE="CalicoControl" startspan -->
<%
if (params != null)
{
	params.clear();
	params.put(PARAM_OBJECTNAME, "[AudioConfig].kitSelection");
	params.put(PARAM_DOMAINMEMBERNAME, "DashSpacer");
	params.put(PARAM_IMAGENAME, "blue.gif");
	params.put(PARAM_IMAGEPATH, "SSImages");
params.put(PARAM_AUTOSUBMIT, "true");
	generateSingleSelectImage(params, request, out);
}
%>
<!-- METADATA TYPE="CalicoControl" endspan --> 

Parameters are:

• PARAM_OBJECTNAME: The unique object name (“<modelnameConfig>.decisionpointname”), which is used to retrieve the items of a form control.

• PARAM_ DOMAINMEMBERNAME: The name of the domain member that the image selects.

• PARAM_IMAGEATTRIBUTE: The name of the domain member attribute whose value is the image that selects the domain member.

• PARAM_IMAGENAME: The name of the image that selects the domain member.

See Single-Select Image, Parameters in the Inclusion Set.

Note. Provide either the image attribute or the image name, but not both.

Optional image parameters are:

• PARAM_IMAGEPATH: The Uniform Resource Locator (URL) path to the directory that has the images.

• PARAM_IMAGEWIDTH: The width of the image.

• PARAM_IMAGEHEIGHT: The height of the image.

• PARAM_IMAGESTATES: A comma-delimited list of states, other than selectable, for which alternative images exist whose names follow a naming convention.

  The naming convention appends an underscore followed by one or two letters to either the image name or the value of the image attribute. For example, image1.gif becomes image1_s.gif and image1_c.gif. The comma-delimited list of states for which images exist uses the same letters (without the underscore) that are appended to the image name; for example, “us, es, e, c.”

  Other possible states and the naming convention for their images are:

  • Selected (_s): Use if you do not display computer-user variations.

  • User-selected (_us).

  • Computer-selected (_cs)): Default-selected can share this image.

  • Default-selected (_ds)): Computer-selected can share this image.

  • Eliminated (_e): Use if you do not display computer-user variations.

  • User-eliminated (_ue).

  • Computer-eliminated (_ce).

  • Conflicted (_c).

• PARAM_MOUSEOVERIMAGES: “True” means that mouseover images are available. The default value is “False.”

  You must also provide mouseover images whose names follow a naming convention. The convention appends an underscore and the letters “mo” to the name of any image that changes when the mouse moves over it, for example, image1_mo.gif or image1_us_mo.gif.

• PARAM_ALTTEXTATTRIBUTE: The name of the domain member attribute whose value is the text that is used as an alternative for the image. Most browsers display this text as a tool tip when the mouse is over the image.

• PARAM_ALTTEX: The text that is used as an alternative for the image, if the domain member does not have an alternative text attribute.

• PARAM_ADDITIONALATTRIBUTES: Comma-delimited list of domain member attributes that are available to client-side script. Do not include the image attribute or the alternative text attribute.

• PARAM_AUTOSUBMIT: True means that the form should be submitted when the user selects the image. The default value is False.

A JavaScript object, calicoSSI, is created for each image that is generated by the image templates, and is passed to JavaScript callback functions to identify the image that is being created, selected, deselected, moused over, moused off of, or auto-submitted. Each of these objects has these properties:

Optional callback parameters are:

• PARAM_CREATECALLBACK: The name of the JavaScript function that is called when a client-side single-select image object is created.

  Parameter: the newly created object.

  Return value: None

  For example, createCB():

  function createCB(calicoSSI) 
  { 
  	calicoSSI.myCustomImg = new Image(143, 126) 
  	calicoSSI.myCustomImg.src = calicoSSI.attributes[0] 
  }

  createCB() caches an image specified by a domain member attribute.

• PARAM_SELECTCALLBACK: The name of the JavaScript function that is called when a domain member image is selected.

  Parameter: The object for the image that is being selected

  Return value: True if the selection can proceed; otherwise, False.

  For example, selectCB():

  function selectCB(calicoSSI) 
  { 
  	document.images["myCustomImg"].src = calico.SSI.customImg.src 
  	return true 
  }

  selectCB() updates an image with an image cached by createCB().

• PARAM_UNSELECTCALLBACK: The name of the JavaScript function that is called when a domain member image is deselected—that is, when another domain member image is selected.

  Parameter: The object for the image that is being deselected.

  Return value: “True” if the deselection can proceed; otherwise, “False.”

  For example, unselectCB():

  function unselectCB(calicoSSI) 
  { 
  	var retval = true 
  	if (someRareCondition(calicoSSI)) 
  	{ 
  		var retval = false 
  		alert("Explanation of problem") 
  	} 
  	return retval 
  } 

  unselectCB() may prevent deselecting the item, which would prevent selecting another item.

• PARAM_MOUSEOVERCALLBACK: The name of the JavaScript function that is called when the mouse moves over a domain member image.

  Parameter: The object for the image that the mouse is over.

  Return value: “False” if the function updates the browser’s status bar. The default value of “True” lets the alternative text for the image appear in the status bar.

  For example, mouseOverCB():

  function mouseOverCB(calicoSSI) 
  { 
  	window.status = calicoSSI.attributes[1] 
  	return false
  }

  mouseOverCB() puts text from a domain member attribute in the status bar.

• PARAM_MOUSEOUTCALLBACK: The name of the JavaScript function that is called when the mouse moves off a domain member image.

  Parameter: The object for the image that the mouse is moving off

  Return value: “False” if the function updates the status bar of the browser. The default value of “True” allows text to be cleared from the status bar.

  For example, mouseOutCB():

  function mouseOutCB(calicoSSI) 
  { 
  	window.status = "Eat at Joe’s" 
  	return false 
  }

  mouseOutCB() puts a static string in the status bar.

• PARAM_AUTOSUBMITCALLBACK: The name of the JavaScript function that is called before the form is submitted because an image is selected whose auto-submit attribute is “True.”.

  Parameter: The object for the image that is being auto-submitted Return value: “True” if the form can be submitted; otherwise, “False.”

  For example, autoSubmitCB():

  function autoSubmitCB(calicoSSI) 
  { 
  	return confirm("Submit your choices?") 
  }

  autoSubmitCB() asks the user to confirm that the form can be submitted.

Single-Select Image Table

The single-select image table template places images for every domain member of a selection point either horizontally in a row, or vertically in a column on the page, to select among them. Specify an image for each domain member of the selection point, and whether you want them placed in a row or a column. At runtime, selecting one image deselects another.

Include the template for the single-select image table in the following way:

<%@ include file="/calico/templates/html/SingleSelectImageTable.jsp" %>

For example, you can create the following single-select image table control for a selection point with three domain members.

When the selectable green image is selected and submitted, it is replaced by a corresponding selected green image.

Note. The images of a single-select table image control are placed in a table row (in a table cell) and centered.

The following code generates the control in the figure:

<!-- METADATA TYPE="CalicoControl" startspan -->
<%
if (params != null)
{
	params.clear();
	params.put(PARAM_OBJECTNAME, "[AudioConfig].kitSelection");
	params.put(PARAM_IMAGEATTRIBUTE, "SSImage");
	params.put(PARAM_IMAGEPATH, "SSImages");
	params.put(PARAM_AUTOSUBMIT, "true");
	generateSingleSelectImageTable(params, request, out);
}
%>
<!-- METADATA TYPE="CalicoControl" endspan -->

See Parameters in the Inclusion Set.

The optional table parameters are:

• PARAM_IMAGEATTRIBUTE: The name of the domain member attribute whose value is the image that selects the domain member.

• PARAM_COLUMNS: The number of columns in the table. The number of domain members that are displayed at runtime determines the number of rows.

• PARAM_ROWS: The number of rows in the table. The number of domain members that are displayed at runtime determines the number of columns.

  Note. Runtime performance is better if you specify the number of columns, rather than the number of rows.

• PARAM_BORDER: The border attribute for the generated table. The default value is 0.

• PARAM_CELLSPACING: The cell spacing attribute for the generated table. The default value is 0.

• PARAM_CELLPADDING: The cell padding attribute for the generated table. The default value is 0.

See Single-Select Image Table.

Application Why Help

Use an Application Why Help template to represent a set of violation items of the current configuration in an unordered list format.

You can create the following application-level why help:

The following code generates the form control in the figure:

<!-- METADATA TYPE="CalicoControl" startspan-->
<%
	if (params != null)
	{
		params.clear();
		params.put(PARAM_CAPTION, "Application Why Help:");
		generateApplicationWhyHelp(params, request, out);
	}
%>
<!-- METADATA TYPE="CalicoControl" endspan -->

See Application Why Help.

Form Control Why Help

Use a Form Control Why Help template to represent a set of violation items of a form control for the current configuration in the unordered list format.

You can create a Form Control Why Help like the example in the Application Why Help:

The following code generates the example form control:

<!-- METADATA TYPE="CalicoControl" startspan-->
<%
	if (params != null)
	{
		params.clear();
		params.put(PARAM_OBJECTNAME, "[MyComputerConfig].HDSelection");
		params.put(PARAM_CAPTION, "Control Why Help:");
		generateControlWhyHelp(params, request, out);
	}
%>
<!-- METADATA TYPE="CalicoControl" endspan -->

See Form Control Why Help.

Text Input Form Control

The text input template generates a text box for entering any text value. Unlike values that are entered into extern entry templates, text input values are not submitted to the engine. They are instead passed from page to page and loaded into the configuration object that is contained within the COP on each page. This allows any information that you store using the text input template to be included with standard configuration information, such as that acquired when you use the BOM item generator, which is saved when you run it against a compound model or integrate it with other applications.

Important! Use text input templates for all text related entries. Use extern entry templates for entering external values that need to be processed by the Configurator engine.

Include the template for the extern entry text box in the following way:

<%@ include file="/calico/templates/html/TextInput.jsp" %>

For example, you can create the following text input control with an initial default value.

The following code generates the control in the example.

<!-- METADATA TYPE="CalicoControl" startspan -->
<%
if (params != null)
{

	params.clear();
	params.put(PARAM_OBJECTNAME, "TextInput_Ctrl01");
	params.put(PARAM_CAPTION, "Phone Number:");
  	params.put(PARAM_ TEXTINPUTDEFAULT, "212-555-1212");
	params.put(PARAM_ ENTRYSIZE, "12");
	generateTextInput(params, request, out, session, cop.getConfiguration());
}
%>
<!-- METADATA TYPE="CalicoControl" endspan -->

See Parameters in the Inclusion Set.

The two optional parameters are:

PARAM_TEXTINPUTDEFAULT: A default value that shows up when the text input box is initially shown.

PARAM_ENTRYSIZE: The width in characters of the text entry field. The default value is 15.

See Text Input Form Control.

Numeric Data Form Control

A numeric data control consists of a control caption or a caption image and a value of the numeric data that are displayed in the same line.

The include file that is required for the numeric data template is:

<%@ include file="/calico/templates/html/NumericData.jsp" %>

For example, you can create the following numeric data control for the decision point WattsSummation with the caption Total Watts.

The following code generates the control in the figure:

<!-- METADATA TYPE="CalicoControl" startspan-->
	<%
		if (params != null)
		{
		params.clear();
		params.put(PARAM_OBJECTNAME, "[_Application].WattsSummation");
		params.put(PARAM_CAPTION, "Total Watts");
		generateNumericData(params, request, out);
		}
	%>
<!-- METADATA TYPE="CalicoControl" endspan -->

See Numeric Data Form Control.

Extern Entry Form Control

The extern entry template generates a text box for entering a value (for example, float, numeric, boolean or date-related value) that is submitted to the Configurator engine using the extern() function.

Important! Use text input templates for all text related entries that do not need to be processed by the Configurator engine.

Include the template for the extern entry text box in the following way:

<%@ include file="/calico/templates/html/ExternEntry.jsp" %>

For example, you can create the following extern entry control to enter a floating point value.

The following code generates the previous control.

<!-- METADATA TYPE="CalicoControl" startspan -->
<%
if (params != null)
{

	params.clear();
	params.put(PARAM_OBJECTNAME, "[_Application].ExtVar1");
	params.put(PARAM_CONTROLID, "ExEn01");
	params.put(PARAM_CAPTION, "Enter Number Here");
	params.put(PARAM_FLOATENTRY, "true");
        params.put(PARAM_ENTRYSIZE, "3");
	generateExternEntry(params, request, out);
}
%>
<!-- METADATA TYPE="CalicoControl" endspan -->

See Parameters in the Inclusion Set.

The two optional parameters are:

• PARAM_FLOATENTRY: “True” processes the entered number as a floating point value. The default value “False” processes the number as an integer.

• PARAM_ENTRYSIZE: The width in characters of the text entry field. The default value is 3.

Using Configuration Form Control Templates

PeopleSoft Advanced Configurator supplies 11 form control templates. Each is a JSP page that generates HTML. Six of them enable the web user to select an item on an HTML form, using radio buttons, check boxes, drop-down lists, or selection lists. The other four form control templates generate output display information. One enables the web user to enter a text value using an edit box. Two of these form controls display constraint violations; one for the entire configuration session, and the other for its corresponding form control. The last display form control template generates a visible numeric value.

Three types of user-selectable form controls are available:

• Group: radio buttons and check boxes that are grouped as part of the selection point.

• List: drop-down or selection lists; one for each selection point.

• Table: Table form controls and Group form controls are alike, except that the Table form controls provide, in addition to the item name, columnar information for each form control item. The Table templates generate extra columns that are determined by the additional field descriptors in the model.

Each type of user-selectable form control can be either single-selectable or multiselectable. A multiselect form control enables the web client user to select more than one item for the selection point, whereas a single-select form control limits the user to a single selection for the selection point. A single-select list is drop-down, whereas a multiselect list is a list, typically scrollable. The following table itemizes the form control templates that are available in this release.

Plugging Form Controls into the Application Pages

To use the form control templates, you need to be familiar with the following directories:

• Applications and processing JSP pages for the form control templates:

  Solaris:	/opt/bea/wlserver_10.3.1/config/CalicoDomain/ applications⇒ /CalicoApp/
  Windows NT:	\bea\wlserver_10.3.1\config\CalicoDomain\ applications\Calico⇒ App\

• Configuration models:

  Solaris:	/opt/bea/wlserver_10.3.1/config/CalicoDomain/ applications⇒ /CalicoApp/Web-inf/models
  Windows NT:	\bea\wlserver_10.3.1\config\CalicoDomain\ applications\Calico⇒ App\Web-inf\models\

To use a form control template, your application pages need:

• A JSP include directive that includes the specified form control template.

• A specialized code-block that passes the required parameters to the specified form control template followed by a method call to generate and include it. This information is called the form control inclusion set.

Using a JSP Include Directive

The syntax to include a form control template, such as the SingleSelectGroup template, is:

<%@ include file="/calico/templates/html/SingleSelectGroup.jsp" %>

Place the include directives for the form control templates immediately following the include directive for the CalicoStartFormInc.jsp that is in each application JSP page.

For example:

<%@ include file="/calico/CalicoStartFormInc.jsp" %>
<%@ include file="/calico/templates/html/SingleSelectGroup.jsp" %>
<%@ include file="/calico/templates/html/MultiSelectTable.jsp" %>...

Note. Only one include directive <% include file="templateFile" %> is required for each type of form control template in the application JSP page. If you have five single-select list form control templates in an application JSP page, use only one JSP include directive to include them.

Using a Form Control Inclusion Set

To include a form control template using an inclusion set, bracket the inclusion set within these start and end tags:

<!-- METADATA TYPE="CalicoControl" startspan-->
		// set the parameters and include the path name for a form 
		// control template here
<!-- METADATA TYPE="CalicoControl" endspan -->

Between the start and end tags, insert these required statements:

params.clear();

params.put(parameter, value);

generateTemplateName(params, request,⇒
 out);

Example:

<!-- METADATA TYPE="CalicoControl" startspan-->
<%
	if (params != null) 
	{
		params.clear();
		params.put(PARAM_OBJECTNAME, "VehicleSelection)";
		params.put(PARAM_ATTRIBUTES, "Desc");
		params.put(PARAM_CAPTION,"Select a Vehicle");
		params.put(PARAM_CONTROLID, "VehicleSelectionControlID");
		generateSingleSelectGroup(params, request, out);
	}
%>
<!-- METADATA TYPE="CalicoControl" endspan -->

Parameters in the Inclusion Set

At runtime, the parameters in the inclusion set are passed to the form control template, which uses them when it runs at the point where generateTemplateName() is called.

Any blank spaces between the values are ignored. For example, “Description, Part Number, Unit Cost” (with spaces) is the same as “Description,Part Number,Unit Cost” (without spaces).

Form control parameter values are specified as a string. The syntax for assigning multivalued parameters (in the application page) is a single string that uses a comma character delimiter between each value. Both the PARAM_ATTRIBUTES and PARAM_COLUMNHEADINGS parameter values may be multivalued.

These parameters are required for using the selection point form control templates:

params.put(PARAM_ATTRIBUTES, <attribute name,
 attribute name ...>);

params.put(PARAM_ATTRIBUTES, <tablename.
columnname, tablename.columnname ...>)

The following table lists optional parameters for the form control templates:

params.put(PARAM_EVENTHANDER, "onClick=⇒
'this.<form-name>.submit()'

params.put(PARAM_EVENTHANDER, "onChange='my
JavascriptSubmit()'"

Specifying the Model and Locale Properties for the Solution

The user interface (UI) properties for a solution are contained in the configuration file, CalicoUI.properties. Each solution, or version of a solution, requires a separate copy of CalicoUI.properties to be modified and maintained for that solution only. It must be placed in the application folder that houses your application JSP pages.

CalicoUI.properties contains mainly display properties, which are optionally used by the application. However, four model properties and two locale properties exist that the form control templates need and that you must specify in the solution CalicoUI.properties file:

• calico.ui.version: A unique number for each application that is hosted by the same application server; one entry per CalicoUI.properties file.

• calico.model.name: Holds the model name. Valid model names are any subfolder name under <install_dir>/PeopleSoft Applications/Configurator/, which houses the models. The modeler sets the model name when it is created.

• calico.model.version: Gets the latest compiled model with the specified version number.

• calico.model.compileversion: The generated ID for a compiled model, for example, 20010221-161729-588.

• calico.locale.language=en: Indicates which set of text in the XX file that provides text for captions and controls in the desired language.

• calico.locale.country=US: Indicates which country variant of the locale language that is specified. If a custom language variant is used, the calico.locale.variant= property is provided for specification instead.

To specify model and locale properties:

1. If you haven't already done so, transfer a copy of CalicoUI.properties from <install directory>\wlserver_10.3.1\config\CalicoDomain\applications\CalicoApp\solutions\ComponentSample to the application folder where the JSP pages are kept.

2. Call the property values from each form control that uses the display properties:

   • If it is a template form control, insert the property as a parameter in its JSP inclusion set. For example:

     <!-- METADATA TYPE="CalicoControl" startspan-->
     <%
     	if (params != null) 
     	{
     		params.clear();
     		params.put(PARAM_OBJECTNAME, "[SmallBusTelecom].ServicePlanSelection)";
     		params.put(PARAM_ATTRIBUTES, "Desc");
     		params.put(PARAM_CAPTION,"Select a Service Plan");
     		params.put(PARAM_CONTROLID, "ServPlanSelectionControlID");
     		params.put(calico.ui.version, "SBQ01.04.01");
     		generateSingleSelectGroup(params, request, out);
     	}
     %>
     <!-- METADATA TYPE="CalicoControl" endspan -->

   • If it is a custom form control, fetch the property values with calls from your code.

3. If the language to use in the UI is other than the United States variant of English, specify which by inserting the code for the desired language and variant. If you have a custom language variant set, specify the desired language code in calico.locale.country=en, comment out calico.locale.country=US, uncomment calico.locale.variant=, and insert in it the correct code.

Assigning a Specific Model Version to Use for Configuration

If you use only the major number and the minor number of the model version for setting the calico.model.version property (such as calico.model.version=0-1), then by default, the form control templates use the latest compiled version from among all models within the subversions folder under version 0.1.

The model name and version (major-minor) are set in the model by the modeler. By changing these in the CalicoUI.properties file, you tell the application which model to use rather than the default latest compiled version. The compiler assigns the micro (sub-version) and compile versions. The WebLogic server by default loads only the most recent version (major-minor-micro) and compile version of every model.

To assign a specific model version to use:

1. Set the calico.model.version property to the complete version number. For example, calico.model.version=0-1-4 represents version 0.1.4.

2. Uncomment the calico.model.compileversion property in CalicoUI.properties.

3. Set the calico.model.compileversion property to the name of the folder that houses the compiled model. For example, using the following directory tree for Configurator models, you would set calico.model.compiledversion property to 200030825-161346-823.

Specifying Solution Information Properties

You use solution information property values to generate a Solution List for Configurator client application. A solution is the collection of pages, images, model files, and supporting files that make up the applications that solve a business problem, such as online configuration and order management. The solution list is the filenames, structures, and version information for that solution.

The solution list could also be used in a server-based deployment.

Solution properties are:

If these properties aren't specified, the SolutionInfo class assigns default values.

Specifying Display Properties

The names of the form control property types correspond to the names of the display attributes, as shown in the following list:

PeopleSoft Advanced Configurator provides the following set of properties to indicate the state of an item in a control:

• Selectable

• User-selected

• Computer-selected

• Default-selected

• User-eliminated

• Computer-eliminated

• Conflict

These properties cause the display of designated text symbols, images, or both that are beside the items in a control to indicate to the user their availability for selection.

You can use the item state properties as examples for creating your own properties or modify them to meet your needs.

Displaying Delta Information

Using the COP XML interface, Advanced Configurator generates two types of delta configuration information at runtime:

• Structural

  Structural deltas include component additions, deletions and changes, and connection additions, deletions, and moves. Structural and component delta information applies to configurations that are generated from compound models.

• Component

  Component information deltas indicate changes between two configurations for a single component and apply to the components in both component and compound configurations. The information can include:

  • Added, changed, and deleted configuration attributes.

  • Added, changed, and deleted choices.

Advanced Configurator returns delta information using an XML interface. The existing ConfigDetails request in the messaging interface (COPXML) can include requests for delta information. By default, the deltas that are returned represent the latest set of saved changes or those from a specified date range. In addition, the available component delta information will be enhanced to include changed expression values. PeopleSoft CRM 9.1 Order Capture and Service Management use delta information in transactions.

See Also

Retrieving Configuration Information

Displaying Delta Pricing

You can modify the pricing display for either all form control items or for the form control items belonging to specified selection points. To display delta prices, you must first enable delta pricing in the application and then specify how it is displayed. Enabling delta pricing occurs in initial implementation of jspInit() in the body of your application pages.

1. Enable delta pricing:

   To enable delta pricing for all form controls, use this statement:

   setPricing(true);

   This statement also enables total pricing for the entire configuration.

   To enable delta pricing for specific form controls, use this statement:

   setPricingControls();	// accepts as arguments a map of the
                         // decision points’ object names (strings)
                         // and price attributes (strings).

   Pass to setPricingControls() the object names that you specify in the PARAM_OBJECTNAME parameters of the form controls, along with the price attribute for that object.

   Note. For better performance, set the pricing variables rather than calling the corresponding set methods.

2. Set display properties.

   The basic format is:

   calico.pricing.add=[+ {0}]
   calico.pricing.subtract=[- {0}]

   The values that are shown result in a display string that appears alongside the selection. If the delta price is an additional 20.00 USD, the delta price appears in the following way:

   [+ $20.00]

   By replacing the characters, you can change the display. For example, if you replace the square brackets with angle brackets, and + with Add, the display becomes <Add $20.00> for a positive delta price. Replacing - with Subtract gives [Subtract $20.00] for negative deltas.

Sample code:

public void jspInit()
{
	setPricing(true);
    
	Map pricingControls = new HashMap();
	pricingControls.put("[BMWConfig].SeriesSelection", "UnitPrice");
	pricingControls.put("[BMWConfig].OptionsSelection", "UnitPrice");
	pricingControls.put("[BMWConfig].EngineSelection", "basePrice");
	
	setPricingControls(pricingControls);
}

Application Page Example

The following code provides a complete example of an application JSP page.

<HTML>
<HEAD>
	<TITLE>Sample Page</TITLE>
</HEAD>
<BODY>

<%!
	public void jspInit()
	
	// turn on pricing for controls
	setPricing(true);

Map pricingControls = new HashMap();
pricingControls.put("[myPCConfig].ProcessorSelection", "UnitPrice");
	
setPricingControls(pricingControls);
	}        
%>
<FORM name="TestForm" method="POST" action="CalicoProcessForm.jsp">
<%@ include file="/calico/CalicoStartFormInc.jsp" %>
<%@ include file="/calico/templates/html/SingleSelectGroup.jsp" %>

<!-- Inclusion set starts below -->
<!-- METADATA TYPE="CalicoControl" startspan-->
	<%
		if (params != null)
		{
				params.clear();
				params.put(PARAM_OBJECTNAME, 
								 "[myPCconfig].ProcessorSelection");
				params.put(PARAM_ATTRIBUTES, "Desc");
				params.put(PARAM_CAPTION, 
								 "[myPCConfig].ProcessorSelection");
				params.put(PARAM_CONTROLID, "ProcessorSelectionCtrl");
				generateSingleSelectGroup(params, request, out); 
		}        
	%>
<!-- METADATA TYPE="CalicoControl" endspan -->

<%@ include file="/calico/CalicoEndFormInc.jsp" %>
</FORM>
</BODY>
</HTML>

Configuring a Form Control Template

You must use getControlData() in configured form control template JSP pages, as in the following Java statement:

ControlData varName = getControlData(objectName, request, params);

Application Scope

You can configure HTML-level display properties, such as the text color of the form controls, by modifying the properties in the CalicoUI.properties file. The form control templates load these properties upon their initialization.

Template Scope

You can configure how the display data is altered depending on the data for the model. You can configure the behavior of the display to:

• Display domain member attribute information.

• Sort the form control items.

• Eliminate form control items of eliminated domain members.

• Eliminate the form control items of the eliminated domain members whose elimination levels are beyond an inclusionary range.

• Display delta pricing and the total price.

To configure the state of an individual instance of a form control:

1. Make a copy of the type of form control template that you want, rename the copy, and put that copy in your application directory.

   When you use the JSP include directive to include your template, be sure to use the path to your application directory.

   Note. Do not modify any of the form control template JSP files: they are installed as read-only files.

2. Modify its JSP code.

3. Include your custom form control template in any of your application JSP pages whenever you use that type of form control.

Loading the Form Control Data from the Model

The form control templates get their corresponding selection point (decision point) data from the model with the following JSP template code:

String objectName = (String)params.get(PARAM_OBJECTNAME);
ControlData ctrlData = getControlData(objectName, request, params);

Loading the UI Properties for a Control

The form control templates load the specified UI properties (from the CalicoUI.properties file) with the following JSP template code:

// set up display properties
String[] stateMap = (String[])request.getAttribute(STATEMAP);
String[] tagMap = (String[])request.getAttribute(TAGMAP);
String[] imgMap = (String[])request.getAttribute(IMAGEMAP);
String[] textColorMap = (String[])request.getAttribute(TEXTCOLORMAP);
Properties props = (Properties)request.getAttribute(UIPROPS);

The form control templates set their properties with the following JSP template code:

// set up the display properties for control items
state = (int)ctrlItem.getFlags();
stateFlags = stateMap[state]; 
tagItemState = tagMap[state];
imgItemState = imgMap[state];
colorItemText = textColorMap[state];

The names of the form control property types correspond to the names of the display attributes, as shown in the following list:

Registering Custom Form Control Templates

The addCtrl() function should be called within any configured form control template. addCtrl() registers a Configurator form control. It adds each control along with its selection point name to a form-hidden attribute called CalicoCtrlMap, which is generated by CalicoEndFormInc.jsp for each Configurator page. This is necessary so that the Configurator JSP processor page (CalicoProcessFormInc.jsp) knows which form controls need to be processed and which to ignore (non-Configurator form controls).

addCtrl() is used by most of the Configurator form control templates.

Custom Form Control Template Example

The purpose of providing the sample template is to explain how developers could configure the behavior of a Configurator control by displaying eliminated control items differently based on their elimination levels returned from COP:

If the elimination level for an eliminated control item is >= 0 and <= 4, the item is hidden (not shown).

If the elimination level for an eliminated control item is >= 5 and <= 9, the item is displayed as unavailable with the X image.

If the elimination level for an eliminated control item is >= 10, the item is displayed as normal (without being unavailable for entry or the X image).

In this example template, we use 0, 4, 5, 9, 10 and so on for the lower and upper bounds to display control items differently. Developers can define a range of values for the elimination level that they want to handle in the template that they create because these values depend on the elimination levels that are defined for the constraints by the modelers.

In the following figures, after the Prima Base Celeron 43 Mhz MiniTower pick is submitted, the control on the right has only one item left and is shown as user-selected (finger icon). All other items in the control have elimination levels that are >= 0 and <= 4. Therefore, they are not shown on the page.

The following web page illustrates using the same model decision point: the top left form control with the SingleSelectGroup.jsp template, and the top right form control with the SingleSelectGroupElimLevel.jsp template:

The next figure illustrates the differing effects of using the standard SingleSelectGroup.jsp form control template and of using a configured (sample) SingleSelectGroupElimLevel.jsp form control template. The top left form control was generated by the SingleSelectGroup.jsp template, and the top right form control was generated by the SingleSelectGroupElimLevel.jsp template:

Common Errors

The following list describes common errors for those who implement the web applications using Configurator JSP pages:

• calico.model.compileversion: The calico.model.compileversion entry of the CalicoUI.properties file is used to specify the compiled version for the model to be loaded for the JSP page.

  By default, this entry is commented out and the most recent compiled version is loaded for a model. Don’t uncomment this entry unless a specific compiled version of a model is given.

• Better performance: Add <%@ page session="false" %> to a JSP page if the page does not reference the session-implicit variable. This should apply to the CalicoProcessForm.jsp file as well.

• CalicoEndFormInc.jsp: A Configurator JSP page must include both CalicoStartFormInc.jsp and CalicoEndFormInc.jsp. For example:

  
  <%@ include file="/calico/CalicoStartFormInc.jsp" %> 
  	.......
  <%@ include file="/calico/CalicoEndFormInc.jsp" %>
  

  CalicoEndFormInc.jsp calls the release() method for the COP. If a system quickly runs out of memory when running Configurator JSP pages, verify that CalicoEndFormInc.jsp is included properly on each page.

• Variables declared within JSP <%! %> blocks: Be careful using variables that are declared within <%! %> blocks of the JSP pages. For example:

  <%!
  	HashMap myMap = new HashMap();
  	...
  %>

  The values of the variables that are declared within the <%! %> blocks are accessed and modified by more than one user when multiple clients access the pages concurrently unless the access to such objects is properly synchronized. If such values are meant to be user-specific, the preceding variables that are used by other functions or codes may easily run into problems.

• Template files: The name of the control-generating function should be changed as well as in any custom templates (for example, generateMyEnterpriseLargeSingleSelectTable(params, request, out), generateMyEnterpriseSmallSingleSelectTable(params, request, out)) so that no confusion results if multiple templates of the same control type exist on one page.

• Keep the custom templates in the application directory instead of in the calico directory.

  You should include only template files that are used on the JSP page.

• StringBuffer.append(): Use StringBuffer.append() for string concatenation instead of using the + operator of the String class.

• Avoid unnecessary evaluations and object creations in Java codes, especially codes within loops—for example, while and for loops.