CONCEPT

Overview

As mentioned above, the layout of each rendered web page is defined by the Layout XML file.

The layout is defined for a given theme, and the xml file will structure the rendering of the page. The CPQ UI engine allows multiple themes in order to address multiple sales channels (end-customers, partners, internal sales people, etc.) for a given model.

The Layout XML file is structured as follows (example of the Configurator layout file):

For a given theme (<thema> section), you will be able to describe:

• The structure of each page (<homePage>, <configurationPage>, <summaryPage> for the Configurator and Need Analysis User interface; <homePage>, <collectionPage>,

  <productPage>, <searchPage> …for the Catalog User interface) in the <organization> section.

The <component> section gathers the description of value selectors used in all the pages.

• The localized graphical resources (<resources> section),
• The Cascading Style Sheets (<layout> section) that make up the design,
• The translations (<translations> section) associated to the components of your pages
• The settings driving the user interface behavior during the configuration: <settings> section
  The Theme associated to the layout is defined at the beginning of the XML file::

  <thema name="catalogXXXX">

  The ‘name’ of the theme corresponds to the name of the directory in \cameleon.ear\cameleonUI.war\theme\.

  Note: A Layout file is defined for only one theme. To manage several themes, you have to create as many Layout files as needed.

Attribute Details

HOW TO CREATE A NEW THEME

We recommend creating a new theme based on the standard theme delivered with CPQ

1. Duplicate the standard theme folders (‘configuratorDesktop/catalogDesktop’) and rename the directory (avoid special characters)
2. Duplicate the corresponding Layout XML file
3. Replace the name of the theme: **
4. If necessary, modify the resources path pointing to the previous theme directory:

   theme/catalogDesktop/images/icons/btnCompare.png theme/catalogDesktop/images/btn/btnAd dToCompare2_en.png

5. If necessary, modify your CSS files content anywhere absolute paths are used.

PAGES SEQUENCING FOR THE CONFIGURATION PROCESS (CP) AND GUIDED SELLING PROCESS (NA)

Overview

The CPQ User Interface of the Configurator and Guided Selling process provides 5 kinds of pages:

• A HomePage that is optional
• One or several ConfigurationPage designed to support the entire configuration process. A configurationPage corresponds to one or many configuration steps.
• A SummaryPage that is optional
• A ManufacturingPage that is optional
• An ErrorPage to which the end-user can be redirected anytime an unexpected error has been raised.

HomePage (Optional) – <homePage>

The HomePage is optional and usually introduces an overview of the Configurable Product.

It basically gathers all necessary information to present the product (images, text, characteristics, etc.), to give information about the product (documents, files, etc.) and to sell the product (links to other products, start configuration, etc.)

As example, the following information may be displayed:

• Image, Name, Description, RMO text
• Business property tab
• Resource tab (tab including the RMO files)
• Related Items tabs

This page also includes specific actions that are usually:

• “Back-to-Catalog” (when integrated in a catalog)
• “Start Configuration”

ConfigurationPage – <configurationPage>

One or several Configuration pages aim at guiding the end-user by means of a dynamic dialog, making the whole configuration process easier.

If necessary, this ConfigurationPage can be instantiated multiple times, every instance will correspond to a high-level configuration step (meaning that it will correspond to a form or a configurable product directly attached to the root configurable product).

This page also includes user actions that are usually:

• “Back-to-configuration”,
• “Add-to-cart” of the configured product

  BundlePage –

The Bundle page aims at offering the user the capability to select products organized in a structured hierarchy.

The result is a consistent assembly of products that can be used in the configuration process output. This page also includes user actions that are usually:

• “Add-to-cart” of the configured product
• “Undo” to cancel last choices
• “Optimization” to open the optimization flyer

  SummaryPage (Optional) –

The summaryPage is optional and usually represents the result of the configuration process. As example, following information may be displayed:

• Generated names, descriptions, prices and business properties
• Generated sales breakdown including the pricing details
• Result of the partial matching
• Etc…

This page also includes user actions that are usually:

• “Back-to-configuration”,
• “Add-to-cart” of the configured product

Actions may also be associated with specific external actions such as:

• “Print configuration”
• “Check delivery time” …

ManufacturingPage (Optional)– <manufacturingPage>

The manufacturingPage is optional and represents the result of the manufacturing process. As example, following information may be displayed:

• Bill of material
• Routings
• Etc. …

ErrorPage – <errorPage>

