11 User Interface Framework

This chapter describes the User Interface (UI) Framework that is part of the Oracle Retail POS Suite architecture. The UI Framework encompasses all classes and interfaces included in Oracle Retail POS Suite to support rapid development of UI screens. It enables the building of custom screens using existing components.

For ease of development, the UI Framework hides many of the implementation details of Java UI classes and containment hierarchies by moving some of the UI specification from Java code into XML. This eases screen manipulation and layout changes affecting the look and feel of the entire screen, subsets of screens, and portions of a screen.

Table 11-1 provides a general description of features of the UI Framework.

Table 11-1 UI Framework Features

Feature	Description
Common Design	All UI implementations share code and extend or implement base UI classes that are provided as part of Oracle Retail POS Suite. The UI Framework provides basic functionality that does not need to be duplicated within each application.
Reuse	The UI Framework allows bean classes to be independent, thereby supporting their reuse. A UI Technician can be used with multiple applications and UI Framework components can be used across multiple features in an application.
Externally Configurable Screens	The UI Framework enables you to configure screens outside the code to accommodate applications that change frequently. The external screen configurations can be updated to use new Oracle Retail POS Suite or application-specific components as they are developed.
Support for Internationalization	The UI Framework provides hooks for implementing internationalization, including language and locale independence.
Extensibility and Flexibility	Additional formats for specifications can be defined without affecting the internal UI Framework classes. Portability is achieved through the use of the Java language and flexible layout managers.

The UI Framework is the set of classes and interfaces that define the elements and behavior of a window-based UI Subsystem. It defines a structure for defining user interfaces.

Table 11-2 briefly describes the components of the framework. This chapter discusses these components in more detail.

Table 11-2 UI Framework Components

Name	Description
Display	A display is the root container for the UI application window. Displays are any subclass of java.awt.Container that implement EYSRootPaneContainer.
Screen	A screen is a user-level snapshot of a UI window as it relates to an application. The screen is composed of displays, template areas, assignment beans, and listeners. Each of these parts can be individually configured and reassembled to compose the screen.
Template	A template divides the display into areas that contain the layout information used to place the information on the display. Templates can be interchanged to define screen layouts within an application. Each screen specifies the template that is associated with the screen.
Area	An area is a layout placeholder for UI components that operate together to perform a function. Each area contains a layout constraint that dictates how the area is placed on the display.
Bean	A bean is a user interface component or group of components that operate together to provide some useful functionality. For example, a bean could be an input form or group of navigation buttons.
Connection	A connection captures relationships between beans, or between devices and beans. When a bean or device generates an event, another bean responds with a change in behavior or visual display.
Listener	A listener provides a mechanism for reacting to user interface events.

Screens

Generally, for each package in an application, one UI script in the form of an XML file is created to define the screens for the given package. However, because many screens share basic components, certain components are defined in a default UI script. These basic screen components, including displays, templates, and default screens, are defined in <source_directory>\applications\pos\src\oracle\retail\stores\pos\config\defaults\defaultuicfg.xml. Overlay screens are then defined in the UI script for the given package. This section describes the components that are used to build Point-of-Service screens, except for beans which are described in the next section.

Displays define window properties. They are basic containers with dimensions and a title defined. In Point-of-Service, only two types of windows can be displayed at the same time—the main application window and a window displaying the Help browser.

Table 11-3 describes the two types of displays.

Table 11-3 Display Types

Name	Description
EYSPOSDisplaySpec	A 600x800 container for all application screens
HelpDialogDisplaySpec	A 600x800 container for Point-of-Service Help screens

Templates divide displays into geographical areas. The GridBagLayout is used to define the attributes of each area.

Table 11-4 describes the typical use of each template.

Table 11-4 Template Types

Name	Typical Use
BrowserTemplateSpec	Back Office screens within Point-of-Service application
EYSPOSTemplateSpec	Point-of-Service screens without required fields
HelpBrowserTemplateSpec	Point-of-Service help screens
ValidatingTemplateSpec	Point-of-Service screens with required fields that display an information panel below the work area

Default screens are partially-defined screens that represent elements common to multiple screens. Default screens are based on one display and one template. Default screens map beans to the commonly used areas of the template and define listeners for the bean. These screens are used by overlay specifications that define more specific screen components. For example, almost all screens in the Point-of-Service application display a status area region. The text displayed in the status region changes, but the StatusPanelSpec bean is the same from screen to screen, so a default screen would assign this bean to the StatusPanel area defined by a template.

Table 11-5 lists the areas of the template to which beans are assigned, and the display and template used by each of the six types of default screens.

Table 11-5 Default Screen Types

Name	Typical Use	Display	Template
BrowserDefaultSpec	Back Office screens within Point-of-Service application	EYSPOSDisplaySpec	BrowserTemplateSpec
DefaultHelpSpec	Point-of-Service help screens	HelpDialogDisplaySpec	HelpBrowserTemplateSpec
DefaultValidatingSpec	Point-of-Service screens with required fields that display an information panel below the work area	EYSPOSDisplaySpec	ValidatingTemplateSpec
EYSPOSDefaultSpec	Point-of-Service screens without required fields	EYSPOSDisplaySpec	EYSPOSTemplateSpec
ResponseEntryScreenSpec	Point-of-Service screens with information captured in the response area at the top of the screen	EYSPOSDisplaySpec	EYSPOSTemplateSpec

