Lite Client Resources

The Lite Client is designed to be easily modified by applications using it and this is done with resource files in the appLiteClient folder under the application folder. There are some specific resource files defined below but the Lite Client will also load any JavaScript or CSS files that are included in the appLiteClient folder or any appLiteClient child folders.

Lite Client Templates

The template file is one of the Lite Client resources that allows an application to modify the Lite Client look and feel. The template file is a JSON file holding objects that have a collection of named string templates.

Template Parameters

The templates are in HTML format and include parameters that are used in various ways. The parameters are names wrapped by double curly brackets (e.g. {{NAME}}).

When the template is used (e.g. to display a button) then the parameter names are used to find a mapping property and are replaced by the mapping value.

Parameter names that are not defined in the mapping file (e.g. node IDs) are given values by the Lite Client source code. These source code parameters can be used in any templates but their value can not be changed by application resources.

...
/***************************************************************************
* Button
* PROIV Static and Dynamic button components.
*/
"Button":
'<button type="button" class="{{form-button}} {{proiv-class}}" id="{{componentID}}" title="{{tooltip}}"\
disabled="{{disabled}}" onclick="onclick" isFieldNode="true" isPagingRootNode="true"\
focusClass="form-button-focus">\
<img class="{{form-button-image}} {{node-hide}}" id="{{componentImageID}}" isImageNode="true" />\
<span class="{{form-button-icon}} {{node-hide}}" id="{{componentFontIconID}}" isIconNode="true"></span>\
<span class="{{form-button-text}} {{node-hide}}" id="{{componentTextID}}" isTextNode="true">{{value}}</span>\
</button>',
...

This example shows the default template for a Button component.

Overriding the Templates

When an application wants to override one or more templates it provides a template file (which must have an extension of js) in the application appLiteClient folder that is loaded after the default one. This JSON file contains objects that replace the default templates and can also contain new templates. The default templates can be found in the ..\ClientServices\work\base-default\webapp\lite-client\resources\PROIVDefault-templates.js file of the PROIV installation.

Note that the default template file has a slightly different object structure to the application template file (compare the Button templates above and below) but the template strings are created in the same way. You do not need to include any unchanged templates in the application template file.

...
/***************************************************************************
* Button
* PROIV Static and Dynamic button components.
*/
proiv.ComponentTemplates["Button"] =
'<button type="button" class="{{form-button}} {{proiv-class}}" id="{{componentID}}" title="{{tooltip}}"\
disabled="{{disabled}}" onclick="onclick" isFieldNode="true" isPagingRootNode="true"\
focusClass="form-button-focus">\
<span class="{{form-button-icon}} {{node-hide}}" id="{{componentFontIconID}}" isIconNode="true"></span>\
<span class="{{form-button-text}} {{node-hide}}" id="{{componentTextID}}" isTextNode="true">{{value}}</span>\
</button>';
...

This example shows the button template being simplified by removing the image node.

Adding New Templates

All the PROIV components have a property called 'Template Name'. If this is defined then the value is used to look for a template with that name. If not found then the default template for the component is used. This allows the application to display components in a different way.

...
/***************************************************************************
* Object heading
* PROIV Icon components.
*/
proiv.ComponentTemplates["heading"] =
'<h2 class="{{form-object-heading}} {{proiv-class}}" id="{{componentID}}" \
isFieldNode="true">{{value}}</h2>';
...

This example shows a template called 'heading'. This can be used in a PROIV Icon component by setting the template name to 'heading'. This will display the Icon text as a H2 heading on the screen. The CSS class 'form-object-heading' will be defined as a property in the application mapping file.

Lite Client Mapping

The mapping file is one of the Lite Client resources that allows an application to modify the Lite Client look and feel. The mapping file is a JSON file holding an object that has a collection of named string properties. The Lite Client templates use parameters that can be defined in the mapping file.

The most common use for mapped parameters is the CSS classes for the DOM nodes built by the Lite Client. Another use is for font icon names allowing for different font icon libraries to be used. Default window titles also use mapped parameters.

The Default Mapping File

The default mapping can be found in the ..\ClientServices\work\base-default\webapp\lite-client\resources\PROIVDefault-mapping.js file of the PROIV installation. This file holds all the mapped parameters used by the Lite Client.

...
proiv.DOMPropertyMap = {
"root-window": "container-fluid proiv-root",
"root-panel-1": "proiv-root__panel--first",
"root-panel-2": "proiv-root__panel--second",
"popup-window": "proiv-popup",
"popup-border": "proiv-popup__border",
...

This example shows some CSS classes.

Overriding the Mapping

When an application wants to override the mapping it provides a mapping file (which must have an extension of js) in the application appLiteClient folder that is loaded after the default one. This file has a JSON object called proiv.AppPropertyMap and can have any number of named properties with their values. If a property has the same name as one in the default mapping object then it will overwrite that property with the new value.

...
proiv.AppPropertyMap = {
"root-window": "container-fluid pl-1 pr-1",
// font icons.
"icon-europe": "fa-globe-europe",
"icon-win-nodata": "far fa-circle",
"icon-win-data": "fa-circle",
"icon-win-view": "fa-ellipsis-h",
// images mapped to icons.
"mldata": "icon-europe",
// Default window titles.
"FileRead-Title": "",
"MessageBox-Title": "",
"Popup-Title": "",
"Prompt-Title": "",
"Query-Title": "",
...

This example shows a number of mapping changes:

It has replaced the CSS classes of the root window.
It has added some font icon names that can be used in the application (see below).
It has added a font-icon that can be used in place of an image.
It has removed all the window titles.

Where Parameter Mapping is Used

The Lite Client uses parameter mapping in the following situations:

DOM Node Class Names: The templates define mapping names to use for all the DOM node CSS class names.
PROIV Image Names: Whenever a PROIV image is defined (e.g. on a button) the name is checked for a mapping and if found then is assumed to be a font icon. Note that Lite Client includes the public Font Awsome icons and the names for these font icons can be found at https://fontawesome.com/icons .
Window Titles: The title of all the PROIV windows are obtained from the mapping parameters.

Lite Client CSS

An application can provide a CSS file (which must have an extension of css) in the application appLiteClient folder and that will be loaded when the session starts. This CSS file should contain any CSS classes that have been defined in the templates or defined by mapping parameters. This could be classes specified by the default templates and mapping, in which case the CSS will override the default, or it could be new classes defined by the application.

Some of the PROIV Developer objects (components) behave differently in the Lite Client as they need to look more like standard browser components.

Section Links:

The Templates explains the Lite Client templates.

The Component Grouping defines the Lite Client component grouping.

The Browser Validation defines the Lite Client browser validation.

Comment on this topic

Topic ID: 870039