Introduction

Cyclos is completely white label, and has various customization options. Most of the layout customization can be done from within the content management section in Cyclos (admin menu: Content management).
There are various levels of customization. The easiest approach is to use Cyclos 'Themes'. If more structural layout changes are needed the (open source) front-end can be entirely customized, and the mobile app also has various additional customization options, all explained further below.

Cyclos does support the Thymeleaf template engine. It falls under the category 'Content management' rather than 'Layout', but Thymeleaf can be very helpful to display dynamically content (based on variables). Thymeleaf can be used with any content page (custom and static web/mobile pages, banners, headers/footers, custom operations, wizard pages). Information about Thymeleaf can be found in the Cyclos reference guide

Themes

Themes in Cyclos consists basically of custom style sheets (CCS) and images. A theme can be to all access channels (classic web front-end, open source front-end, mobile phone). The advantage of using themes is that all customization can be managed directly in Cyclos.
Themes can be found logging in as admin and going to: Content - Content management - Themes. A theme defines the layout (e.g. colors, menu bar size, font style) and built-in system images. There are three types of themes; Classic Web theme, New front-end and Mobile (app). When saving a theme it will be directly applied. Any network in the system has a theme applied. This can be a theme inherited from a higher level, or a theme managed directly at network level. Cyclos comes with various 'built-in' themes and it is possible to create new themes as well.

There are three levels of customizing a theme. The first (easiest) level is done with a color picker. This allows to create a new theme in a few minutes. The second level is done by changing common theme elements by predefined Sass variables. Normally variables are used to group layout items that logically share the same value (e.g. all window borders). The third customization allows to customize the entire CSS file. When creating a new theme you have to option to create an empty one, or extend an existing theme. It is also possible to import and export a theme.

CSS customization