Each screen in Point-of-Service has an overlay screen defined in a UI script in the package to which it belongs or in a package higher in the hierarchy. For example, the Authorization tour script is found in <source_directory>\applications\pos\src\oracle\retail\stores\pos\services\tender\authorization but the UI script is located in <source_directory>\applications\pos\src\oracle\retail\stores\pos\services\tender. This overlay screen is based on a default screen and defines additional properties for the beans on the areas of the screen. The overlay screen may also specify connections, which are described in "Connections". The following code sample shows the definition of the ALTERATION_TYPE screen defined in <source_directory>\applications\pos\src\oracle\retail\stores\pos\services\alterations\alterationsuicfg.xml.

Example 11-1 alterationsuicfg.xml: Overlay Screen Definition

<OVERLAYSCREEN
         defaultScreenSpecName="EYSPOSDefaultSpec"
         resourceBundleFilename="alterationsText"
         specName="ALTERATION_TYPE">
 
        <ASSIGNMENT
            areaName="StatusPanel"
            beanSpecName="StatusPanelSpec">
            <BEANPROPERTY
                propName="screenNameTag" propValue="AlterationTypeScreenName"/>
        </ASSIGNMENT>
 
        <ASSIGNMENT
            areaName="PromptAndResponsePanel"
            beanSpecName="PromptAndResponsePanelSpec">
            <BEANPROPERTY
                propName="promptTextTag" propValue="AlterationTypePrompt"/>
        </ASSIGNMENT>
 
        <ASSIGNMENT
            areaName="LocalNavigationPanel"
            beanSpecName="AlterationsOptionsButtonSpec">
        </ASSIGNMENT>
 
</OVERLAYSCREEN>

Beans

A screen is composed of beans mapped to specific areas on the screen. All beans are defined in <source_directory>\applications\pos\src\oracle\retail\stores\pos\ui\beans. The beans described in this section are commonly used in screen definitions. Bean properties that can be defined in assignments of beans to areas. Through Java reflection, properties defined in XML files invoke set() or create() methods in the bean class that accept a single string parameter or multiple string parameters.

The following section covers the PromptAndResponseBean, DataInputBean, NavigationButtonBean, and DialogBean.

PromptAndResponseBean

The PromptAndResponseBean configures and displays the text in the top areas of a Point-of-Service screen called the prompt region and the response region. This bean is implemented by <source_directory>\applications\pos\src\oracle\retail\stores\pos\ui\beans\PromptAndResponseBean.java and its corresponding model PromptAndResponseModel.java.

Bean Properties and Text Bundle

PromptAndResponsePanelSpec is the name of a bean specification that defines the implementation of the PromptAndResponseBean class. The following code sample shows the bean specification available to all screens, defined in <source_directory>\applications\pos\src\oracle\retail\stores\pos\config\defaults\defaultuicfg.xml.

Example 11-2 defaultuicfg.xml: Bean Specification Using PromptAndResponseBean

<BEAN
        specName="PromptAndResponsePanelSpec"
        beanClassName="PromptAndResponseBean"
        beanPackage="oracle.retail.stores.pos.ui.beans"
        configuratorPackage="oracle.retail.stores.pos.ui"
        configuratorClassName="POSBeanConfigurator"
        cachingScheme="ONE">
</BEAN>

Table 11-6 lists property names and values that can be defined in overlay specifications when specifying attributes of a PromptAndResponseBean.

Table 11-6 PromptAndResponseBean Property Names and Values

Item	Description	Example
enterData	Indicates whether data can be entered in the response area	true
promptTextTag	The label tag that corresponds to the text bundle	GiftCardPrompt
responseField	The type of field expected in the response area (see Field Type section for available types)	oracle.retail.stores.pos.ui.beans.AlphaNumericTextField
maxLength	Maximum length of response area input	15
minLength	Minimum length of response area input	2
zeroAllowed	Indicates whether a zero value is allowed in the response area	true
negativeAllowed	Indicates whether a negative value is allowed in the response area	false
grabFocus	Indicates whether focus should be grabbed when the screen is first displayed	true

These properties can be defined in UI scripts. The following code sample defines an overlay specification that assigns the PromptAndResponsePanelSpec defined above to the PromptAndResponsePanel. This example from <source_directory>\applications\pos\src\oracle\retail\stores\pos\services\tender\tenderuicfg.xml defines the COUPON_AMOUNT overlay screen for the Tender service. The property that retrieves text from a text bundle is highlighted.

Example 11-3 tenderuicfg.xml: PromptAndResponseBean Property Definition

<OVERLAYSCREEN>
                        defaultScreenSpecName="ResponseEntryScreenSpec"
                        resourceBundleFilename="tenderText"
                        specName="COUPON_AMOUNT">
        <ASSIGNMENT
            areaName="PromptAndResponsePanel"
            beanSpecName="PromptAndResponsePanelSpec">
            <BEANPROPERTY
                propName="promptTextTag" propValue="CouponAmountPrompt"/>
            <BEANPROPERTY
                 propName="responseField"
                 propValue="oracle.retail.stores.pos.ui.beans.CurrencyTextField"/>
            <BEANPROPERTY
                 propName="maxLength" propValue="9"/>
        </ASSIGNMENT>
...
</OVERLAYSCREEN>

The string that should be displayed as the prompt text is defined in a resource bundle. In the resource bundle for the Tender service, which for en locale is defined in <source_directory>\applications\pos\locales\en\config\ui\bundles\tenderText_en.properties, the following includes a line that defines the CouponAmountPrompt.

Example 11-4 tenderText_en.properties: PromptAndResponseBean Text Bundle Example

PromptAndResponsePanelSpec.CouponAmountPrompt=Enter coupon amount and press Next.

Tour Code

In the Tour code, bean models are created to hold the data on the bean components.

Table 11-7 lists some of the important methods in the PromptAndResponseModel class.

Table 11-7 PromptAndResponseModel Important Methods