The errorPage is used to display a custom error message when an unexpected error has been raised during the configuration process.

For the end-user, the navigation through the different pages depends on his actions as shown in the following diagram:

Attributes Details

Definition: A configuration step (identified by a seqOrder) corresponds to a given first level node of the configurable product breakdown.

PAGES SEQUENCING FOR THE CATALOG

Overview

The CPQ User Interface of the Catalog provides 9 kinds of pages:

• A HomePage
• One or several CollectionPage designed to browse the Catalog and display the list of contained products.
• A SearchPage for quick and advanced search
• A Compare Page
• One or several ProductPage to display the product characteristics
• One or several ConfigurableProductPage to run a configuration process
• A Quote Page to have an overview of the current quote content
• A Need Analysis page to run the guided selling process and display the resulting products
• An ErrorPage to which the end-user can be redirected anytime an unexpected error has been raised.

HomePage – <homePage>

The HomePage is optional and is usually the entry point of the Catalog.

It basically allows the end-user to browse the Catalog by using menu bars, displays the main collections and highlights some product/collection/guidedSelling process thanks to teasers.

CollectionPage – <collectionPage>

One or several collection pages aim at displaying multimedia content and/or list of products.

If necessary, the CollectionPage can be instantiated multiple times depending on the userType of the collection currently displayed.

SearchPage – <searchPage>

The search page allows the end-user to look for products in the whole Catalog or in sub-collections. He can search by entering a partial name, description of the product but also use an advanced search based on product criteria.

ComparePage – <comparePage>

While browsing the Catalog, the end-user can add some products to the comparator. Then he can access the ComparePage to display a table allowing to compare the properties of these items.

ProductPage – <productPage>

The productPage basically displays the characteristics of products as well as their prices and linked products. Moreover, it displays the multimedia elements associated to the current products and allows the end-user to add it to the quote.

This page is accessed when the ACTIVATE_CURRENT action is triggered.

ConfigurableProductPage – <configurableProductPage>

The configurableProductPage aims at displaying the configurationProcess.

When a configuration process is contained in the Catalog, the CPQ UI redirects the user to this page when the CONFIGURE action is triggered.

This page is a standard Catalog page containing an ‘inclusion’ allowing to embed the

configurationProcess User Interface in the Catalog.

CartPage – <cartPage>

The cartPage displayed a simplified version of the Quote spreadsheet.

Only 1 quote level can be displayed and the end-user can only delete quote lines or change the associated quantities.

NeedAnalysisPage – <needAnalysisPage>

The needAnalysis page allows to display a guided selling process when this process is attached to a catalog sub tree.

A dialog is proposed to the end-user, allowing him to retrieve a set of products contained in the sub tree and matching his needs.

ErrorPage – <errorPage>

The errorPage is used to display a custom error message when an unexpected error has been raised.

For the end-user, the navigation through the different pages depends on his actions as shown in the following diagram.

Basically, the end-user enters the Catalog via the HomePage. Then he can browse the collections using the vertical selector or the menu bar.

Once he has accessed a collection and displayed a list of products, he can directly add the products to the quote or go to the product page to display the product characteristics.

The ‘tool’ pages (ComparePage, CartPage, SearchPage) can be accessed from any page of the Catalog thanks to OPEN_PAGE actions.

The Guided selling process is either embedded in the collectionPage if its context is the currentCollection, or in a specific Catalog page if its context is the currentSubTree.

Attributes Details

E.g.

collectionPage userType="ut1;ut2"> … </collectionPage>

<collectionPage seqOrder="*"> … </collectionPage>

HOW TO EMBED A CONFIGURATION PROCESS IN A CATALOG

A collection can contain a set of products but also configurable products. In that case, CPQ UI will launch the configuration process directly in the Catalog.

When a configurable product is displayed for example in a collectionPage (in a product list) or in a productPage, it is possible to declare a CONFIGURE action in the layout XML file.

As soon as the end-user activates the CONFIGURE action, he is redirected to the configurableProductPage corresponding to the selected Configurable Process.

Design Phase

1. [Designer]

   Add a configuration Process to a Catalog collection.

2. [In the Catalog Layout File]
   1. Allow the access to the configuration process

In a collectionPage or in a productPage, make sure that the CONFIGURE action has been parameterized.

<actionBox …>

<action cssName="actionBoxHover" actionName="CONFIGURE" alignment="right" resourceName="action.configureNow" translationName="action.configureNow" url=""/>