In order to customize CSS you need to enter a theme. You only can customize themes for which you have write permissions (the themes to which you don't have write access will show up in italic and grey color in the theme list). At the bottom of the page there is a select box 'custom style´. Selecting this will show a link called 'show the original style' and a input text box. If you click on the link you can see the entire CSS. You can copy & past this to work on it. Any CSS you put in the box will be added to the CSS, meaning it will overwrite existing CSS tags. In order to apply you have to click on save. Make sure your refresh the browser window.

Font customization

To change the font to some font in Google Font directory, you will have to do the following:

Go to https://fonts.google.com/ and choose the desired font, clicking the plus icon next to its name. A black box at the bottom will appear.
Click that black box. Click EMBED, then @IMPORT. Take note of both the @import line and the code in "Specify in CSS" section.
Edit the theme in Cyclos. Check "Use custom style" and paste the following, replacing the entire @import line and the font family name (as in the "Specify in CSS" section).

Here is an example for the Roboto font:

@import url('https://fonts.googleapis.com/css?family=Roboto');

body, td, th, input, textarea, select, button, .gm-field, .statusMenuCountBadge, .leftMenu, body.help {
    font-family: 'Roboto', sans-serif;
}

After saving the theme and refreshing the browser window the new fonts should be applied.

Theme images

A theme has built-in images, that can be changed. It is also possible to upload custom images, that can be included.

Open source front-end

Cyclos comes with a classic front-end and a new front-end based on open source frameworks (J angular and Bootstrap). The new front-end has been published as an open source project, and can therefore completely customized. The front-end uses the REST API, which is very well documented (see example here).

Technical information and the road map can be found at the Cyclos front-end page at GitHub.
All functions will work exactly the same as in the classical front-end. System administrators will typically use the classical front-end as not all administration features are available in the new front-end. In case if an admin configures his own layout (configuration) to use the new front-end he will be able to login and switch back to the classical interface by going to the Personal menu - Settings - User classic front-end.

A demo of the new front-end can be seen at:
demo.cyclos.org
(You can login with user: demo, password: 1234, or create a new user yourself clicking on the 'register' link at the top right)

Configuration & Customization

There are two ways to customize the front-end. The easiest and most straightforward way is to enable the built-in in front-end in the configuration. This can be done per configuration in the section 'new front-end'. The section has various settings (explain). All content can be configured logging in as an admin and going to the 'Content' menu:

Front-end pages
Application translation (New front-end > Translations)
Banners > New front end banner
Static content > New front-end
Themes > New front-end theme

The new front-end uses icons for entities. For dynamic entities (that can be created by admins) it is possible to assign a new icon. This is available for the entities: Record type, Advertisement category, Wizard and Custom operation.

Customization outside Cyclos

The other way to customize the front-end is to get the code from GitHub (see URL above) and do the customization separately. This is only useful if you want to make changes that go beyond layout (CSS) and content (menus, pages) changes. When the customization is done the front-end can be included in Cyclos. A tool is available (included with the Cyclos .zip file) to migrate the external front-end into the Cyclos built.
The tool can also be used by projects that have have developed a customized version form the code on GitHub (before it was available as a built-in module in Cyclos). This tool can also be used for project where the new front-end is customized from the GitHub repository.

Mobile customization

There are various levels of customization of the mobile app. The most straightforward is the customization of the layout. There is a dedicated theme for the mobile app (admin menu: Content - Content Management - Themes > Mobile app). For some changes (launch icon, fixed URL) access to the mobile app code is needed. The download package of the mobile app from the license server contains documentation how to do this.

Form the content management section in Cyclos it is possible to customize built-in mobile app pages such as login page, home page, welcome page and the help page. It is also possible to add new mobile pages. Customizing pages is described in the Content management of the reference guide. The mobile app customization allows changing completely the look & feel of the mobile app. The thymeleaf template engine allows displaying data depending on variables such as the logged user product, profile field values etc. It is also possible to add custom features by using custom mobile operations.

Here below an example of the built-in mobile home page (left), and a custom mobile home page (with menu).

Default home page
Custom home page
Custom home page (menu)

We made we made the above custom mobile home page the default example so it is easy to enable. You can activate it by logging in as admin and going to: Content - Static content (choose configuration here if you have multiple) - Mobile home page. Now select 'customize' and make sure to check the enable option. Clicking on the < > button will give you a preview.

You can also link to certain pages in Cyclos. Here are some examples:

Customers who have signed our NDA can download the customizable mobile app through license.cyclos.org, this bundle contains more examples.

Advanced customization

The above section explains how new pages and custom operations for the mobile app can be created and managed directly within Cyclos. The advantage of this approach is that it does not require redeploying the Cyclos mobile app, since all configurations are stored and executed on the Cyclos server side.

However, in some cases it may be required to extend or modify a page on the client side, for example, when specific interactive behavior or validation rules are needed directly within the page. This can be achieved by including a JavaScript file in the mobile app. The JavaScript file has access to the page data and can manipulate or extend it, for example, by dynamically displaying additional information on the page based on user input. It is also possible to connect to an external API or to the Cyclos API directly from the JavaScript file.
This functionality is available starting from Cyclos mobile app version 2.15.2 and works for any mobile page, including both custom operations and built-in Cyclos operations. It will require a deployment of the Mobile app (at the Android and Apple stores).

An example can be found in the Mobile Reference Guide (section 6.2). The example demonstrates how to extend a custom operation that does a conversion payment. In the example, the app dynamically displays, directly below the payment field, the converted amount that the customer will receive. (see screenshots below).
The conversion calculation can be performed by: a Cyclos script (via a Cyclos web service), an external API, or a combination of both.

Error creating thumbnail: File missing

Home page
Error creating thumbnail: File missing

Custom operation

Ticket confirmation page

The ticket confirmation page ([cyclos-root]/pay) is an application written using Angular Material 2. It uses a style sheet for the Material theme, plus customizations for the application itself. In Cyclos, on the Themes page it is possible to create a new theme for the ticket confirmation page, and it will have 2 main sections, each reflecting one of these styles. The custom style can be set in the last field, and will be appended to the final style.
Note!: The ticket confirmation page will be completely redesigned together with the default frontend in Cyclos 5.

However, the hardest part in the customization is generating a theme for Angular Material 2. It uses SASS to generate the themes based on a set of color palettes. Basically, the material theme uses 4 color definitions:

The primary color palette;
The accent color palette;
The warning color palette;
The background (either light or dark).

The Material design specification defines a set of color palettes that can be used. One of these should be used for the primary, accent and warning palettes.

Generating a theme for Angular Material 2 requires a set of commands. In order to run them, Node.js version 6 or later needs to be installed. Then, Angular CLI needs to be installed globally. For this, run the following command with administrative rights (ie, sudo on Linux):

npm install -g @angular/cli

Afterwards, the following series of commands need to be executed in as a regular user:

ng new --skip-install --skip-git --skip-tests --style scss material-theme
cd material-theme
npm install --save @angular/material
npm install --save node-sass

As result, the material-theme folder is created. Then, open the file src/styles.scss in a text editor, and customize the following content:

// Import the basic material theme
@import 'node_modules/@angular/material/theming';

// Include the common styles for Angular Material. We include this here so that you only
// have to load a single css file for Angular Material in your app.
// Be sure that you only ever include this mixin once!
@include mat-core();

// Define the palettes. See https://www.google.com/design/spec/style/color.html.
// The built-in palletes are: $mat-red, $mat-pink, $mat-purple, $mat-deep-purple,
// $mat-indigo, $mat-blue, $mat-light-blue, $mat-cyan, $mat-teal, $mat-green,
// $mat-light-green, $mat-lime, $mat-yellow, $mat-amber, $mat-orange,
// $mat-deep-orange, $mat-brown, $mat-grey and $mat-blue-grey.
$app-primary: mat-palette($mat-blue);
$app-accent:  mat-palette($mat-light-blue, A200, A100, A400);

// The warn palette is optional (defaults to red).
$app-warn:    mat-palette($mat-red);

// Create the theme object (a Sass map containing all of the palettes).
$app-theme: mat-light-theme($app-primary, $app-accent, $app-warn);

// Include theme styles for core and each component used in your app.
// Alternatively, you can import and @include the theme mixins for each component
// that you are using.
@include angular-material-theme($app-theme);

The palette choices are present in the following SASS variables: $mat-red, $mat-pink, $mat-purple, $mat-deep-purple, $mat-indigo, $mat-blue, $mat-light-blue, $mat-cyan, $mat-teal, $mat-green, $mat-light-green, $mat-lime, $mat-yellow, $mat-amber, $mat-orange, $mat-deep-orange, $mat-brown, $mat-grey and $mat-blue-grey.

It is also possible to generate a dark theme by replacing mat-light-theme with mat-dark-theme.

Finally, generate the CSS with the following command:

node_modules/.bin/node-sass src/styles.scss dist/styles.css --output-style compressed

The file dist/styles.css will be generated. It is the content of this file that should be copied and pasted in the 'Material theme' section in the Cyclos theme.

For more information on Angular Material 2 theming, please, refer to the theming guide.

Layout customization

Contents