Method	Description
boolean isSwiped()	Returns the flag indicating whether a card is swiped
void setsScanned(boolean)	Sets the flag indicating whether a code is scanned
boolean isResponseEditable()	Returns the flag indicating whether the response area is editable
void setGrabFocus(boolean)	Sets the flag indicating whether focus should stay on the response field

Example 11-5 is a sample from <source_directory>\applications\pos\src\oracle\retail\stores\pos\services\modifyitem\ModifyItemQuantitySite.java that shows creation of a PromptAndResponseModel, prefilling of data in the model, and display of the model on which the PromptAndResponseModel is set.

Example 11-5 ModifyItemQuantitySite.java: Creating and Displaying PromptAndResponseModel

 POSBaseBeanModel baseModel = new POSBaseBeanModel();
        PromptAndResponseModel beanModel = new PromptAndResponseModel();
        UtilityManagerIfc utility =
          (UtilityManagerIfc) bus.getManager(UtilityManagerIfc.TYPE);
        Locale locale = LocaleMap.getLocale(LocaleConstantsIfc.USER_INTERFACE);
        String unitId = UNITID_TEXT;
        if ((uom == null) || (unitId.equals(uom.getUnitID())))
        {
            beanModel.setResponseText(Integer.toString(lineItem.getItemQuantityDecimal().intValue()));
        }
        else
        {
            beanModel.setArguments(uom.getName(locale));
            String responseText = LocaleUtilities.formatNumber(lineItem.getItemQuantityDecimal(),LocaleMap.getLocale(LocaleConstantsIfc.USER_INTERFACE));
            beanModel.setResponseText(responseText);
            screenID = POSUIManagerIfc.ITEM_QUANTITY_UOM;
        }
 
        baseModel.setPromptAndResponseModel(beanModel);
        ui.showScreen(screenID, baseModel);

The screen constant, ITEM_QUANTITY_UOM, is mapped to an overlay screen name found in the UI script for the package. The screen constants are defined in <source_directory>\applications\pos\src\oracle\retail\stores\pos\ui\POSUIManagerIfc.java.

Example 11-6 is a sample from ItemQuantityModifiedAisle.java in the same directory that shows how to retrieve data from the PromptAndResponseModel in a previous screen. To arrive at this code, a new quantity for an item is entered and the user presses Next. This line of code gets the new quantity from the previous screen.

Example 11-6 ItemQuantityModifiedAisle.java: Retrieving Data From PromptAndResponseModel

POSUIManagerIfc ui=(POSUIManagerIfc)bus.getManager(UIManagerIfc.TYPE);
        String quantity = ui.getInput();

DataInputBean

The DataInputBean is a standard bean that displays a form layout containing data input components and labels. This bean is implemented by <source_directory>\applications\pos\src\oracle\retail\stores\pos\ui\beans\DataInputBean.java and its corresponding model DataInputBeanModel.java. Field components are commonly defined with the FIELD element when defining a bean with the DataInputBean, as shown in the code sample.

Bean Properties and Text Bundle

The DataInputBean has two properties that can be defined in UI scripts, which override the settings in the field specifications.

Table 11-8 lists DataInputBean property names and values.

Table 11-8 DataInputBean Property Names and Values

Item	Description	Example
labelTags	Sets the property bundle tags for the component labels	NameLabel,AddressLabel,StateLabel
labelTexts	Sets the text on the component labels	Name,Address,State

The label tag is used for internationalization purposes, so the application can look for the correct text bundle in each language. The label tag overrides the value of the labelText field. Example 11-7 is code from manageruicfg.xml that shows a field specification defined in a DataInputBean bean specification.

Example 11-7 manageruicfg.xml: Bean Specification Using DataInputBean

<BEAN
        specName="RegisterStatusPanelSpec"
        configuratorPackage="oracle.retail.stores.pos.ui"
        configuratorClassName="POSBeanConfigurator"
        beanPackage="oracle.retail.stores.pos.ui.beans"
        beanClassName="DataInputBean">
 
        <FIELD fieldName="storeID"
               fieldType="displayField"
               labelText="Store ID:"
               labelTag="StoreIDLabel"
               paramList="storeNumberField"/>
         ...
</BEAN>

The strings that should be displayed as labels on the screen are defined in a resource bundle. In the resource bundle for the Manager service, which for the en locale is defined in <source_directory>\applications\pos\locales\en\config\ui\bundles\managerText_en.properties, Example 11-8 is a line of code that defines the StoreIDLabel.

Example 11-8 managerText_en.properties: DataInputBean Text Bundle Example

RegisterStatusPanelSpec.StoreIDLabel=Store ID:

Fields do not have to be defined in the UI script. They can be defined in the beans and models instead. In the overlay screen specification, two bean properties that can be set are OptionalValidatingFields and RequiredValidatingFields. If the fields are optional and the user enters information in them, then they are validated. If the user does not enter any information, the fields are not validated. On the other hand, required fields are always validated.

Tour Code

Bean models are created to hold the data managed by the bean. This protects the bean from being changed. A bean can only be accessed by a model in the Tour code.

Table 11-9 lists some of the important methods in the DataInputBeanModel class.

Table 11-9 DataInputBeanModel Important Methods

Method	Description
String getValueAsString(String)	Returns the value of the specified field as a string
int getValueAsInt(String)	Returns the value of the specified field as an integer
void setSelectionValue(String, Object)	Sets the value of the specified field in a vector to the specified value
void setSelectionChoices(String, Vector)	Sets the value of the specified field to the specified vector of choices
void clearAllValues()	Clears the values of all the fields