</actionBox>

1. Define the layout of the configurableProductPage The configurable product page is a standard catalog page whose main part contains an ‘Inclusion’. An inclusion is a box that will display the Configuration Process user interface inside a catalog page.

<mainPart …>

<inclusion sourceName="ConfiguratorUILayout" widthPercent="100" heightPercent="100" hzAlignment="left" vtAlignment="up" autosize="on"/>

</mainPart>

1. Point to the Configurator layout to be used while running the configuration process.

<inclusions>

<source name="ConfiguratorUILayout">configuratorUIDesktop.xml</source>

</inclusions>

1. [In the Configurator Layout File]

   You may have to adapt the layout of the configuration pages as the configuration process will be run directly in the Catalog (e.g.: removal of the pages header, footer etc.)

2. [In the XML Catalog Setting File]

   Add the Settings (Sales and pricing method, custom settings etc.) required to run the configuration process.

   RunTime Phase

Now you can run the Catalog.

Browse the Catalog until finding a configurable process (either in a product list or via the productPage for example) and click on “Configure Now” to access the configurable product page and launch the configuration process.

Only 1 XML setting file is used to initialize the catalog and all the contained configurable processes. When the end-user clicks on the configure button, CPQ UI initiates a configuration session using the same input settings as for the catalog session and replacing/adding on the fly the following CPEs:

<cam:Param cpe="CPE.Settings.Session.Workspace" value="currentCPWorkspace" />

<cam:Param cpe="CPE.Settings.Session.CPName" value="currentCPName" />

If the configuration is launched from a Standard Item, the CPQ UI passes the identifier of the contextual standard item as a setting of the configuration session:

<cam:Param cpe="CPE.Settings.Session.RefSI" value="workspace/SI/mySelectedSI"/>

E.g.

<configurableProductPage userType="ut1;ut2">… </configurableProductPage>

<configurableProductPage seqOrder="*"> … </configurableProductPage>

Each time a SetSetting(s)() method on such kind of setting is called from the Configurator, then this setting is available in the Catalog session, and then, by definition, will be passed to the next configuration session.

The guided selling process UI is similar to the configurable process. It uses the same page and XSD schema.

Design Phase

1. [Designer] Once you have designed the guided selling process (needAnalysis), you have to attach it to a collection and define the scope of the filterMethod.

- currentCollection: the guided selling process will return a list of products which is a subset of the ones contained in the current collection. - currentSubTree: the guided selling process will return a list of products which is a subset of the ones contained in the current catalog branch (current collection and sub collections).

1. [In the Catalog Layout File]
   1. Allow the access to the guided selling process via the needAnalysisBox In the collectionPages and in the needAnalysisPage, make sure that the needAnalysisBox has been parameterized.

<needAnalysisBox mode="on" cssName="needAnalysisBox" widthPercent="100" heightPercent="100" hzAlignment="left" vtAlignment="up" titleTranslationName="title"

autosize="on" framedBox="off" >

<inclusion sourceName="needAnalysis" widthPercent="100" heightPercent="100" hzAlignment="left" vtAlignment="up" autosize="off"/>

<actionBox mode="on" cssName="actionBoxTransparenct" hzAlignment="center" vtAlignment="down" widthPercent="100" heightPercent="8" autosize="off">

<action actionName="RESET" alignment="center" resourceName="" translationName="action.clearAll" url=""/>

<action actionName="SEND_CUSTOM_EVENT(eventName=applyBreakdown)" alignment="center" resourceName="btnFind" translationName="action.sendCustomEvent.find" url=""/>

</actionBox>

</needAnalysisBox>

1. Define the layout of the guided selling user interface The guided selling dialog is similar to a configuration process and it is embedded into the needAnalysisBox

<inclusion sourceName="needAnalysis" widthPercent="100" heightPercent="100" hzAlignment="left" vtAlignment="up" autosize="off"/>

1. Point to the layout file to be used.
   <inclusions>:

   <source name="needAnalysis">guidedSellingUIDesktop.xml</source>

   </inclusions>

   1. [In the Configurator Layout File] You may have to adapt the layout of the configuration pages.
   2. [In the XML Catalog Setting File] Add the Settings (Sales and pricing method, custom settings etc.) required to run the guided selling process.

      RunTime Phase

Now you can run the Catalog.

Browse the catalog to display a collectionPage linked to a needAnalysis.

