Using JSP Templates for Form Controls

This chapter provides an overview of the form control templates and discusses:

• Properties, parameters, and attributes.

• Form control templates.

• Using configuration form control templates.

• Specifying the solution's model and locale properties.

• Application page example.

• Customizing a form control template.

• Registering custom form control templates.

• Example custom form control template.

• 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 supported in the Configuration Client, which is the midtier application. A form control template is a separate 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 page(s) can contain form controls by including 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 look-and-feel of the form control display in the following ways:

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

• Form control scope:

  • Setting parameters in the application page(s).

  • Customizing a Configurator template—Extending the form control template by copying the JSP template, modifying that copy, and saving it as a customized template file that can be included in the application page(s).

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

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.

Properties, Parameters, and Attributes

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

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 your application page(s) passes 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 specified attributes’ data.

Form Control Templates

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

Note. The form control template filenames are in mixed case, i.e. 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 de-selected. 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.

Multi-Select Group

A multi-select 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 box buttons. Each item can be either selected or de-selected.

You can create the following multi-select 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 used to connote the domain member states:

Note. These state tags can be customized 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 de-select more than one item, a user presses the Ctrl/Shift keys and clicks on the subsequent items to select them or clicks (on selected items) to de-select 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 used to connote the domain member states:

Note. These state tags can be customized by modifying the property values in the CalicoUI.properties file, which is located in your application directory.

You can create the following multi-select 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/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 code block above, 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/column format based on check box buttons and table HTML elements. Each row in the table contains a check box button 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 run time, selecting one image de-selects another. Include the template for the single-select image as follows:

<%@ 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 the “selectable” blue image is selected and submitted, 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—Name of the domain member that the image selects.

• PARAM_IMAGEATTRIBUTE—Name of the domain member attribute whose value is the image that selects the domain member.

• PARAM_IMAGENAME—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—URL path to the directory that has the image(s).

• PARAM_IMAGEWIDTH—Width of the image.

• PARAM_IMAGEHEIGHT—Height of the image.

• PARAM_IMAGESTATES—A comma-delimited list of states, other than selectable, for which there are alternative images 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 there are images 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—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—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 generated by the image templates, and is passed to JavaScript callback functions to identify the image 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—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—Name of the JavaScript function that is called when a domain member image is selected.

  Parameter: The object for the image 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—Name of the JavaScript function that is called when a domain member image is de-selected—that is, when another domain member image is selected.

  Parameter: The object for the image being de-selected.

  Return value: “True” if the de-selection 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 de-selecting the item, which would prevent selecting another item.

• PARAM_MOUSEOVERCALLBACK—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 image’s alternative text 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—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 browser’s status bar. 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—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 run time, selecting one image de-selects another.

Include the template for the single-select image table as follows:

<%@ 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—Name of the domain member attribute whose value is the image that selects the domain member.

• PARAM_COLUMNS—Number of columns in the table. The number of domain members displayed at run time determines the number of rows.

• PARAM_ROWS—Number of rows in the table. The number of domain members displayed at run time determines the number of columns.

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

• PARAM_BORDER—Border attribute for the generated table. The default value is “0”.

• PARAM_CELLSPACING—Cell spacing attribute for the generated table. The default value is “0”.

• PARAM_CELLPADDING—Cell padding attribute for the generated table. The default value is “0”.

See Single-Select Image Table.

Application Why Help

An Application Why Help template is used 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

A Form Control Why Help template is used 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 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 contained within the COP on each page. This allows any information stored using the text input template to be included with standard configuration information, such as that acquired when using the BOM item generator, saved when running against a compound model, or integrating with other applications.

include the template for the extern entry text box as follows:

<%@ 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—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 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 figurel.

<!-- 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

The extern entry template generates a text box for entering a value that is submitted to the Configurator engine using the extern() function.

Include the template for the extern entry text box as follows:

<%@ 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—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 allows the Web user to enter a text value using en 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.

There are three types of user-selectable form controls:

• Group—radio buttons and check boxes 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 multi-selectable. A multi-select form control enables the Web client user to pick more than one item for the selection point, whereas a single-select form control limits the user to a single pick for the selection point. A single-select list is drop-down, whereas a multi-select list is a list, typically scrollable. The following table itemizes the form control templates available in this release.

Plugging Form Controls into the Application Page(s)

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/weblogic81/config/CalicoDomain/ applications/CalicoApp/
  Windows NT:	\bea\weblogic81\config\CalicoDomain\ applications\Calico⇒App\

• Configuration models—

  Solaris:	/opt/bea/weblogic81/config/CalicoDomain/ applications⇒/CalicoApp/Web-inf/models
  Windows NT:	\bea\weblogic81\config\CalicoDomain\ applications\CalicoApp\Web-inf\models\

To use a form control template, your application page(s) needs:

• 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 form control templates’ include directives 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 run time, 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 multi-valued 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 multi-valued.

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 are optional parameters for the form control templates:

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

params.put(PARAM_EVENTHANDER, "onChange='myJavascriptSubmit()'"

Specifying the Solution's Model and Locale Properties

A solution's UI properties 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, there are four model properties and two locale properties 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 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 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>\weblogic81\config\CalicoDomain\applications\CalicoApp\solutions\ComponentSample to the application folder where the JSP pages are kept.

2. Call the property value(s) 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 value(s) 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

Solution information property values are used in generating a Solution List for Configurator client application. A Solution is the collection of pages, images, model files, and supporting files that comprise the application(s) 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 will assign 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 a 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 and/or images 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 your needs.

Displaying Delta Information

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

• Structural

  Structural deltas include component additions, deletions and changes, and connection additions, deletions, and moves. Structural and component delta information applies to configurations 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 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 Enterprise CRM 8.9 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 page(s).

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 you specify in the form controls’ PARAM_OBJECTNAME parameters 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 shown result in a display string that appear alongside the selection. If the delta price is an additional $20.00, the delta price appears as follows:

   [+ $20.00]

   By replacing the characters, you can change the display, for example, by replacing 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>

Customizing a Form Control Template

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

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

Application Scope

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

Template Scope

You can customize how the display data is altered depending upon the model’s data. You can customize 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 customize the state of an individual instance of a form control:

1. Make a copy of the type of form control template 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 customized 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.

Example Custom Form Control Template

The purpose of providing the sample template is to explain how developers could customize 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 grayed out with the X image.

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

In this example template, we use 0, 4, 5, 9, 10 etc. for the lower and upper bounds to display control items differently. Developers can define a range of values for the elimination level they want to handle in the template they create since these values depend on the elimination levels 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 only has 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 customized (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 is a checklist of 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 COP’s release() method. If a system quickly runs out of memory when executing Configurator JSP pages, verify that CalicoEndFormInc.jsp is included properly on each page.

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

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

  The values of the variables declared within the <%! %> block(s) will be accessed/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 above variables 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 (e.g. generateMyEnterpriseLargeSingleSelectTable(params, request, out), generateMyEnterpriseSmallSingleSelectTable(params, request, out)) so that there won’t be any confusion should 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 only include 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.