Example 11-9 is a sample from <source_directory>\applications\pos\src\oracle\retail\stores\pos\services\admin\parametermanager\SelectParamStoreSite.java that shows creation of a DataInputBeanModel and prefilling of data in the model.

Example 11-9 SelectParamStoreSite.java: Creating and Displaying DataInputBeanModel

        DataInputBeanModel beanModel = new DataInputBeanModel();
beanModel.setSelectionChoices("choiceList", vChoices);
beanModel.setSelectionValue("choiceList", (String)vChoices.firstElement());

Example 11-10 is a sample from Tour code that shows how to retrieve data from the DataInputBeanModel. In this example from <source_directory>\applications\pos\src\oracle\retail\stores\pos\services\admin\parametermanager\StoreParamGroupAisle.java, after the model is created and displayed by the code from the previous code sample, the model is retrieved from the UI Manager, and data is retrieved from the model.

Example 11-10 StoreParamGroupAisle.java: Retrieving Data from DataInputBeanModel

        DataInputBeanModel model =
                (DataInputBeanModel)ui.getModel(POSUIManagerIfc.PARAM_SELECT_GROUP);
        ParameterCargo cargo = (ParameterCargo)bus.getCargo();
String val = (String)model.getSelectionValue("choiceList");
        cargo.setParameterGroup(val);

NavigationButtonBean

The NavigationButtonBean represents a collection of push buttons and associated key stroke equivalents. This bean is implemented by <source_directory>\applications\pos\src\oracle\retail\stores\pos\ui\beans\NavigationButtonBean.java and its corresponding model NavigationButtonBeanModel.java. The global navigation area and the local navigation area both use the NavigationButtonBean.

Bean Properties and Text Bundle

The LocalNavigationPanel and GlobalNavigationPanel bean specifications both use the NavigationButtonBean. Bean properties are described only for the GlobalNavigationPanelSpec because the LocalNavigationPanelSpec typically sets its properties in the bean specification and not the overlay specification.

LocalNavigationPanel

The only property available to the NavigationButtonBean in XML is used to enable and disable buttons. When setting the states of buttons on a LocalNavigationPanel, the buttons are usually defined with the BUTTON element in the bean specification as in the following code sample. In fact, any bean that extends NavigationButtonBean, such as ValidateNavigationButtonBean, can define its buttons in the bean specification.

Example 11-11 from <source_directory>\applications\pos\src\oracle\retail\stores\pos\services\customer\customeruicfg.xml, defining the CustomerOptionsButtonSpec bean specification for the Customer service, shows how button text on a NavigationButtonBean is defined in a UI script.

Example 11-11 customeruicfg.xml: Bean Specification Using NavigationButtonBean

<BEAN
        specName="CustomerOptionsButtonSpec"
        configuratorPackage="oracle.retail.stores.pos.ui"
        configuratorClassName="POSBeanConfigurator"
        beanPackage="oracle.retail.stores.pos.ui.beans"
        beanClassName="NavigationButtonBean">
 
        <BUTTON
            actionName="AddBusiness"
            enabled="true"
            keyName="F4"
            labelTag="AddBusiness"/>
...
</BEAN>

The string that should be displayed on the buttons on the GlobalNavigationPanel is defined in a resource bundle. In the resource bundle customerText_en.properties, the following entry defines the label for the AddBusiness button.

Example 11-12 customerText_en.properties: NavigationButtonBean Text Bundle Example

CustomerOptionsButtonSpec.AddBusiness= Add Business

GlobalNavigationPanel

The GlobalNavigationButtonBean extends the NavigationButtonBean. The following code sample shows the GlobalNavigationPanel bean specification defined in <source_directory>\applications\pos\src\oracle\retail\stores\pos\config\defaults\defaultuicfg.xml. The bean class is a subclass of NavigationButtonBean.

Example 11-13 defaultuicfg.xml: Bean Specification Using GlobalNavigationButtonBean

<BEAN
         specName="GlobalNavigationPanelSpec"
         configuratorPackage="oracle.retail.stores.pos.ui"
         configuratorClassName="POSBeanConfigurator"
         beanPackage="oracle.retail.stores.pos.ui.beans"
         beanClassName="GlobalNavigationButtonBean"
         cachingScheme="ONE">
...
</BEAN>

Table 11-10 lists property names and values that can be defined in UI scripts when specifying attributes of a GlobalNavigationButtonBean.

Table 11-10 GlobalNavigationButtonBean Property Names and Values

Item	Description	Example
manageNextButton	Indicates whether the bean should manage the enable property of the Next button	true
buttonStates	Sets the buttons with the action names listed to the specified state	Help[true],Clear[false],Cancel[false],Undo[true],Next[false]

These properties can be defined in overlay specifications, as in the following code sample from tenderuicfg.xml.

Example 11-14 tenderuicfg.xml: GlobalNavigationButtonBean Property Definitions

<OVERLAYSCREEN>
                
defaultScreenSpecName="EYSPOSDefaultSpec"
                        resourceBundleFilename="tenderText"
                specName="TENDER_OPTIONS">
         <ASSIGNMENT
            areaName="GlobalNavigationPanel"
            beanSpecName="GlobalNavigationPanelSpec">
            <BEANPROPERTY
                propName="manageNextButton"
                propValue="false"/>
            <BEANPROPERTY
                propName="buttonStates"
                propValue="Help[true],Clear[false],Cancel[false],Undo[true],Next[false]"/>
        </ASSIGNMENT>
...
</OVERLAYSCREEN>

Tour Code

In the Tour code, bean models are created to hold the data on the bean components.

Table 11-11 lists some of the important methods in the NavigationButtonBeanModel class.

Table 11-11 NavigationButtonBeanModel Important Methods