Depending on the context, the needAnalysis will be displayed in the needAnalysisBox directly in the collectionPage (scope = currentCollection) or in a dedicated needAnalysisPage (scope = currentSubTree)

The products returned by the needAnalysis are displayed in a productResultBox.

The products returned by the needAnalysis are displayed in a productResultBox.

(1 configurationPage having 1 mainPart displaying the guided selling dialog and using simple value selectors)

PARTS POSITIONING

Overview

A page (Home, Configuration, Summary or Error for the Configurator or Collection, Search, Quote, Product etc. for the Catalog) is made of 3 main parts:

• An optional header in which all elements are optional
• A main area divided into 3 sizable columns (Left, Main, Right) underneath optional Horizontal Upper Parts and above optional Horizontal Lower Parts
• An optional footer made of several texts or links aligned left, right or center in the middle of the page.
  
  

Into each part, several user interface components can be placed.

Reference: You will find hereafter a brief description of the predefined UI components. Please

refer to: Components parameterization.

Attributes Details

Each part can be positioned and sized by setting its attributes.

You can find in the following table the list of attributes corresponding to each one of these parts:

• <header>
• < hzUpperPart > (repeatable section)
• < leftPart >
• < mainPart >
• < rightPart >
• < hzLowerPart > (repeatable section)
• < footer>

Reference: For more details on the layout dimensions, alignment and autosizing, please refer to: UI bricks positioning.

Visual Identity

The page main part, header and footer background can be customized in their respective CSS files (e.g. ‘homePage.css’, ‘configurationPage.css’)

COMPONENTS PARAMETERIZATION OVERVIEW

You can find in the following table the list of UI components that can be included into the different parts of the pages.

Reference: For more details on the properties you can use to customize the design and behavior of these components, please refer to: Page Components.

The presentation of the user interface can be dependent of the users’ country and language (meaning that the text and graphical resources should in some circumstances be “translatable”). Therefore, the theme enables the specialization of translations, graphical resources and style sheets for certain languages.

REVIEWING TERMINOLOGY AND TRANSLATIONS

Labels and messages displayed in the user interface can be specified depending on the languages (e.g. <localizedTranslations lang="EN,IT,ES"> for English, Italian and Spanish).

Translations are divided into two sections:

• The <genTranslations> section gathers the standard messages required by the application to ensure its correct behavior
• The <customTranslations> section gathers the custom messages (Popup titles, box descriptions

  … )

  A translated element is identified by its name (xxxTranslationName="ID_OfTranslatedElmt"). This name links the element to the translation itself which is declared in the section:

  <translation name="ID_OfTranslatedElmt"> Translation </translation>

  Tip: You can insert CPEs in your translated messages. CPE has to be put between braces. These CPE have to be valuated when the session starts (e.g. settings). It is not currently possible to use dynamic CPE.

  E.g.

  <translation name="myId2">

  Enjoy the new {CPE.rootCP.wks/FO/fo1.descr}

  </translation>

  All default translations and message keys are listed in the ‘messagesResource.properties’ files::

  $cpq_home_folder$/conf/messages/

  The default translations can be overridden per layout file.

  <translation name="messageKey_fromMessagePropertiesFile">

  Overridden translation message

  </translation>

  <translation name="itemGrid.comboBox.TitleMessage">

  Select products :

  </translation>

For instance, it is possible to customize the looped instances description pattern with the following parameter in the messagesResource.properties:

For instance, to override in the layout file:

configuratorUI.system.valueSelector.none=(aucun)

You will have to place in the corresponding translation the following suffix:

valueSelector.none=yourNewValue

USING GRAPHICAL RESOURCES

Once the messages and translations have been reviewed and localized, the same can be done with resources. ‘Static’ resources (status icons, title images etc.) are directly referenced in the layout file in order to be easily translated from the XML.

<resource name="ID_OfTheIcon">

theme/My_THEME_Name/images/MyIcon.gif

</resource>

The graphical resources have to be located under the following folder: $cpq_home_folder$/ …

/cameleon.ear/configuratorUI.war/

We advise you to classify these resources depending on their related theme.

All other resources related to the theme of the pages (background, colors, fonts, margins …) belong to the CSS files.

Each component of the user interface is associated to a style sheet which allows customizing its display and personalizing the visual identity of the pages.

Components and CSS association

When the UI engine generates the pages from the layout XML file, each UI component corresponds to a HTML structure. A UI component is associated (through the attribute ‘cssName’) to a CSS controlling its HTML rendering.

