You are viewing the documentation for Blueriq 17. Documentation for other versions is available in our documentation directory.

Deprecated

MVC UI is deprecated from Blueriq 11.0. The alternative for the MVC UI support is to only use the UI REST API  endpoints.


A custom MVC UI theme can be created if the use of default Blueriq themes is not desired.

Introduction

The MVC UI has two default themes (bootstrap3 and bootcards) and has support for custom made themes. A theme is basically a set of files and some configuration that consists of the following components:


DescriptionLocation
Index fileStringTemplate index file

JAR or

spring.config.additional-location

Web resourcesJavaScript, CSS, images, etc.

JAR or

spring.config.additional-location

Configuration

Properties in the application.properties file

spring.config.additional-location

Getting started

The base of a theme is the index file from which the main page is built. Blueriq uses a template engine called StringTemplate to make server properties available in the client.

A default Blueriq index page is injected with a template context that features the following properties:

Variable TypeDescription
context.sessionId
string
Blueriq Session ID of the current Blueriq session
context.theme
string
Current theme of the Blueriq session
context.webResourcesBasePath
string

Location from root where web-resources are located

context.apiBasePath
string

Relative path of API endpoints, always "../api/"

context.currentPage
{ [elementKey: string]: Element }
Full pageModel, see REST Page Models
context.developmentMode
boolean
Indicates if developmentMode is active or not
context.sessionTimeout
integer
Session timeout in seconds

Creating the index file

The index file is the starting point of a custom theme and is a StringTemplate template that follows a certain structure. For full details on the StringTemplate syntax and usage please check the official documentation. The purpose of the initial page is to load all the required resources (e.g. JavaScript or CSS files) and to provide a base layout.

A StringTemplate index file in Blueriq has the following structure:

Basic index file structure
delimiters "$", "$"
main(context) ::= <<

[HTML]

>>

First the delimiters to use around StringTemplate variables are set to "$" instead of the default "<" ">" delimiters to be able to use variables within HTML. StringTemplate uses a function call to generate the template: main(context). The context object that is passed with this function call contains all properties as described above. In the function body (between "<<" and ">>") the actual index page is placed, which is a full HTML page.

In this example "main" is used as template function name, but this can be customized. See the Configuration section below for more information.

Save the custom index file as a .stg file so it is recognized by StringTemplate.

Installation

Installing your custom theme is easily done by putting all files in the 

spring.config.additional-location
 folder. For example when a theme is created named "custom_dashboard" which consists of an index file, a JavaScript file and a CSS stylesheet, installation would be as follows:

Java

  1. Create a UI/mvc folder in 
    spring.config.additional-location
     and put the custom index file (for example custom_dashboard.stg) here.
  2. Create a webresources/mvc folder in 
    spring.config.additional-location
     and put the JavaScript and CSS files here (optionally in /js and /css sub folders).
  3. Add a configuration section for your custom theme to application.properties in 
    spring.config.additional-location
     root, as described in the Configuration section below.

Configuration

In order to configure your theme so it will be known by the Runtime several properties must be set. The following example shows properties for registering a theme named "custom_dashboard" in both Java and .NET:

Java

Properties for registering a custom theme in Java
blueriq.mvc.themes=custom_dashboard
blueriq.mvc.custom_dashboard.templateGroupFile=UI/mvc/custom_dashboard.stg
blueriq.mvc.custom_dashboard.templateName=main

Working with multiple themes is possible by adding comma separated theme names to the mvc.themes property.


The mvc.themes or name property specifies the name for the theme which will be displayed in the Runtime theme selector. The other two properties specify which StringTemplate index file should be used and which StringTemplate function should be called to render the index page (see "Creating the index file" above). The path to the index file is relative to either the JAR/DLL or the 

spring.config.additional-location
/Configuration folder. When a file name is specified which is located in 
spring.config.additional-location
/Configuration and that is already loaded from a JAR, the file from 
spring.config.additional-location
/Configuration will be used and the file from the JAR/DLL will be overridden.

1 Comment

  1. The properties for registering a custom theme in Java doesn’t seem to work (the camelcasing doesn't seem right).

    But we do get the properties to work if we change it to:

    blueriq.mvc.themes=custom_dashboard
    blueriq.mvc.custom_dashboard.template-group-file=UI/mvc/custom_dashboard.stg
    blueriq.mvc.custom_dashboard.template-name=main