Method	Description
ButtonSpec[] getNewButtons()	Returns an array of new buttons
void setButtonEnabled(String, boolean)	Sets the state of the specified action name of the button (the name of the letter the button mails)
void setButtonLabel(String, String)	Sets the label of the button using the specified action name of the button (the name of the letter the button mails)

The following sample from <source_directory>\applications\pos\src\oracle\retail\stores\pos\services\customer\lookup\CustomerSearchOptionsSite.java shows creation of a NavigationButtonBeanModel, prefilling of data in the model, and display of the model on which the NavigationButtonBeanModel is set.

Example 11-15 CustomerSearchOptionsSite.java: Creating and Displaying NavigationButtonBeanModel

NavigationButtonBeanModel nModel = new NavigationButtonBeanModel();
 
        if (cargo.isAddCustomerEnabled())
        {
            nModel.setButtonEnabled(CustomerCargo.EMPID, true);
            nModel.setButtonEnabled(CustomerCargo.CUSTINFO, true);
        }
        else
        {
            nModel.setButtonEnabled(CustomerCargo.EMPID, false);
            nModel.setButtonEnabled(CustomerCargo.CUSTINFO, false);
        }
        
        if (cargo.isAddBusinessEnabled())
        {
            nModel.setButtonEnabled(CustomerCargo.BUSINFO, true);
        }
        else
        {
            nModel.setButtonEnabled(CustomerCargo.BUSINFO, false);
        }
 
        model.setLocalButtonBeanModel(nModel);
 
        ui.showScreen(POSUIManagerIfc.CUSTOMER_SEARCH_OPTIONS, model);

The screen constant, CUSTOMER_SEARCH_OPTIONS, is mapped to an overlay screen name found in the UI script for the package. The screen constants are defined in <source_directory>\applications\pos\src\oracle\retail\stores\pos\ui\POSUIManagerIfc.java.

DialogBean

The DialogBean provides dynamic creation of dialog screens. This bean is implemented by <source_directory>\applications\pos\src\oracle\retail\stores\pos\ui\beans\DialogBean.java and its corresponding model DialogBeanModel.java.

Bean Properties and Text Bundle

DialogSpec is the name of a bean specification that defines an implementation of the DialogBean class. The following code sample shows the bean specification defined in <source_directory>\applications\pos\src\oracle\retail\stores\pos\services\common\commonuicfg.xml.

Example 11-16 commonuicfg.xml: Bean Specification Using DialogBean

<BEAN
        specName="DialogSpec"
        configuratorPackage="oracle.retail.stores.pos.ui"
        configuratorClassName="POSBeanConfigurator"
        beanPackage="oracle.retail.stores.pos.ui.beans"
        beanClassName="DialogBean">
        <BEANPROPERTY propName="cachingScheme" propValue="none"/>
</BEAN>

The DialogBean does not have any properties that can be defined in UI scripts. Therefore, all its properties are defined in Tour code discussed in the next section. The following code sample defines the message displayed in the dialog. This example from <source_directory>\applications\pos\src\oracle\retail\stores\pos\services\inquiry\giftcardinquiry\InquirySlipPrintAisle.java shows how text on a DialogBean is defined in Java code.

Example 11-17 InquirySlipPrintAisle.java: DialogBean Label Definition

 DialogBeanModel model = new DialogBeanModel();
            model.setResourceID(RETRY_CONTINUE_TAG);
            model.setType(DialogScreensIfc.RETRY_CONTINUE);
            model.setButtonLetter(DialogScreensIfc.BUTTON_CONTINUE, "ExitPrint");
            model.setArgs(msg);

The resourceID corresponds to the name of the text bundle. For all dialog screens in the en locale, dialogText_en.properties contains the bundles that define the text on the screen, as shown in the following code.

Example 11-18 dialogText_en.properties: DialogBean Text Bundle Example

DialogSpec.Retry.title=Device is offline
DialogSpec.Retry.description=Device offline
DialogSpec.Retry.line2=<ARG>
DialogSpec.Retry.line5=Press the Retry button to attempt to use the device again.

Tour Code

In the Tour code, bean models are created to hold the data on the bean components.

Table 11-12 lists some of the important methods in the DialogBeanModel class.

Table 11-12 DialogBeanModel Important Methods

Method	Description
setResourceID(String)	Used to locate screen text in the text bundle
setArgs(String [])	Sets a string of arguments to replace <ARG> tags in the text bundle
setButtonLetter(int, String)	Sets the specified letter to be sent when the specified button is pressed
setType(int)	Sets the flag indicating whether focus should stay on the response field

The following sample from <source_directory>\applications\pos\src\oracle\retail\stores\pos\services\dailyoperations\register\registeropen\AcknowledgeRegisterOpenSite.java shows creation of a DialogBeanModel, prefilling of data in the model, and display of the model on which the DialogBeanModel is set.

Example 11-19 LookupStoreCreditSite.java: Creating and Displaying DialogBeanModel

DialogBeanModel dialogModel = new DialogBeanModel();        
DialogModel.setResourceID(”RegisterOpenPromptConfirmation”);
String args[] = new String[1];
        args[0] = String.valueOf(cargo.getRegister().getWorkstation().getWorkstationID());
    model.setArgs(args); 
dialogModel.setType(DialogScreensIfc.ACKNOWLEDGEMENT);
ui.showScreen(POSUIManagerIfc.DIALOG_TEMPLATE, dialogModel);

The screen constant, DIALOG_TEMPLATE, is mapped to an overlay screen name found in the UI script for the package. The screen constants are defined in <source_directory>\applications\pos\src\oracle\retail\stores\pos\ui\POSUIManagerIfc.java.