It allows for example to associate different colors depending on the collections.

The CSS usage provides a powerful and flexible mean to completely customize the final generated pages. It is possible to apply a separate stylesheet to each individual box or to re-use the same CSS to keep some graphical consistency.

In the <layout> section, you indicate which CSS file contains the description of the ID_OfTheCSS:

<css name="ID_OfTheCSS">

NameOftheCSSfile.css

</css>

Four main style sheet categories exist:

• <genStyleSheet>

  CSS corresponding to the start page and the systemException pages

• <pageStyleSheet>

  CSS associated to the different pages (Home Page, Summary Page…) and the headers and footers.

• <componentStyleSheet>

  CSS associated to the standard boxes and components used within the different parts of the pages.

How to apply a visual identity to the Page components?

As described above, each UI element display is driven by a main CSS class that identifies its main <div>. Then ‘secondary’ CSS classes allowing to customize the sub-parts of the element are generated by the UI engine. Their names cannot be changed.

All secondary classes in a CSS file have to be defined in the context of the main class (in order to ensure that the CSS inheritance mechanism correctly applies).

.myMainClass .mySecondaryClass .myOtherSecondaryClass { /* description of my other secondary class */ }

When adding a component into a part of a page, you can either associate an existing CSS class or to create a new one in order to change the appearance of this specific object.

1. [Associate the CSS main class to the component]

   <combinedBox cssName="ID_OfTheCSSMainClass" ….>

2. [Declare a new CSS file]

In the <layout> section, declare a CSS file name that will contain the code of your main class (and secondary classes)

Create as many CSS files as necessary in particular if the CSS content depends on the language. The ID of the CSS has to be unique for a given localizedLayout.

<css name="ID_OfTheCSSMainClass ">

ExampleOfName.css

</css>

1. . [Create the CSS file]

In the CSS folder: $cpq_home_folder$/...

/cameleon.ear/cameleonUI.war/theme/My_THEME_Name/css/ create the ExampleOfName.css file.

We advise you to create this CSS by copying an existing CSS file from the standard CPQ theme and which is associated to the same kind of component.

The goal is to retrieve a template of all classes you can further adapt depending on your needs.

1. . [Modify the CSS file]

If you have copied an existing CSS file from the standard theme, replace the main class name by your new class name ‘ID_OfTheCSSMainClass’

E.g.:

A dedicated file in the Theme directory (cssConstants.properties) allows to define variables for the colors of the theme:

$Main-Color=hsl(200, 69%, 48%)

$Other-Light-Txt-Color=hsl(0, 0%, 83%)

$Light-Txt-Color=#FFFFFF …

Once declared in the cssConstants file, these variables can be used in the CSS files: E.g.

.itemSheet .itemDescr a {

color: $Other-Light-Txt-Color;

}

The variables are automatically replaced by their values during the CSS concatenation process described in the next paragraph.

This mechanism allows to centralize all the color codes in a single file, ensures the consistency of the visual identity of the User interface and eases the modifications of the theme colors.

The default themes Catalog/configuratorDesktop are built so that the font sizes are defined using ‘rem’

The rem unit is relative to the root—or the html—element. That means a single font size on the html element can be defined and all other rem units will be a percentage of that.

The base font-size of 62.5% is used in the themes to have the convenience of sizing rems in a way that is similar to using px

html {

overflow: hidden;

font-size: 62.5%;

}

body { font-size: 1.4rem; } /* =14px */

h1 { font-size: 2.4rem; } /* =24px */

Reference: For more details on the CSS Classes used to customize the design of the page components, please refer to: Focusing on page components.

CSS concatenation process

When the CPQ UI web service starts, the UI engine builds (if not already existing) merged CSS files (1 per page). Simultaneously with the merge process, all the variables referenced in the CSS files are replaced by their values (found in the cssConstants.properties file) - The generated merged files does not contain any variable name.

Then the rendered HTML page contains a reference to the merged CSS file plus one separate CSS file for each widget.

The names of merged CSS files are computed as described below.

Name of the merged CSS File: {0}{1}{2}.css?v={3} where

