.. /* * This file is part of the SavaPage project . * Copyright (c) 2026 Datraverse B.V. * Author: Rijk Ravestein. * * SPDX-FileCopyrightText: (c) 2020 Datraverse B.V. * SPDX-License-Identifier: CC-BY-SA-4.0 * * For more information, please contact Datraverse B.V. at this * address: info@datraverse.com */ .. _ch-customization: .. figure:: ../images/manual/savapage-logo-no-text-100px.png :width: 75px Customization ============= .. admonition:: |ADMONITION_TABLE_OF_CONTENTS| - :numref:`{number}. {name} ` - :numref:`{number}. {name} ` SavaPage can be customized to match your organizational identity. Customization makes SavaPage an integral part of your organization rather than an external tool. .. note:: Customization is an advanced topic. If you need help, contact your :ref:`SavaPage Service Provider `. .. _ch-custom-webapp: Custom Web App -------------- .. contents:: :depth: 1 :local: .. _ch-custom-webapp-intro: Introduction ~~~~~~~~~~~~ Web App customization is controlled in the ``/opt/savapage/server/custom/web.properties`` file. An annotated ``web.properties.template`` file is installed for your convenience. .. tip:: Each key value in the ``/opt/savapage/server/custom/web.properties`` file can be overruled at runtime by specifying the key value in the |RST_LINK_CONFIG_EDITOR|. If the configuration key value is left empty customization falls back to the value in the properties file. .. _ch-custom-webapp-look-and-feel: Web App Look-and-feel ~~~~~~~~~~~~~~~~~~~~~ .. contents:: :depth: 1 :local: The default look-and-feel of Web Apps has a simple drawing of green hills with a blue sky as background. You can disable this default by setting the value of the ``webapp.style.default.enable`` config item to ``N``. See |RST_LINK_CONFIG_EDITOR| on how to change this value. The look-and-feel of Web Apps can be customized by theming and CSS tailoring. .. _ch-custom-webapp-theming: Web App Theming ^^^^^^^^^^^^^^^ SavaPage uses `jQuery Mobile `__ as user interface system to create responsive Web Apps that are accessible on all smartphone, tablet and desktop devices. jQuery Mobile supports theming. Themes can be built online with the `ThemeRoller for Mobile `__ tools and deployed in SavaPage by downloading the zipped theme file and extracting the content of the ``/themes/`` folder into the ``/opt/savapage/server/custom/web/themes`` directory. The ``web.properties`` file contains entries to specify a separate CSS theme for each Web App, as shown in the example below: .. callout:: .. code-block:: ini webapp.theme.admin=admin.min.css # <1> webapp.theme.jobtickets=jobtickets.min.css # <2> webapp.theme.pos=admin.min.css # <3> webapp.theme.user=user.min.css # <4> .. annotations:: :1: CSS theme file name for the |RST_LINK_ADMIN_WEBAPP|. :2: CSS theme file name for the |RST_LINK_JOBTICKETS_WEBAPP|. :3: CSS theme file name for the |RST_LINK_POS_WEBAPP|. :4: CSS theme file name for the |RST_LINK_USER_WEBAPP|. SavaPage uses swatch [1]_ **a** for all pages and dialogs. Swatch **b** is used for page and dialog headers, and in some cases for list dividers. You can store a theme in a subdirectory of ``/opt/savapage/server/custom/web/themes`` and use its relative path to reference a CSS theme file. .. [1] A swatch is one of several colour schemes that can be provided by a jQuery Mobile theme. Single-letter designations are used for swatches. The default theme provides two swatches. The "a" swatch is a neutral, gray swatch, and the "b" swatch has a darker color scheme designed to contrast with the "a" swatch. Swatch "b" is used to draw special attention to certain elements in a user interface styled with "a". .. _ch-custom-webapp-css: Custom CSS ^^^^^^^^^^ Advanced tailoring can be done with custom CSS files. They are rendered as last, so they have the final say about styling. The ``web.properties`` file contains entries to specify a custom CSS file for each Web App, as illustrated in the example below: .. callout:: .. code-block:: ini webapp.custom.admin=admin.css # <1> webapp.custom.jobtickets=jobtickets.css # <2> webapp.custom.pos=pos.css # <3> webapp.custom.user=user.css # <4> .. annotations:: :1: Custom CSS file for the |RST_LINK_ADMIN_WEBAPP|. :2: Custom CSS file for the |RST_LINK_JOBTICKETS_WEBAPP|. :3: Custom CSS file for the |RST_LINK_POS_WEBAPP|. :4: Custom CSS file for the |RST_LINK_USER_WEBAPP|. Custom CSS files are stored in ``/opt/savapage/server/custom/web/``. Subdirectories are allowed, and you can use their relative path to reference the custom CSS file. Any content placed in ``/opt/savapage/server/custom/web/``, such as images, can be accessed in CSS via a URL beginning with ``/custom/web/``. For example if a file named ``logo.png`` is placed in ``/opt/savapage/server/custom/web/images`` it can be accessed via the URL ``/custom/web/images/logo.png`` .. figure:: ../images/manual/screenshots/admin/sp-01-15-custom-css-sample-1.png :width: 400 User Web App: Custom CSS - Sample #1 .. figure:: ../images/manual/screenshots/admin/sp-01-15-custom-css-sample-2.png :width: 400 User Web App: Custom CSS - Sample #2 .. _ch-custom-webapp-html: Custom HTML ^^^^^^^^^^^ Extra tailoring can be done with HTML snippet files to be injected into the Web App. Injection points are defined at the top of the Login and About Page for each Web App. Snippet files must be placed in the ``/opt/savapage/server/custom/html/`` directory. The default snippet is for the English locale. You can create i18n variants by appending the locale to the base file name. For example: ``user-login_de.html`` is the German variant of ``user-login.html``. Snippet files are assigned in the ``web.properties`` file, as shown below. Snippets must refer to the default English language variant. At runtime the locale variant (when applicable and available) is used. .. callout:: .. code-block:: ini webapp.html.admin.about=admin-about.html # <1> webapp.html.admin.login=admin-login.html webapp.html.jobtickets.about=jobtickets-about.html # <2> webapp.html.jobtickets.login=jobtickets-login.html webapp.html.mailtickets.about=mailtickets-about.html # <3> webapp.html.mailtickets.login=mailtickets-login.html webapp.html.payment.about=payment-about.html # <4> webapp.html.payment.login=payment-login.html webapp.html.pos.about=pos-about.html # <5> webapp.html.pos.login=pos-login.html webapp.html.printsite.about=printsite-about.html # <6> webapp.html.printsite.login=printsite-login.html webapp.html.user.about=user-about.html # <7> webapp.html.user.login=user-login.html .. annotations:: :1: snippets for |RST_LINK_USER_WEBAPP| About Dialog and Login Page. :2: snippets for |RST_LINK_JOBTICKETS_WEBAPP| About and Login Page. :3: snippets for |RST_LINK_MAILTICKETS_WEBAPP| About and Login Page. :4: snippets for |RST_LINK_PAYMENT_WEBAPP| About Dialog and Login Page. :5: snippets for |RST_LINK_POS_WEBAPP| About Dialog and Login Page. :6: snippets for |RST_LINK_PRINT_SITE_WEBAPP| About Dialog and Login Page. :7: snippets for |RST_LINK_USER_WEBAPP| About Dialog and Login Page. You can store custom HTML files in a subdirectory of ``/opt/savapage/server/custom/html/`` and use its relative path to reference the HTML file. .. note:: The keys in the ``web.properties`` file are also present as Configuration Property, the latter taking precedence over the former. See |RST_LINK_CONFIG_EDITOR| on how to enter these property values. .. important:: Please use this template when creating snippets for Login pages. The CSS classes are needed to toggle visibility of sub-parts in different Login modes. .. code-block:: html .. _ch-custom-webapp-i18n: Custom i18n ^^^^^^^^^^^ In rare cases an application manager might want to override i18n text of Web App pages, dictionaries or messages. Overrides of packaged i18n ``*.xml`` files are placed in ``/opt/savapage/server/custom/i18n/``. Each override must be located in a subdirectory with a path identical to the original ``*.xml`` file. The content of the override file can be restricted to just the overridden keys. Overrides of packaged ``*.properties.xml`` files (Web App HTML parts) must have a ``*.xml`` name **without** the "``.properties.``" part. For all other ``*.xml`` files the name can remain the same. The base name of English i18n files must end with "``_en``". Example: .. code-block:: /opt/savapage/server/custom/i18n/org/savapage/core/i18n/PrintOutNounEnum_de.xml /opt/savapage/server/custom/i18n/org/savapage/core/services/impl/messages_de.xml /opt/savapage/server/custom/i18n/org/savapage/server/pages/Login_de.xml /opt/savapage/server/custom/i18n/org/savapage/core/i18n/PrintOutNounEnum_en.xml /opt/savapage/server/custom/i18n/org/savapage/core/services/impl/messages_en.xml /opt/savapage/server/custom/i18n/org/savapage/server/pages/Login_en.xml Custom i18n must be activated in :ref:`server.properties ` with: .. code-block:: ini webapp.custom.i18n=true .. warning:: Custom i18n is an advanced feature and should be implemented in consultation with SavaPage Tech Support. .. note:: Added or changed custom i18n files have immediately effect when the i18n cache is cleared in the Admin Web App :ref:`About > Java ` section, or when |PRODUCT_NAME| is restarted. .. tip:: Custom i18n is a great way to get started with localizing SavaPage to your own region. See :ref:`Notes for Translators `. .. _ch-custom-webapp-i18n-ipp: Custom i18n for IPP ^^^^^^^^^^^^^^^^^^^ IPP attribute localization can be overridden with special i18n XML files. See :ref:`IPP Localization `.