When setting the dialog type, refer to the following table. For each dialog type, the buttons on the dialog are specified. In most cases, the letter sent by the button has the same name as the button, except for the two types noted.

Table 11-13 lists some of the available dialog types as defined by constants in <source_directory>\applications\pos\src\oracle\retail\stores\pos\ui\DialogScreensIfc.java.

Table 11-13 Dialog Types

Dialog Type	Buttons	Details
ACKNOWLEDGEMENT	Enter	Button sends OK letter
CONFIRMATION	Yes, No	NA
CONTINUE_CANCEL	Continue, Cancel	NA
ERROR	Enter	Button sends OK letter, Screen displays red in the title bar
RETRY	Retry	NA
RETRY_CANCEL	Retry, Cancel	NA
RETRY_CONTINUE	Retry, Continue	NA
SIGNATURE	NA	Places a signature panel to capture the customer's signature

When setting a letter to a button, refer to the following table that lists the available button types also defined in DialogScreensIfc.java. These constants are used as arguments to DialogBean methods that modify button behavior.

Table 11-14 lists some of the available button types also defined in DialogScreensIfc.java.

Table 11-14 Button Types

Button	ButtonID
Enter, OK	BUTTON_OK
Yes	BUTTON_YES
No	BUTTON_NO
Continue	BUTTON_CONTINUE
Retry	BUTTON_RETRY
Cancel	BUTTON_CANCEL

Field Types

This section defines field types available to all beans. The following field types may be used by all the beans, but DataInputBean is the only bean that understands the FIELD element. In other words, DataInputBean is the only bean that defines fields in bean specifications.

These field types correspond to create() methods in UIFactory.java, such as createCurrencyField() and createDisplayField(). The application framework uses reflection to create the fields. Therefore, the field names in the following table can be set as the fieldType attribute in an XML bean specification using the DataInputBean class. The corresponding parameter list is a list of strings that can be set as the paramList attribute.

Table 11-15 lists field types and their descriptions.

Table 11-15 Field Types and Descriptions

Name	Description	Parameter List Strings (no spaces allowed)
alphaNumericField	Allows letters and/or numbers, no spaces or characters	name,minLength,maxLength
constrainedPasswordField	Text where the view indicates something was typed, but does not show the original characters	name,minLength,maxLength
constrainedTextAreaField	Multi-line area that allows plain text, with restrictions on length	name,minLength,maxLength,columns,wrapStyle,lineWrap
constrainedField	Allows letters, numbers, special characters, and punctuation, with restrictions on length	name,minLength,maxLength
currencyField	Displays Currency objects in a localized format	name,zeroAllowed,negativeAllowed,emptyAllowed
decimalField	Allows decimal numbers only	name,maxLength,negativeAllowed,emptyAllowed
displayField	Display area that allows a short text string or an image, or both	name
driversLicenseField	Allows alphanumeric text that can contain &rsquor;*' or &rsquor; &rsquor;	name
EYSDateField	Displays a date object in a localized format	name
EYSTimeField	Displays a time object in a localized format	name
nonZeroDecimalField	Allows non-zero decimal numbers only	name,maxLength
numericField	Allows integers only, no special characters or letters	name,maxLength,minLength
nonZeroNumericField	Allows non-zero integers only	name,maxLength,minLength
textField	Allows letters, numbers, special characters, and punctuation	name
validatingTextField	Line of text that can be validated by length requirements	name

Multi-byte Support For Input Fields

The current UI framework allows the display and entering of multi-byte characters and the proper display and handling of the UI elements.

Multi-byte characters occupy up to four times more space than single-byte characters. In order to support these bigger sizes, the database columns need to be updated, the number of digits entered in the UI can be updated and the size of the fields in the UI needs to be adjusted.

The following are the extensions added to the UI framework subsystem:

Enable the configuration of maxLength for all input elements.
Enable the configuration of size (the width of the display field) for all input elements.
Enable UI fields to accept multi-byte characters.
Enable the UI text fields to be populated with data that is greater, up to the value of maxLength.

UI Framework Architecture for Input Fields

The main component of the UI framework subsystem is UIFactory.java. This class contains methods to create and configure all the UI Elements. It is used by the DataInputBean.java file and by all the custom beans that define the UI elements of a specific screen.

The following classes represent the UI input fields for alphanumeric characters:

ConstrainedTextField – It is a base class and it allows input fields to accept all characters.
AlphaNumericTextField – Allows fields to accept only alphanumeric characters.

The DataInputBean.java class implements a wide variety of UI elements. It is configured by using a *uicfg.xml file. For further information see DataInputBean.

Example 11-20 DataInputBean.java Class

    <BEAN
        specName="PurchaseOrderAgencyNameSpec"
        configuratorPackage="oracle.retail.stores.pos.ui"
        configuratorClassName="POSBeanConfigurator"
        beanPackage="oracle.retail.stores.pos.ui.beans"
        beanClassName="DataInputBean">
        
        <FIELD fieldName="businessNameField"
               fieldType="ConstrainedField"
               labelText="Agency/Business Name:"
               labelTag="AgencyBusinessName"
               paramList="businessNameField,2,30 />  
    </BEAN>

The following are definitions for the <FIELD> excerpt:

FieldName: The logical name of the field.
FieldType: The type of the field. When reading the configuration file, by using reflexion, the UIFactory.createConstrainedField is invoked.
LabelText: The default label in case there is no resource bundle defined for this label.
LabelTag: The resource bundle property name.
ParamList: Name of the field, minimum length and maximum length. When reading the configuration file, by using reflexion, the UIFactory.createConstrainedField (String fieldName, String minLength, String maxLength)is invoked.