• {0} is either 'home', 'summary', 'config' or 'config'+ seqOrder
• {1} is the language in use
• {2} is the unique ID value calculated as a 32 characters hex string based on the list of all the names of the CSS of the page.
• {3} is the version of the model as entered into the layout file:

  eConfiguratorUI version="1.0"

  Note:

  Each time the application starts, the hash ID for the current model is calculated. Then CSS is

  searched with corresponding name. If not found – it is created.

  Each time the server starts, all generated CSS files are deleted in order to be refreshed

  Note:

  When customizing the CSS or the cssConstants.properties file, you have to modify your classes in the original CSS files (and not the merged ones), and delete the temporary merged files from the CSS folder in order to deploy your modifications.

  To delete the merged CSS files you can:

  • either delete manually the generated CSS files
  • launch the CPQ UI from the Designer and use the option Empty Model Cache = ‘This Working Version (Once)’
  • or use the WS parameter : clearMergedCSSFileOnStartup

    With the last 2 options, the CPQ UI automatically deletes CSS files matching the following pattern:

    NameOfThePage (e.g. catalogPage, cartPage…) + ..*._.css*

In addition to the description of the design, the XML file also contains parameters and describes actions driving the behavior of the user interface.

The end-user is guided along the configuration process. Obviously, he can choose to answer such or such question, to come back into a step to review his inputs, to manually browse the configuration tree. Therefore, some behavior actions are automated to ease the navigation and/or to launch some processes triggered by the user manipulations.

Two main elements are dedicated to drive the Configurator UI behavior: the Actions and the next/previous Policy.

For the Catalog UI, the end-user is free to browse the collection hierarchy (no automation of the next/previous policy) but some actions allow him to reach specific pages.

CPQ UI ACTIONS

Configurator Actions (Configuration and Guided Selling Process)

The user interface allows:

• to apply actions corresponding to events that have been triggered and returned by the engine.
• to raise events that will be sent to the engine (Events triggered by end-user actions for example).
  1. Events triggered by the model

Events coming from the model are described in the “Define Event Logic” step of the Designer. The model can partially control the behavior of the user interface.

They allow for example to activate a FormProperty box as soon as a Form is completed, or create a new instance of a nested Configurable Product as soon as the first one is completed.

1. Events triggered by the user interface

The user interface can trigger and send predefined or custom actions using the element.

• Predefined actions

• Custom actions The user interface can also call on demand actions specified in the model via the ‘Event Logic’ Steps.

In the Designer, these actions are created by defining an ‘onCustom’ event identified by its ‘eventName’. The user interface can call these actions by triggering on demand the event itself using a specific action type: SEND_CUSTOM_EVENT.

Catalog Actions

a. Events triggered by the user interface

The user interface can trigger and send predefined or custom actions using the <action> element.

Rules for actions associated to products

(i.e. ACTIVATE_CURRENT, CONFIGURE, ADD_TO_CART, CONFIGURE_AND_ADD):

A cell or an actionBox can contain the ADD_TO_CART and/or CONFIGURE and/or CONFIGURE_AND_ADD actions. The availability of these actions depends

• on the fact that they are present in the layout file
• AND on the CURRENT_ITEM type:
  • ADD_TO_CART action will be available if the Product is a SI or a SP both eligible and contained in at least 1 collection of the current Catalog
  • CONFIGURE action will be available if the product is
    • either a CP both eligible and contained in at least 1 collection of the current Catalog
    • Or a SI eligible, contained in at least 1 collection of the current Catalog AND linked to a CP with a ‘configurationLink’
  • CONFIGURE_AND_ADD action will be available if the product is a SI eligible, attached to a collection AND linked to a CP with a ‘computationLink’.

By default, a product is considered as eligible. However, an Eligibility BRC can be implemented on the item to prevent the user from adding the item to the quote depending on a given context. The Product is still visible and accessible in the Catalog, but the actions are de-activated. If the Eligibility BRC raises a Business Explanation, this message will be displayed as a tooltip on the ressourceOff button.

Tip:

A Standard Item linked to a Configuration Process via a ‘computationLink’ or ‘configurationLink’ is considered as a Configurable Product by CPQ User Interface.

It means that these products are eligible to the CONFIGURE/CONFIGURE_AND_ADD actions and not to a standard ADD_TO_CART.

When launching the configuration engine via these actions, the CPQ UI passes the identifier of the contextual standard item as a setting of the configuration session:

<cam:Param cpe="CPE.Settings.Session.RefSI" value="workspace/SI/mySelectedSI"/>

How to Call an Action from the User Interface

An action can be called:

