You are viewing the documentation for Blueriq 17. Documentation for other versions is available in our documentation directory.
Introduction
The MVC UI has two default themes (Forms theme and Dashboard theme) and has support for custom made themes. A theme is basically a set of files and some configuration that consists of the following components:
| Description | Location | |
|---|---|---|
| Index file | StringTemplate index file | JAR or spring.config.additional-location |
| Web resources | JavaScript, CSS, images, etc. | JAR or spring.config.additional-location |
| Configuration | Properties in the aquima.properties file | spring.config.additional-location |
A theme can be part of a custom plugin JAR (for example the Dashboard plugin) but can also just be a collection of files located in spring.config.additional-location.
Getting started
The base of a theme is the index file from which the main page is build. 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:
| Property | Type | Description | |
|---|---|---|---|
| theme | String | Name of the theme currently selected | |
| apiBasePath | String | Base path for the web API | |
| webResourcesBasePath | String | Base path for web resources | |
| extensions | Object (ExtensionContext) | Contains all registered CSS and JavaScript files | |
| cssExtensionUrls | String[] | URLs to all registered CSS files | |
| jsExtensionUrls | String[] | URLs to all registered JavaScript files | |
| sessionId | String | Current session id | |
| currentPageJson | String | Current page in JSON format | |
| developmentMode | boolean | Indicates whether or not the application runs in development mode | |
| sessionTimeout | int | Configured session timeout in seconds | |
When creating a custom theme you need to provide a StringTemplate index file.
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.
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 funciton 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:
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":
Properties for registering a custom theme
mvc.themes=custom_dashboard mvc.custom_dashboard.templateGroupFile=UI/mvc/custom_dashboard.stg mvc.custom_dashboard.templateName=main
Overview
Content Tools