Custom Beans are java classes in which all UI elements can be defined.They ares not as configurable as the DataInputBean.java class, but they are widely used in Oracle Retail Point-of-Service.

These beans are referenced in the *uicfg.xml files but the definition of the UI elements are done in java.

Example 11-21 is an example of a custom bean java class:

Example 11-21 customeruicfg.xml

    <BEAN
            specName="CustomerAddSpec"
            configuratorPackage="oracle.retail.stores.pos.ui"
            configuratorClassName="POSBeanConfigurator"
            beanPackage="oracle.retail.stores.pos.ui.beans"
            beanClassName="CustomerAddBean">
    </BEAN>

Updating MaxLength and Size of Multi-byte Fields

Do the following to update the maxLength and size of those fields that can support multi-byte characters:

Identify the field to be updated in the UI.

If the field is created inside a Custom Bean, open the class and look for the initializeField method. This method creates and initializes all screen UI elements.

Use the overloaded constructors from the UIFactory to create the field with the new maxLength:

UIFactory.createConstrainedField(String name, String minLength, String maxLength, String columns)
UIFactory.AlphaNumericTextField createAlphaConstrainedField(String name, String minLength, String maxLength, String columns)
UIFactory.ValidatingComboBox createValidatingComboBox (String name, String emptyAllowed, String columns)

Identify the size of the equivalent database column. The new field maxLength is the database column size divided by four.

The current maxLength will be the new size/columns. The new field maxLength will be the DB Column size divided by 4.

Note:
If the size isn't passed as an input parameter, then internally, size = maxLength.

For dropdown boxes, no maxLength or size is specified.

To make it a standard when defining the new size of the field, use the size of the longest element displayed in the input box. For example, suppose the database column FirstName in the database was updated from 16 to 80.

Update from:
```
firstNameField = uiFactory.createConstrainedField("firstNameField", "2", "16");
```
to:
```
firstNameField = uiFactory.createConstrainedField("firstNameField", "2", ”80”, "16");
```

Identify where this field is being created. Look into the *uicfg.xml which represents the current UI screen.

If the field is created inside a DataInputBean, the entire configuration is done in the *uicfg.xml.From:

        <FIELD fieldName="firstNameField"
               fieldType="ConstrainedField"
               labelText="First Name:"
               labelTag="firstName"
               paramList="firstNameField,2,16 />

to:

        <FIELD fieldName="firstNameField"
               fieldType="ConstrainedField"
               labelText="First Name:"
               labelTag="firstName"
               paramList="firstNameField,2,80,16 />

UIFactory.createConstrainedField(String name, String minLength, String maxLength, String columns) is called.

Determine if the field to be updated is being created in a Custom Bean or through the DataInputBean. In the *uicfg.xml file, look for the <BEAN> that contains the screenSpec. Look into the beanClassName attribute. It has the name of the bean class that creates the UI elements for the screen.

Allowing or Disallowing UI Fields to Accept UTF8 Characters

Do the following to allow or disallow UI fields to accept UTF8 characters:

Identify the field to be updated in the UI.

If the field is created inside a Custom Bean, open the class and look for the initializeField method. This method creates and initializes all screen UI elements.

Use the overloaded constructors from the UIFactory to set the doubleByteCharsAllowed flag to false. By default the flag is set to true.
```
UIFactory.createConstrainedField(String name, String minLength, String maxLength, String columns, false)
```
Use this constructor if you also want to change the maxLength and size.
```
UIFactory.createConstrainedField(String name, String minLength, String maxLength, false) 
```
Use this constructor if you want to keep the same maxLength and size.
```
UIFactory.AlphaNumericTextField createAlphaConstrainedField(String name, String minLength, String maxLength, String columns, false )
```
Use this constructor if you also want to change the maxLength and size.
```
UIFactory.AlphaNumericTextField createAlphaConstrainedField(String name, String minLength, String maxLength, false )
```
Use this constructor if you do not want to change the maxLength and size.
```
UIFactory.DriversLicenseTextField createDriversLicenseField(String name, String minLength, String maxLength, String columns, false )
```
Use this constructor if you also want to change the maxLength and size.
```
UIFactory.DriversLicenseTextField createDriversLicenseField(String name, String minLength, String maxLength, false )
```
Use this constructor if you do not want to change the maxLength and size.

Identify where this field is being created. Look into the *uicfg.xml which represents the current UI screen.

If the field is created inside a DataInputBean, the entire configuration is done in the *uicfg.xml.

From:

        <FIELD fieldName="firstNameField"
               fieldType="ConstrainedField"
               labelText="First Name:"
               labelTag="firstName"
               paramList="firstNameField,2,16 />

to:

        <FIELD fieldName="firstNameField"
               fieldType="ConstrainedField"
               labelText="First Name:"
               labelTag="firstName"
               paramList="firstNameField,2,80,16, false />

when you want to change the maxLength and size.

Or:

        <FIELD fieldName="firstNameField"
               fieldType="ConstrainedField"
               labelText="First Name:"
               labelTag="firstName"
               paramList="firstNameField,2,16, false />

when you do not want to change the maxLength and size.

One of the following is called:

UIFactory.createConstrainedField(String name, String minLength, String maxLength, String columns, false )
UIFactory.createConstrainedField(String name, String minLength, String maxLength, false )

Determine if the field to be updated is being created in a Custom Bean or through the DataInputBean. In the *uicfg.xml file, look for the <BEAN> that contains the screenSpec. Look into the beanClassName attribute. It has the name of the bean class that creates the UI elements for the screen.

Connections

Connections configure the handling of an event in the UI Framework. They are used to define inter-bean dependencies and behavior and to tie the bean event responses back to the business logic. When one bean generates an event, another bean can be notified of the event. Connections have a source bean, a Listener Type for the target, and a target bean.

