=========================================
Frontend customization (prior to 2023.03)
=========================================

.. 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`.


.. contents:: :local:


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

    * ``/var/webapps/fleio/frontend/staff`` - staff panel
    * ``/var/webapps/fleio/frontend/enduser`` - enduser panel


.. _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.

.. note::

    You may need to specify `@angular/cli` and `@angular/material` specific versions in the following commands, check
    template notes related to your Fleio version first.

.. 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  # when asked for prebuilt theme choose CUSTOM then 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:`2023.02-or-newer`
   * :ref:`2022.03-or-newer`
   * :ref:`2022.02-or-newer`
   * :ref:`2021-06-or-newer`
   * :ref:`2021-05-1-or-older`

.. _2023.02-or-newer:

Template for 2023.02 or newer
-----------------------------

.. important::

    Adapt this template if you're using Fleio 2023.02 or newer. Themes generated using this template will not work with
    2023.01.1 or older.

    Requirements:

    * have node v18.13.0 installed
    * when running `npm install -g @angular/cli` specify version "15.1.3", e.g.: ``npm install -g @angular/cli@15.1.3``
    * when running `ng add @angular/material` specify version "15.1.2", e.g.: ``ng add @angular/material@15.1.2``

Notable changes from previous version:

    * ``$demo-theme: mat.define-light-theme()`` statement now takes a ``color`` parameter
    * ``@include mat.all-component-themes($demo-theme);`` statement becomes
      ``@include mat.all-legacy-component-themes($demo-theme);`` - this is because we've updated Angular & Angular
      Material to version 15 and we're using legacy components until we completely migrate to the MDC-based Angular
      Material Components

.. 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((
      color: (
        primary: $demo-primary,
        accent: $demo-accent,
        warn: $demo-warn,
      )
    ));
    .app-theme-demo {
      @include mat.all-legacy-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, .notification-text a {
        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.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);
      }
    }


Building the theme for 2023.02 or newer
=======================================

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 also make use of some already defined color palettes (e.g.: ``mat.$blue-palette``) from Angular Material which
can be found in ``node_modules/@angular/material/core/theming/_palette.scss``.

For additional information, you can read: `Angular Material theming guide <https://material.angular.io/guide/theming>`_,
`Sass/scss basics <https://sass-lang.com/guide>`_.

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

.. code-block:: bash

    ng build

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 add the theme to your installation following this guide: :ref:`add-new-themes-docker`.

After that include the theme in the available themes list by :ref:`editing panels configuration files<frontend-config>`
and updating the "availableThemes" setting like described here: :ref:`themes_in_my_profile`.

.. 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.


Building the theme for 2023.01 or older
=======================================

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 <https://material.angular.io/guide/theming>`_,
`Sass/scss basics <https://sass-lang.com/guide>`_.

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/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"


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

.. code-block:: bash

    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"

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


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

.. code-block:: bash

    fleio edit staff.config.json
    fleio edit enduser.config.json


How to change the logo in Docker install
========================================

Follow this guide to change the logo in Fleio panels: :ref:`change-logo`.


Adding custom javascript
========================

Follow this guide to add custom javascript in Fleio panels, or to customize request headers: :ref:`add-custom-js`.