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.

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 section gathers the standard messages required by the application to ensure its correct behavior
• The 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>

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>

The messages listed in messageResources.properties that can be overridden are those prefixed by one of the following:

• Catalogui.system
• Configuratorui.system
• Cameleonui.system.

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

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.

An Icon associated to a component contained in a page is identified by

its name (xxxResourceName="ID_OfTheIcon"). This name links the element to the localized path of the graphical resource which is declared in the <resources> section:

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

The attribute cssName="ID_OfTheCSS" allows:

• to associate to the component a CSS Class in order to control its display. The name given in the XML Layout file (ID_OfTheCSS) is used by the UI engine during the rendering. The main <div> of the component is associated to this main CSS class.
• to identify in which CSS file this class is described.

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

CSS resources have to be located in the following directory:

$cpq_home_folder$/...

/cameleon.ear/cameleonUI.war/theme/My_THEME_Name/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.

.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]
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 */

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"

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

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*