============================== Angular frontend customization ============================== .. index:: 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 :ref:`docker-custom-frontend`. 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: * :ref:`add-new-themes` * :ref:`add-new-themes-docker` * :ref:`change-logo-docker` * :ref:`custom-js` * :ref:`customizing-headers` .. _add-new-themes: Adding new themes ================= .. important:: If you are adding or changing Fleio files, other than Fleio setting files that are stored in docker volumes, see :ref:`change-docker-files`. 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. .. code-block:: bash 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 template may look: * :ref:`2022.03-or-newer` * :ref:`2022.02-or-newer` * :ref:`2021-06-or-newer` * :ref:`2021-05-1-or-older` .. _2022.03-or-newer: Template for 2022.03 or newer ----------------------------- .. important:: Adapt this template if you're using Fleio 2022.03 or newer. Themes generated using this template will not work with 2022.02.1 or older. .. code-block:: none @use '@angular/material' as mat; $mat-demo-blue: ( 50: #e8eaf6, 100: #c5cae9, 200: #6294b8, 300: #386d92, 400: #144463, 500: #083652, 700: #083652, contrast: ( 50: rgba(black, 0.87), 100: rgba(black, 0.87), 200: rgba(black, 0.87), 300: rgba(black, 0.87), 400: white, 500: white, 600: white, 700: white, 800: white, 900: white, A100: rgba(black, 0.87), A200: rgba(black, 0.87), A400: white, A700: white, ) ); $mat-demo-red: ( 50: #ffebee, 100: #ffcdd2, 200: #ef9a9a, 300: #e57373, 500: #ff3919, 700: #ff3919, contrast: ( 50: rgba(black, 0.87), 100: rgba(black, 0.87), 200: rgba(black, 0.87), 300: rgba(black, 0.87), 400: white, 500: white, 600: white, 700: white, 800: white, 900: white, A100: rgba(black, 0.87), A200: rgba(black, 0.87), A400: white, A700: white, ) ); $demo-primary: mat.define-palette($mat-demo-blue, 500); $demo-accent: mat.define-palette($mat-demo-red, 500); $demo-warn: mat.define-palette(mat.$red-palette, 500); $demo-theme: mat.define-light-theme($demo-primary, $demo-accent, $demo-warn); .app-theme-demo { @include mat.all-component-themes($demo-theme); $demo-primary-color: #476190; .topbar-items-container > div, .mat-toolbar, .mat-toolbar .mat-icon, .mat-raised-button.mat-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); } } .. _2022.02-or-newer: Template for 2022.02 or newer ----------------------------- .. important:: Adapt this template if you're using Fleio 2022.02 or newer. Themes generated using this template will not work with 2021.06 or older. .. code-block:: none @use '@angular/material' as mat; $mat-demo-blue: ( 50: #e8eaf6, 100: #c5cae9, 200: #6294b8, 300: #386d92, 400: #144463, 500: #083652, contrast: ( 50: rgba(black, 0.87), 100: rgba(black, 0.87), 200: rgba(black, 0.87), 300: rgba(black, 0.87), 400: white, 500: white, 600: white, 700: white, 800: white, 900: white, A100: rgba(black, 0.87), A200: rgba(black, 0.87), A400: white, A700: white, ) ); $mat-demo-red: ( 50: #ffebee, 100: #ffcdd2, 200: #ef9a9a, 300: #e57373, 500: #ff3919, contrast: ( 50: rgba(black, 0.87), 100: rgba(black, 0.87), 200: rgba(black, 0.87), 300: rgba(black, 0.87), 400: white, 500: white, 600: white, 700: white, 800: white, 900: white, A100: rgba(black, 0.87), A200: rgba(black, 0.87), A400: white, A700: white, ) ); $demo-primary: mat.define-palette($mat-demo-blue, 500); $demo-accent: mat.define-palette($mat-demo-red, 500); $demo-warn: mat.define-palette(mat.$red-palette, 500); $demo-theme: mat.define-light-theme($demo-primary, $demo-accent, $demo-warn); .app-theme-demo { @include mat.all-component-themes($demo-theme); $demo-primary-color: #476190; .topbar-items-container > div, .mat-toolbar, .mat-toolbar .mat-icon, .mat-raised-button.mat-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); } } .. _2021-06-or-newer: Template for 2021.06 or newer ----------------------------- .. important:: Adapt this template if you're using Fleio 2021.06 or newer. Themes generated using this template will not work with 2021.05.1 or older. .. code-block:: none @use '~@angular/material' as mat; $mat-demo-blue: ( 50: #e8eaf6, 100: #c5cae9, 200: #6294b8, 300: #386d92, 400: #144463, 500: #083652, contrast: ( 50: rgba(black, 0.87), 100: rgba(black, 0.87), 200: rgba(black, 0.87), 300: rgba(black, 0.87), 400: white, 500: white, 600: white, 700: white, 800: white, 900: white, A100: rgba(black, 0.87), A200: rgba(black, 0.87), A400: white, A700: white, ) ); $mat-demo-red: ( 50: #ffebee, 100: #ffcdd2, 200: #ef9a9a, 300: #e57373, 500: #ff3919, contrast: ( 50: rgba(black, 0.87), 100: rgba(black, 0.87), 200: rgba(black, 0.87), 300: rgba(black, 0.87), 400: white, 500: white, 600: white, 700: white, 800: white, 900: white, A100: rgba(black, 0.87), A200: rgba(black, 0.87), A400: white, A700: white, ) ); $demo-primary: mat.define-palette($mat-demo-blue, 500); $demo-accent: mat.define-palette($mat-demo-red, 500); $demo-warn: mat.define-palette(mat.$red-palette, 500); $demo-theme: mat.define-light-theme($demo-primary, $demo-accent, $demo-warn); .app-theme-demo { @include mat.all-component-themes($demo-theme); $demo-primary-color: #476190; $demo-accent-color: #ff3919; .notification-circle { background-color: $demo-accent-color !important; } .topbar-items-container > div, .mat-toolbar, .mat-toolbar .mat-icon, .mat-raised-button.mat-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); } } .. _2021-05-1-or-older: Template for 2021.05.1 or older ------------------------------- .. important:: Adapt this template if you're using Fleio 2021.05.1 or older. Themes generated with this template might not work with Fleio 2021.06.0. .. code-block:: none @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: .. code-block:: bash ng build --prod --extract-css Now locate 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`` or ``/var/webapps/fleio/frontend/enduser/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): .. code-block:: javascript ... "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: .. code-block:: javascript ... "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. .. _add-new-themes-docker: Adding new themes in docker install =================================== First, you need to generate the theme .css file as in the above docs. After that, 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: :ref:`change-docker-files`. Here are a few notes: The css theme file should be copied like this (do so for every panel): .. code-block:: bash COPY theme_name.css "$INSTALL_PATH/frontend/staff/assets/themes/theme_name.css" COPY theme_name.css "$INSTALL_PATH/frontend/enduser/assets/themes/theme_name.css" COPY theme_name.css "$INSTALL_PATH/frontend/reseller/assets/themes/theme_name.css" # only if reseller is enabled Also, the sed command from the Dockerfile should look like this (do so for every panel): .. code-block:: bash RUN sed -i \ 's^^^' \ "$INSTALL_PATH/frontend/staff/index.html" RUN sed -i \ 's^^^' \ "$INSTALL_PATH/frontend/enduser/index.html" RUN sed -i \ 's^^^' \ "$INSTALL_PATH/frontend/reseller/index.html" # only if reseller is enabled 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): .. code-block:: bash fleio edit staff.config.json fleio edit enduser.config.json fleio edit reseller.config.json # only if reseller is enabled .. _change-logo-docker: How to change the logo in Docker install ======================================== In order to change the logo for enduser, staff and reseller angular panels you will have to copy the new logo to the following locations, **inside the fleio_frontend_1 container**: .. code-block:: bash /var/webapps/fleio/frontend/staff/assets/img/staff/ /var/webapps/fleio/frontend/enduser/assets/img/enduser/ /var/webapps/fleio/frontend/reseller/assets/img/reseller/ Keep in mind that manually copying there does not make these persistent so on upgrade / recreate they will be removed. In order to make them persistent, you will have to create a custom frontend image, as it's described in this guide :ref:`change-docker-files`. Here are a few particular notes for this case: The Dockerfile new lines which will copy the logos to their location are the following: .. code-block:: bash COPY logo_light.png "$INSTALL_PATH/frontend/staff/assets/img/staff/logo_light.png" COPY logo_dark.png "$INSTALL_PATH/frontend/staff/assets/img/staff/logo_dark.png" COPY logo_light.png "$INSTALL_PATH/frontend/enduser/assets/img/enduser/logo_light.png" COPY logo_dark.png "$INSTALL_PATH/frontend/enduser/assets/img/enduser/logo_dark.png" COPY logo_light.png "$INSTALL_PATH/frontend/reseller/assets/img/reseller/logo_light.png" COPY logo_dark.png "$INSTALL_PATH/frontend/reseller/assets/img/reseller/logo_dark.png" Remember to update the `logoDark` and `logoLight` setting from angular configs as described in the previous section but this time by using the following command (do so for every panel): .. code-block:: bash fleio edit staff.config.json fleio edit enduser.config.json fleio edit reseller.config.json # only if reseller is enabled .. _custom-js: 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: .. code-block:: javascript (function () { // window.setHeaders = function (request, getCookie) { // return { // CustomHeader: getCookie('customCookieName'), // } // } })(); Notice the usage of `IIFE `_ .. _customizing-headers: 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).