1. either from inside an actionBox

   Definition: The action box is a reserved area that can be inserted in the most of the predefined CPQ UI boxes.

   It is possible to add several actions in each actionBox.

An action is associated to a translationName and/or a resourceName.

• If the translationName only is present, it is used as a clickable link or as the title of the button.
• If both translationName and resourceName are present, the translationName is used as a tooltip of the clickable resource.
  1. or from a linkedAction

     Definition: The linkedAction allows to control which kind of action is launched when the end-user clicks on some dynamic elements of the component.

     E.g. if a linkedAction is embedded in an itemSheet, the Name and Description of the displayed item becomes clickable and the corresponding linkedaction is launched.

     Moreover if the linkedAction is associated to a resource, this resource is inserted into the component and is clickable (the translationName is used as a tooltip).

1. Predefined action

In this example, we want to add in the user interface a button in order to SAVE the configuration.

1. Declare in an actionBox (or an actionFlyer) in the Layout XML file an element.
2. Associate to this element the name of the predefined action it will launch (as well as its associated graphical resources).

Example for a SAVE action.

<action actionName="SAVE”… />

1. A click on this new button will call the action.
   1. Custom action

In this example, we want to add in the user interface a button in order to activate a given Form Property.

1.[Prerequisite – In the Designer]

In your model, create an onCustom Event.

2.[Prerequisite – In the Designer] This event named ‘myEvent_FPActivation’ triggers an action ‘Activate’ on the FP you want to be redirected.

1. Declare in an actionBox (or an actionFlyer) in the Layout XML file an element corresponding to the button we want to add in the interface.
2. Associate to this element the modeled action it will launch (as well as its associated graphical resources and parameters) via the SEND_CUSTOM_EVENT action

<action actionName="SEND_CUSTOM_EVENT(eventName= myEvent_FPActivation)”… />

1. A click on this new button will run all the actions triggered by the model custom event ‘myEvent_FPActivation’. The custom event corresponds to the FP activation in our example.

How to use Flyers?

All flyers (action, RMO, product, compare, form, external) are parameterized inside their parent page (Home, Configuration and/or Summary pages). However, they are called on demand, if triggered by some user actions.

1. Declare a flyer in the XML file (in Home, Configuration or Summary Page)
2. Position the action triggering the flyer:

The Flyers can be called by the use of a specific action called ‘OPEN_FLYER’. <action actionName="OPEN_FLYER(flyerName=myFlyer)"… >

This OpenFlyer action uses a parameter that is the name of the flyer that must be opened

1. The information displayed in the flyer depends on the type of flyer and its calling context:

Note:

The OPEN_FLYER of an informationFlyer is only available when the message persistence is activated (common.message.persistence=true in cameleon.properties). For more details, please refer to the Information Components chapter.

The action is de-activated (resourceOffName can be used)

As the OPEN_FLYER action can call all kind of flyers, the names of these flyers have to be unique in the XML file.

Tip:

By choosing the ‘auto’ value for the parameters vtPosition and/or hzPosition, the flyers are positioned automatically and relatively to the user mouse pointer.

The following translations are associated to the component:

