.. _customization:

Customization
----------------

LinOTP web components are based on templates and CSS. You may change the look and feel
of the WebUI but we recommend not to change the default templates and style sheets, as an
update may destroy your changes. Therefor custom templates and style sheets can
be defined.

Templates
~~~~~~~~~

The place where the custom templates are read from can be defined in
``/etc/linotp2/linotp.ini`` in the section ``[app:main]``:: 

   custom_templates = /etc/linotp2/custom-templates/

All templates will be searched in this directory. If the template does not
exist here, the default template is used - usually from::

   /usr/lib/python2.7/dist-packages/linotp/templates

To modify the look and feel, copy the desired templates from the default
location to this custom location and keep the structure of the sub directories.

.. code::

  cp -rL /usr/lib/python2.7/dist-packages/linotp/templates/* /etc/linotp2/custom-templates/

After changing the custom templates the Pylons cache needs too be emptied and
it is necessary to restart the web server::

   rm -rf /etc/linotp2/data/* 
   service apache2 restart

.. tip:: For mayor updates (like LinOTP 2.9.x -> 2.10) it is recommended to
 backup /etc/linotp2/custom-templates, delete the content and to copy the new
 files from /usr/lib/python2.7/dist-packages/linotp/templates. After this the
 changes from the backup should be readded to the fresh copies of the custom
 template files.

Style Sheets
~~~~~~~~~~~~

The style sheets can be used among other things to change the logo as described
in the next chapter and are located in the following directory:

.. code::

   /usr/lib/python2.7/dist-packages/linotp/public

The default stylesheets are::

   /usr/lib/python2.7/dist-packages/linotp/public/manage/style.css
   /usr/lib/python2.7/dist-packages/linotp/public/selfservice/style.css
   /usr/lib/python2.7/dist-packages/linotp/public/openid/style.css

The following files can be create to overrule the default style sheets. They
are applied on top of the default style sheets. It is recommended to include
only required changes in the custom files::

   /etc/linotp2/custom-style/selfservice-style.css
   /etc/linotp2/custom-style/manage-style.css
   /etc/linotp2/custom-style/openid-style.css

After changing the style sheets the Pylons cache needs too be emptied and
it is necessary to restart the web server::

   rm -rf /etc/linotp2/data/* 
   service apache2 restart

.. tip:: If updating from LinOTP 2.9.x -> 2.10 a helper script tries to copy
 previously used CSS files to the new location /etc/linotp2/custom-styles.
 Images need to be transferred manually. It might also be necessary to adapt the
 paths to the image files (/custom leads to /etc/linotp2/custom-styles).

Changing the Logo
~~~~~~~~~~~~~~~~~

It is easy to change the logos on the ``/manage`` and on the ``/selfservice`` portal.
The LinOTP logo is defined as a background image of the div ``#logo``
(``/selfservice``) or ``#header #logo`` (``/manage``).

.. note:: Please setup the custom style sheets as described in the previous
 chapter before following the next steps.

These stylesheets need to be modified::

   /etc/linotp2/custom-style/selfservice-style.css
   /etc/linotp2/custom-style/manage-style.css
   /etc/linotp2/custom-style/openid-style.css


There is the id definition ``#logo`` (``/selfservice``) or ``#header #logo``
(``/manage``) which points to the corresponding image file at
``/usr/share/pyshared/linotp/public/images/``.

**Transfer the new logo file to the correct position:**

.. code::

  mkdir /etc/linotp2/custom-style/images 
  cp /root/<IMAGE.PNG> /etc/linotp2/custom-style/images/

.. tip:: The ``/etc/linotp2/custom-style/`` directory can be referenced with ``/custom`` in the CSS files.

**Example /manage:**

.. code::

 nano /etc/linotp2/custom-style/manage-style.css

  #header #logo {
    background-image: url(/custom/images/linotp_logo_103x35.png);
  }

**Example /selfservice:**

.. code::

 nano /etc/linotp2/custom-style/selfservice-style.css

  #logo{
     background-image:  url(/custom/images/linotp_logo_103x35.png);
  }

.. tip:: With LinOTP 2.10.0.3 the customisations are maintained in /etc/linotp2, the custom-templates and custom-style (with images) folders are backed up by the backup and restored with restore.