Angular frontend customization

Important

The customization steps described here are not fully up-to-date with the docker deployment.

To create a future-proof customization, also check notes in Example: add custom CSS and Google Analytics.

The frontend created using Angular framework is located at these paths:

  • /var/webapps/fleio/frontend/staff - staff panel
  • /var/webapps/fleio/frontend/reseller - reseller panel
  • /var/webapps/fleio/frontend/enduser - enduser panel

This documentation includes:

Adding new themes

Important

If you are adding or changing Fleio files, other than Fleio setting files that are stored in docker volumes, see Adding or changing files in Fleio docker images.

First, we’ll use a local environment to write the .scss custom theme and generate our .css file that we’ll deploy on production. Use the following procedure (adapt to your operating system if needed). We’ll use demo as the name for our custom theme.

apt update
apt install npm
npm install -g @angular/cli
ng new demo --style=scss  # answer no to questions
cd demo
ng add @angular/material  # choose CUSTOM, answer no to the next questions

Now, edit the demo/src/styles.scss file. Remove its contents if any.

This is how our demo theme may look.

@import '~@angular/material/theming';
$demo-primary: mat-palette($mat-amber, 500);
$demo-accent: mat-palette($mat-brown, 600);
$demo-warn: mat-palette($mat-red, 500);
$demo-theme: mat-light-theme($demo-primary, $demo-accent, $demo-warn);
.app-theme-demo {
  @include angular-material-theme($demo-theme);
  $demo-primary-color: #ffc107;
  .topbar-items-container > div,
  .mat-toolbar, .mat-toolbar .mat-icon,
  .mat-raised-button[ng-reflect-color="primary"] > span, .mat-fab mat-icon {
    color: #fff;
  }
  .sidenav-container, .sub-header {
    background: #f1f1f1;
  }
  .fl-card-fixed,
  .fl-card-fixed-md,
  .fl-card-fixed-sm {
    @include mat-elevation(2);
  }
  mat-icon {
    color: grey;
  }
  button[disabled] .mat-icon {
    color: lightgrey;
  }
  .mat-button-base {
    text-transform: uppercase;
  }
  .active-link, .active-link mat-icon {
    color: $demo-primary-color !important;
  }
  .object-card-content {
    margin-left: 15px;
    font-size: 14px;
    line-height: 20px;
    word-break: break-all;
    color: #616161;
  }
  .fl-tag {
    background-color: #878787;
    color: white;
    padding: 2px 8px 2px 8px;
    border-radius: 2px;
  }
  .mat-form-field-appearance-legacy .mat-form-field-underline {
    background-color: rgba(0, 0, 0, 0.12);
  }
}

It is enough to overwrite $demo-primary, $demo-accent, $demo-warn and $demo-primary-color variables in order to just change the primary/secondary colors. However, you can dig further and edit the styling, positioning, etc. of any element of the app.

You can see that for primary, accent and warn palettes we use already defined color palettes provided by Angular Material (e.g. $mat-amber, $mat-brown, $mat-red). You can find additional already defined palettes like those in node_modules/@angular/material/_theming.scss (just search for those we’ve already used in our demo) and you can make use of them just like we did above. If you wish to define your own palette you can take some inspiration from those that are already defined, add them in the styles.scss file and make use of them.

For additional information, you can read: Angular Material theming guide, Sass/scss basics.

Once all changes were done we need to generate the .css file:

ng build --prod --extract-css

Now copy the demo/dist/demo/styles.xxxxxxx.css file, rename it to demo.css (use your theme name instead of default name, very important) and copy it on your fleio installation in /var/webapps/fleio/frontend/staff/assets/themes or /var/webapps/fleio/frontend/reseller/assets/themes directory.

Once copied, you will need to add your theme in the available themes in panel’s config file. Edit /var/webapps/fleio/frontend/PANEL_NAME/assets/config/PANEL_NAME.config.json settings > availableThemes property to look like this (or add it, if missing):

...
"settings": {
    ...
    "availableThemes": ["demo"],
    ...

Notice we removed “spring” from the availableThemes default array. In this case, we’ll need to also change the app default theme using the defaultTheme property:

...
"settings": {
    ...
    "defaultTheme": "demo",
    ...

Now users will have another default theme and they can change it from their user’s profile page, if any other themes are available.

Adding new themes in docker install

First, you need to generate the theme .css file as in the above docs.

Then, there is a new setting that can be used in angular config files called dynamicallyLoadCustomThemes. Using this setting you will be able to disable dynamic loading of custom themes and have a smoother experience on slower internet connections by customizing the Docker frontend image to include the .css in the panel index.html. So, to disable this, enter the following command:

fleio edit staff.config.json

Do so for all panels you need (enduser, staff, reseller).

In the config file, add or update the setting with the value set to false.

...
"settings": {
    ...
    "dynamicallyLoadCustomThemes": false,
    ...

After you generate the .css file as described in the above section, you’ll need to change the index.html file for each panel you want and to and include the customized .css file. To do so, read the following guide: Adding or changing files in Fleio docker images.

Here are a few notes:

The css theme file should be copied like this (do so for every panel):

COPY theme_name.css "$INSTALL_PATH/frontend/staff/assets/themes/theme_name.css"

Also, the sed command from the Dockerfile should look like this (do so for every panel):

RUN sed -i \
's^</head>^<link rel="stylesheet" type="text/css" \
href="assets/themes/theme_name.css" \ media="screen"/></head>^' \
"$INSTALL_PATH/frontend/staff/index.html"

Remember to update the availableThemes setting from angular configs as described in the previous section but this time by using the following command (do so for every panel):

fleio edit staff.config.json

Adding custom javascript

If you wish to add custom javascript to the angular app you can access and edit the following files (create them if they happen to not exist):

  • /var/webapps/fleio/frontend/staff/assets/js/custom.js - for staff
  • /var/webapps/fleio/frontend/reseller/assets/js/custom.js - for reseller

Example of custom.js file:

    (function () {
// window.setHeaders = function (request, getCookie) {
//   return {
//     CustomHeader: getCookie('customCookieName'),
//   }
// }
    })();

Notice the usage of IIFE

Customizing request headers

After reading the above documentation about the custom.js file, besides custom javascript code you want to write, we’ve introduced a method for allowing you to override/add headers when making requests. As you can see in the template, overriding the window.setHeaders function’s return value will allow you to define those headers as a dictionary. You can make use of the request param to add conditions based on request method for example. Return null if you want no headers to be added/overridden. You can make use of the getCookie param that references a method used for getting a cookie by name (exemplified in the commented code of the template).