<translation name="flyer.close"></translation>` allows to modify the label of the flyer close button

NEXT/PREVIOUS POLICIES

The <settings> section contains parameters specifying the default behavior of the interface.

NEXT & PREVIOUS POLICIES (CONF. ONLY)

The nextPolicy & previousPolicy describes the rules to define which element in the user interface will have the focus (meaning: ‘will become the current element’) once the Next (resp. Previous) action has been called.

Reference: The automatic scrolling mode that rules the focus put on Form Properties when answering them can be setup in the cameleon.properties file. See the CPQ Administration guide for more details on the scrollMode parameter.

The Next action is automatically called when the user clicks on the ‘Next’ button.

Moreover, it is also called each time a Form Property is valuated on condition that it complies with the automateNextPolicy rules. The purpose of automateNextPolicy is to set rules on focus automation, but it cannot disable it.

Tip:

By default, the layout file is configured so that, once the end user has answered a FP:

• If the FP is mandatory, the next policy is called if (and only if) the FP has been valuated without error

  <automateNextPolicy mustBeWithoutFailure="true" mustBeCompleted="true" mustBeMandatory="true" />

• If the FP is optional, the next policy is called if (and only if) the FP has been valuated without error or if no value has been chosen.

  <automateNextPolicy mustBeWithoutFailure="true" mustBeCompleted="false" mustBeOptional="true" />

The Previous action is called when the user clicks on the ‘Previous’ button.

When the Next/Previous action is called, the Configurator Engine returns which UI element has to become ‘Current’ and then have the focus.

STEP BY STEP NAVIGATION (CONF. ONLY)

CPQ allows to navigate from one form property to another one without taking into account the sequential access to the questions.

However, in some cases, it can be useful to guide the end-user by offering a step-by-step navigation. The goal of this navigation is to have a User Interface displaying a horizontal menu (see selectorBar chapter) whose tabs represent the navigation steps.

A tab of the main selector bar will become accessible if all the preceding steps have been successfully completed.

How to Activate the Step-by-Step Navigation

Declare the step by step policy in the settings part of the Layout XML file.

< stepByStepPolicy selectorBarName ="selectorBarMain”… />

The ‘selectorBarMain’ is the component that will define the different steps of navigation.

In addition to the Step-by-step policy, the usage of the dynamic NEXT_STEP and PREVIOUS_STEP

actions allows the end-user to be automatically redirected to the next (or previous) tab without clicking on the selector bar itself.

Declare the Previous/Next step actions in the Layout XML file:

<action actionName="PREVIOUS_STEP" alignment="center" resourceName="btnPreviousStepMNT" resourceOffName="btnPreviousStepMNTOff" translationName="tooltip.previousStep" url=""/>

Tip:

When the step-by-step navigation and Next_Step/Previous_Step actions are used, the following settings are recommended:

ACTIONS AUTOMATION (CONF. ONLY)

The automateActionPolicy allows triggering automatically a SAVE or ADD_TO_CART or ADD_TO_CART(goTo=cart) or ADD_TO_CART(multiConfiguration=on) action every XX seconds in case the issuer is idle.

The timer attribute is in Seconds.

A confirmation flyer can be raised each time the action has to be launched in order to let the user confirm is this action has to be completed.

Tip:

<automateActionPolicy timer="100" confirmationFlyer="on" actionName="ADD_TO_CART"

onConfirmationTranslationName="automateActionPolicy.onConfirmation"

The ‘Success’ or ‘Failure’ messages returned by the automated action can be parameterized in the translation section.

SELECTOR POLICY

The selectorPolicy gives some parameters shared by all value selectors (Configurator or Catalog).

COMPARISON POLICY

The comparisonPolicy gives the parameters of the comparison tools that are used during the sales script.

INDEXING POLICY

The indexingPolicy gives the RMO usertype which is used by CPQ UI to build the pages header and to fill the <meta> tags.

By default, the following header is inserted into the CPQ UI HTML pages:

<title>Cameleon-edge</title>

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>

<meta http-equiv="pragma" content="no-cache"/>

<meta http-equiv="cache-control" content="no-cache, must-revalidate"/>

If a userType has been specified in the indexingPolicy, the RMOText of the rootCP, or rootCollection corresponding to this userType is used and appended to existing <meta>.

Then it is possible to add RMOText to sub-collections or products and these meta will be used to build the corresponding collection or productPage.

Tip:

E.g. Content of the RMO Text attached to the rootCP:

`<title>`My Configurable Product Title `</title>`

<meta content="Lorem Ipsum…… " name="description"/>

<meta content="Web, Configuration" name="keywords"/>

Generated Meta in the resulting HTML confUI pages:

`<title>`My Configurable Product Title `</title>`

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>

<meta http-equiv="pragma" content="no-cache"/>

<meta http-equiv="cache-control" content="no-cache, must-revalidate"/>

SEARCH POLICY

The searchPolicy gives the way products descriptions and text will be searched in the Catalog

Reference: For more details, please refer to the Search Tools chapter.

LINKED PRODUCTS SEARCH POLICY

The linkedProductsSearchPolicy gives the way products will be searched in a complex product structure.

The search applies on the name, description and rmoText (having a userType specified in the rmoUserType attribute.

NAVIGATION POLICY

The navigationPolicy defines the way the path of items associated via product links are displayed in a navigationPathBox.

Example:

Example with a list of links:

<navigationPolicy linkType="spareParts,CustomLink1" />

Example for all types of links:

<navigationPolicy linkType="*" />

DRAG AND DROP POLICY

The dragAndDropPolicy allows (de)activating the capability, in the Catalog, at runtime, to drag a product from a product list and to drop it in the cart box, thus adding this item to the Quote.

Example:

<dragAndDropPolicy ddProducts="off"/>