External Component Pieces
Overview of the Pages generation mechanisms
THE CPQ UI MVC IMPLEMENTATION
The CPQ UI is built following the standard architectural pattern Model-view-controller (MVC). It isolates the business logic from the user interface to modify either the visual appearance of the application or the underlying business rules without affecting the other.
The application is divided into three layers. Each layer handles specific tasks and has specific responsibilities to the other areas.
- A model represents business data and business logic or operations that govern access and modification of this business data. The model notifies views when it changes and provides the ability for the view to query the model about its state. It also provides the ability for the controller to access application functionality encapsulated by the model.
- A view renders the contents of a model. It accesses data from the model and specifies how that data should be presented. It updates data presentation when the model changes. A view also forwards user input to a controller.
- A controller defines application behavior. It dispatches user requests and selects views for presentation. It interprets user inputs and maps them into actions to be performed by the model. A controller selects the next view to display based on the user interactions and the outcome of the model operations. ‘Value Objects’ represents model outcomes allowing the separation between the View layer and the Model layer.
- End-user triggers some action from the View
- The controller processes the action and calls the Model (business layer )
- Exchange objects (‘Value Objects’) are created
- The controller defines which information is provided to the View
- The View displays information to the end-user
The Configurator uses the Struts framework providing an implementation of the MVC model.
Definition: Apache Struts is an open-source web application framework for developing Java EE web applications.
Struts provides a centralized page-flow management via the struts-config.xml file.
Here is a typical example of Struts mechanisms. During the configuration of your product, some information needs to be collected from the user as inputs and then be processed.
- In order to get the users information, a HTML form is used. The user requests this form and fills it. User inputs can come from several widgets, such as text fields, text boxes, check boxes, pop-up menus, and radio buttons.
- Then he submits the form containing its inputs to a URL (e.g. submit.do) by clicking on ‘OK’ button. This URL address is mapped by Struts to an action. The purpose of this action is to perform the appropriate actions on the user input gathered from the form. This action is executed.
- a form bean (called ‘Actionform’ is automatically created to store the user incoming data.
- the action invokes business logic and data-access logic, placing the results in other beans stored in request, session, or application scope.
- the action returns an output ‘condition’ (called ‘ActionForward’ object which depends on the result of the business logic process). These conditions are mapped by Struts to various JSP pages (E.g. It is possible to forward to a given page if the data processing has been successful, another different one in case of failure...Etc.).
- Struts automatically forwards the requests to the appropriate JSP page
THE CPQ UIVIEW LAYER
The View layer of the UI engine is designed to dynamically build resulting JSP pages in a standard, reusable and flexible way. Tile technology coupled with Struts is used to achieve these goals.
Definition: A Tile is an area in a web page, a “part of a page that you assemble to build another part or a full page”.
In the example below, the Tile framework allows to dynamically assembly the rendered page from a standard sketch described in HTML and the description of each area or Tile in a JSP file (Header, Menu, Body, Footer).
With CPQ UI, the Designer is able to create his own sketch of resulting view in a Layout XML file passed as a parameter when running your configuration.
The rendered page structure is dynamically computed from information provided by the layout file and the information of the modeled configurable product or catalog. Tile technology allows positioning and dimensioning the different components of your page. Each part of the page is viewed as a Tile either ‘simple’ or ‘complex’ (i.e. made of nested tiles).
Example of the main page container:
THE CPQ UIWORKFLOW
The CPQ UI retrieves and loads the configuration/catalog data based on information given in the Settings and Layout XML file. During the configuration of his product, the user answers the questions and navigates from a form to another one, form a catalog page to another one. The generated pages are refreshed accordingly following the user interactions.
As each page is represented by a collection of individual tiles (Selectors, configuration box, form properties are separate tiles), when the client submits some data to the server, a full refresh of the page is not necessary.
Step-by-Step process
- [GUI Mapping Init]
During the page rendering initialization, the HTML corresponding to each tile is generated. Each tile is responsible to register itself in a session object called GuiMappings.
Registered information:
- Data object Ids: all objects (Form Properties, Configurable Products, etc…) in relationship
with the tile and whose change leads to a reload of the tile have to be registered.
- The decision to refresh the tile is based on this set of object IDs (set of CPE). If the state of one of these objects has changed, then the tile has to be reloaded. The state of each object is monitored via a Watching Set that is able to indicate to the Controller an object change.
- Mapping information: a link between the tile’s identifier and its corresponding HTML ID in the rendered page is stored.
- Data object Ids: all objects (Form Properties, Configurable Products, etc…) in relationship
- [User Interactions]
When the user changes the data in some form property and validates his changes, an Ajax request is sent to the server.
- [Refresh Mechanisms]
The list of modified objects is retrieved from the Ajax request. A list of all impacted and monitored objects is built thanks to the watching sets.
This list is sent by the controller to the engine API. Data updates are executed and the updated list of watching sets is returned.
The new page can be generated. All components marked as ‘to be refreshed’ by the API are associated to their tile JSP definition (through the GUI Mapping) and then gathered to be returned via an Ajax request to the client. A client-side JavaScript action is responsible to substitute the tiles' current content with the new one.
How to build an external component?
Step-by-step development process:
- [Setting the development environment up]
The first step to develop an external component is to create a new Java project and include the externalComponentFramework.jar in the project’s classpath.
This library contains the interfaces and abstract classes, needed for the creation of the component's controllers and actions.
[Creating the Controller]
As complying with the Model-View-Controller architecture, the creation of each component and tile starts with the development of a controller class.
The controller may have to interact with the ConfiguratorUI Service Layer or the CatalogUI Service Layer – to extract data from the Layout file (translations, dimensions, images), and also to interact with the Configurator Engine Layer – to extract the data for the model (Object states, Form Property values etc…)
[Creating the View]
- JSP design
You create the presentation of the tile thanks to a JSP
- Tile assembling
You integrate the new Tile into the Struts framework
- JSP design
- [Managing Actions] (if your component triggers actions)
- Form bean creation
- Actions design
- [Packaging and deploying the component]
- [Running the component]
The external component is now ready to be displayed in the application page and can be called from the Layout XML file.
Warning: The project is developed with JDK 1.5 which is the minimum JDK recommended version.Reference: The full code listing of examples used in this tutorial is part of in the standard CPQ delivery and can be found in $CPQ_INSTALL_DIRECTORY/doc/:ExternalComponentsSamples.zip(code listing)externalComponentsFramework.jar(internal CPQ library)
The tutorial examples are focused on the Configurator UI. However, the way to build
external components for the Configuration Process or for the Catalog is identical.
A service layer is available for the Configuration and another on for the Catalog:
// Gets the Configurator UI service layer
ConfiguratorUIService configUIService =
(ConfiguratorUIService)request.getSession().
getAttribute(ConfiguratorUIService.CONFIGURATOR_UI_SERVICE);
// Gets the CatalogUI service layer
CatalogUIService catalogUIService =
(CatalogUIService) request.getSession().
getAttribute(CatalogUIService.CATALOG_UI_SERVICE);
However, the usage of other JS frameworks (jQuery, Mootools…) is not supported for the external components as they may be incompatible with some prototype.js features.