Connections attach a source bean to a target bean, which receives event notifications from the source bean. The Listener Type specifies which type of events can be received. The XML in the following sections is found in <source_directory>\applications\pos\src\oracle\retail\stores\pos\services\tender\tenderuicfg.xml. Other listeners used in Point-of-Service include ConfirmCancelAction, HelpAction, and CloseDialogAction.

ClearActionListener

ClearActionListener is an interface that extends ActionListener in Swing to make it unique for its use in Point-of-Service. The following code shows how this listener is used in an overlay specification. Adding the ClearActionListener allows Clear to erase the text in the selected field in the work area when Clear on the GlobalNavigationPanelSpec is clicked.

Example 11-22 tender.xml: ClearActionListener XML tag

<CONNECTION
       listenerInterfaceName="ClearActionListener"
       listenerPackage="oracle.retail.stores.pos.ui.behavior"
        sourceBeanSpecName="GlobalNavigationPanelSpec"
               targetBeanSpecName="CreditCardSpec"/>

DocumentListener

DocumentListener is an interface defined in Swing. The following code shows how this listener is used in an overlay specification. Adding the DocumentListener allows the Clear button on the GlobalNavigationPanelSpec to be disabled until input is entered in the selected field on the work area.

Example 11-23 tender.xml: DocumentListener XML tag

<CONNECTION
            sourceBeanSpecName="CreditCardSpec"
            targetBeanSpecName="GlobalNavigationPanelSpec"
            listenerPackage="javax.swing.event"
            listenerInterfaceName="DocumentListener"/>

ValidateActionListener

ValidateActionListener is an interface that extends ActionListener in Swing to make it unique for its use in Point-of-Service. The following code shows how this listener is defined in an overlay specification. Adding the ValidateActionListener allows the CreditCardSpec to recognize when the Next button on the GlobalNavigationPanelSpec is clicked, resulting in the validation of the required fields on the work area. If the required fields are empty, an error dialog appears stating that the required field(s) must have data.

Example 11-24 tender.xml: ValidateActionListener XML tag

<CONNECTION
        listenerInterfaceName="ValidateActionListener"
        listenerPackage="oracle.retail.stores.pos.ui.behavior"
        sourceBeanSpecName="GlobalNavigationPanelSpec"
        targetBeanSpecName="CreditCardSpec"/>

The fields that are required must be specified for this listener in the overlay specification for the target bean, as in the following XML from tenderuicfg.xml.

Example 11-25 tenderuicfg.xml: ValidateActionListener Required Fields

<ASSIGNMENT
   areaName="WorkPanel"
   beanSpecName="CreditCardSpec">
   <BEANPROPERTY
      propName="RequiredValidatingFields" propValue="CreditCardField,ExpirationDateField"/>
   </ASSIGNMENT>

Text Bundles

Currently, over forty text bundles exist for the Point-of-Service application. Many of these bundles are service-specific. A properties file with the same name exists for every language, located in <source_directory>\applications\pos\locales\<locale name>\config\ui\bundles with the language name appended to the filename. For example, the Customer service would have its text defined in the customerText_en.properties file in English.

A similarly named properties file would exist for each locale. Because they are discussed earlier in the chapter, service-specific bundles and the dialogText bundle are not described in this section.

parameterText

In overlay specifications, the parameterText bundle is specified to define the text for particular screens. For example, the following code from <source_directory>\applications\pos\src\oracle\retail\stores\pos\services\admin\parametermanager\parameteruicfg.xml defines text for the PARAM_SELECT_PARAMETER overlay screen. On this screen, the names of the parameters found in the parameterText properties file are displayed.

Example 11-26 parameteruicfg.xml: Overlay Specification Using parameterText

<OVERLAYSCREEN
        defaultScreenSpecName="EYSPOSDefaultSpec"
        resourceBundleFilename="parameterText"
        specName="PARAM_SELECT_PARAMETER">

In the utility package, the ParameterManager is used to retrieve parameter values. The following code from <source_directory>\applications\pos\src\oracle\retail\stores\pos\utility\GiftCardUtility.java shows how a parameter is retrieved from the ParameterManager. The handle to the ParameterManager, pm, is passed into the method but originally retrieved by the code ParameterManagerIfc pm = (ParameterManagerIfc)bus.getManager(ParameterManagerIfc.TYPE);

Example 11-27 GiftCardUtility.java: Tour Code to Retrieve Parameter

public static final String DAYS_TO_EXPIRATION_PARAMETER = "GiftCardDaysToExpiration";
daysToExpiration = pm.getIntegerValue(DAYS_TO_EXPIRATION_PARAMETER);

In the parameterText_<language>.properties file, the corresponding text is defined. This text is displayed on the Parameter List screen when viewing Security options and choosing the Tender parameter group.

Example 11-28 parameterText_en.properties: Text Bundle

Common.GiftCardDaysToExpiration=Days To Giftcard Expiration

The value of the parameter is defined in <source_directory>\applications\pos\deploy\shared\config\parameter\application\application.xml by the code sample below. Each parameters belongs to a group, a collection of related parameters.

Example 11-29 application.xml: Definition of Parameter

<PARAMETER name="GiftCardDaysToExpiration"
         type="INTEGER"
         final="N"
         hidden="N">
         <VALIDATOR class="IntegerRangeValidator"
            package="oracle.retail.stores.foundation.manager.parameter">
            <PROPERTY propname="minimum" propvalue="1" />
            <PROPERTY propname="maximum" propvalue="9999" />
         </VALIDATOR>
         <VALUE value="365"/>
</PARAMETER>