Customizing Apliqo UX

Hi,

The document was created by Stuart a while back so I thought this could be useful for many.

Visual Studio code
This is the IDE that we all use for development and is a very powerful tool.

If you haven’t already, download and install the latest version of Visual Studio Code

Node
This is required for running gulp when we wish to make customizations to the code. Download and install the latest version. (For any version below 2.5, the latest version of node that we can run is version 10.

Install Node Packages
This is most easily done through a terminal when running the Visual Studio Code.
It needs to be run from the webapps\UX_Custom folder that you wish to customize.

Gulp
Install gulp globally. This is most easily done through a terminal when running the Visual Studio Code.

  • npm uninstall gulp-g (If you have previously installed gulp, please run this)
  • npm install gulp-cli -g (This will globally install gulp-cli which you need to run gulp).


This enables the automatic compilation of SASS and custom JS files.
Gulp is only required if you are modifying SASS files or in need of supporting ie11… if you wish to add some entries into a CSS file, then this will work as well… you will just be a bit more limited in what you can achieve.
Once this is done you can run gulp from the terminal window: Leave this running in the terminal and any changes you make will be automatically compiled into the required files that the browser will pick up on a full refresh.

Apq-c3-custom
This is where you will need to put all your customizations so they can be carried forward into future versions of Apliqo UX.

Customizing an app

Change the title of the app
Apq-c3-custom/js/default.constant.js

‘APPLICATION_NAME’: ‘The Gnar’,
Picture4

Change the webpage title
WEB-INF/config/settings.json

“applicationName”: “The Gnar”,

Picture5
Change the application logo
Apq-c3-custom/js/default.constant.js

‘APPLICATION_LOGO’: ‘river2.png’,
Picture4

Change the login logo
Apq-c3-custom/js/default.constant.js

‘LOGIN_LOGO’: ‘river2.png’,

Change the background image of login page
Apq-c3-custom/css/scss/_custom-style.scss

@media (min-width: 400px ) {
    .modal-fullpage {
        background: #030303 url(../../apq-c3-custom/images/fallsskier.jpg);
        background-position: center;
        background-size: cover;
    }
}

Stylesheet customization
In ApliqoUX we use SASS https://sass-lang.com/
Sass is completely compatible with CSS, so you can happily write CSS as you know it in a Sass (scss) file. If however, you are not syntactically correct then the gulp process will show an error message upon saving.
Sass offers some very nice features over basic CSS, so it’s worth spending a little time to understand what makes it so good.
Here is a link to the Sass basics which will give you a good starting point https://sass-lang.com/guide

The 2 main things you will need to use are

Configuring custom colours for the look and feel of Apliqo
Apq-c3-custom/css/scss/_custom-variables.scss

// Colours
// --------- Close to default ----------
// $brand-primary: #39A5DC !default; // Close to default
// $brand-secondary: #030303 !default; // Close to default
// --------- Purple and orange mix ----------
$brand-primary: #FF9901 !default;
$brand-secondary: #232F3D !default;
// --------- Scarlet and orange mix -----------
// $brand-primary: #FF9901 !default;
// $brand-secondary: hsl(0, 100%, 25%) !default;

// Title name colours
$apq-c3-name: white !default;
$apq-c3-name-hover: scale-color($brand-primary, $lightness: 90%) !default;

// Masthead background colours.
$navbar-pf-bg-color: $brand-secondary !default;
$navbar-pf-bg-color-start: lighten($navbar-pf-bg-color, 2%) !default;
$navbar-pf-bg-color-stop: darken($navbar-pf-bg-color, 2%) !default;

// Colour of the top border in the page
$navbar-pf-border-color: $brand-primary !default;

// Start and stop colour of appbar
$navbar-pf-navbar-primary-bg-color-start: lighten($navbar-pf-bg-color, 10%) !default;
$navbar-pf-navbar-primary-bg-color-stop: $navbar-pf-bg-color !default;

// Appbar border colour
$navbar-pf-navbar-border-color: lighten($navbar-pf-bg-color, 1%) !default;
$navbar-pf-navbar-header-border-color: lighten($navbar-pf-bg-color, 1%) !default;

// Hover colour of utitity menu at top right of page
$navbar-pf-navbar-utility-hover-bg-color: darken($navbar-pf-bg-color, 10.5%) !default;

// Start and stop colour of appbar hovered item
$navbar-pf-navbar-primary-hover-bg-color-start: lighten($navbar-pf-bg-color, 8%) !default;
$navbar-pf-navbar-primary-hover-bg-color-stop: lighten($navbar-pf-bg-color, 2%) !default;

// Colour of border on top of widget cards
$card-pf-accented-border-top-color: $navbar-pf-border-color !default;

// Dropdown menu colours of active and hovered items.
$dropdown-menu-active-border-color: lighten($navbar-pf-border-color, 20%) !default;
$dropdown-menu-active-background-color: lighten($navbar-pf-border-color, 35%) !default;
$dropdown-link-hover-bg: $dropdown-menu-active-background-color !default;
$dropdown-link-hover-border-color: $dropdown-menu-active-background-color !default;
$dropdown-link-active-bg: $navbar-pf-border-color !default;
$dropdown-link-active-border-color: $dropdown-link-active-bg !default;

The result of these Sass variable customizations

Adding custom CSS
Apq-c3-custom/css/scss/custom-style.css
If you wish to add custom CSS you can also just add it to the custom-style.css file. You do not need to run gulp to compile this file as it is already CSS.

If you are already adding content to the _custom-style.scss file and running gulp, then I recommend that you keep your changes in the one file.

How to find variables or CSS that needs to be modified

For example, if you wish to change the color of the active item in the menu but you don’t know what the sass variable name is you need to inspect the item in chrome.


Then under the styles tab, you will see information similar to the following:
Picture10
Click on the _adm-view.scss:1223 to look at the Sass file

From this, you can see that the variables that you are interested in are:

  • $dropdown-link-active-bg
  • $dropdown-link-active-border-color

You just need to redefine what these are equal to in the _custom-variables.scss fie.

What if there is no Sass variable is defined?

Within our codebase, there has been an attempt to define all colors to Sass variables. Unfortunately, this will not always be the case.
If this is the case then you will need to create some CSS that redefines the color.

You can copy the CSS and change the required setting and save it into the _custom-style.scss file.
Please only copy that which you wish to change, otherwise, this may have an undesirable effect in the future.

If you are needing to do this then, please raise an issue with the Apliqo team so that the code can be improved for future customizations.

7 Likes