Tuleap Customisations
=====================

System configuration files
--------------------------

The PHP scripts take many values from a configuration file located in
``/etc/tuleap/conf/local.inc``. Make sure that you read this file where the role
of each variable is well documented.

Database configuration is read from ``/etc/tuleap/conf/database.inc``.

The file ``/etc/tuleap/conf/encryption_secret.key`` is used by Tuleap when data
need to be encrypted. It is generated by Tuleap the first time it is needed.
If this file is lost or altered, any encrypted data are not recoverable.

Plugins specific configuration can be found in the folder ``/etc/tuleap/plugins/``.

.. _organization-logo:

Organization Logo
-----------------

By default, the platform logo is the Tuleap one. It is displayed on every pages of
the application and is sent in email notifications. You can dock the logo of your
organization instead. This can be achieved by putting
your nice logos in ``/var/lib/tuleap/images``.

Email notifications
```````````````````
For email notifications, platform administrator must push an image file in PNG format
in ``/var/lib/tuleap/images/organization_logo_mail.png`` (recommended size: 97×42px).
Once file is created, cache must be invalidated with ``tuleap -c`` command.

For web interface, it is a little bit more complex since there are different places where
the logo can be displayed.

Web interface
`````````````

Tuleap can display your logo in two different format. PNG or SVG. Independently of the
chosen format, you should check that the logo is displayed nicely (for each theme variants):

* On Homepage (with and without scroll)
* On project sidebar expanded
* On project sidebar collapsed

SVG alternative (recommended)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The default logo is in SVG format. We recommend this format so that your logo can be
displayed nicely both on light background and on the sidebar which has a dark background.
Furthermore the logo in SVG format has the nice capability to adapt itself to the current
theme color.

Platform administrator must push two image files in SVG format:

* ``/var/lib/tuleap/images/organization_logo.svg`` (maximum size: 180×40px)
* ``/var/lib/tuleap/images/organization_logo_small.svg`` (maximum size: 40×40px)

Once files are created, cache must be invalidated with ``tuleap -c``.

The small version is used when the project sidebar is collapsed.

As soon as both files are present, then the logo will be considered customized and
it will be provided instead of the default logo.

In order to ensure readability of the logo on every context, we provide two class names
to put in your SVG elements (``<path>``, …):

* ``logo-svg-fill-theme-color``
* ``logo-svg-fill-default-text-color``

This will be rendered with the following color according to context:

+------------+---------------------------+----------------------------------+
| Context    | logo-svg-fill-theme-color | logo-svg-fill-default-text-color |
+============+===========================+==================================+
| No sidebar |  theme color              |  blackish                        |
+------------+---------------------------+----------------------------------+
| Sidebar    |  theme color              |  white                           |
+------------+---------------------------+----------------------------------+

Without those class names, the color of the element will stay the same
on each pages of Tuleap.

Here is an example of class names usage:

``organization_logo_small.svg``

.. code-block:: html
    :linenos:
    :emphasize-lines: 7

    <svg xmlns="http://www.w3.org/2000/svg"
        width="38.796" height="29.986"
        viewBox="0 0 10.265 7.934"
    >
        <path
            d="M1.374 0a.432.432 0 00-.312.136.995.995 0 0…75 3.967-.943v-.105z"
            class="logo-svg-fill-theme-color"/>
    </svg>

``organization_logo.svg``

.. code-block:: html
    :linenos:
    :emphasize-lines: 7,15,19

    <svg xmlns="http://www.w3.org/2000/svg"
        viewBox="0 0 28.84 7.938"
        height="30" width="109"
    >
        <path
            d="M1.374 0a.432.432 0 00-.312.136.995.995 0 0…75 3.967-.943v-.105z"
            class="logo-svg-fill-theme-color"/>
        <g style="line-height:1.25"
            aria-label="Locomotive Manipulation"
            font-weight="400" font-size="12"
            font-family="sans-serif" letter-spacing="0" word-spacing="0"
        >
            <path
                d="M10.47.405h.313v2.051h1.127v.264h-1.44zm…5-.164.38z"
                class="logo-svg-fill-default-text-color"/>
            <path
                d="M10.47 4.815h.466l.59 1.575.595-1.575h.4…5.153.545z"
                letter-spacing="-.74"
                class="logo-svg-fill-default-text-color"/>
        </g>
    </svg>

.. warning::
    If parts of the logo cannot be dynamically changed according to
    the current context (for example corporate logo is vibrant red, Design
    department does not allow to transform it blue for good reasons), then
    we strongly encourage platform administrator and desigers to check if
    the logo is rendered nicely and that they avoid harmful combinaisons of
    colors like vibrant red on green sidebar for example.

PNG alternative (deprecated)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you cannot afford having a SVG version of your organization logo, then you can fallback
on the PNG format. The images will be the same on every pages of Tuleap and cannot be
adapted to user's theme color.

Platform administrator must push two image files in PNG format:

* ``/var/lib/tuleap/images/organization_logo.png`` (maximum size: 180×40px)
* ``/var/lib/tuleap/images/organization_logo_small.png`` (maximum size: 40×40px)

Once files are created, cache must be invalidated with ``tuleap -c``.

The small version is used when the project sidebar is collapsed.

Site content
------------

Several PHP scripts in the source code contain pieces of text or code that are generally here to give instructions to the users or to provide site-specific information. Typical examples are: the introductory text at the top of the home page, instructions on how to connect to the SVN repository, instructions and guidelines in the project registration process, LDAP repository information, etc.

These pieces of text or code are isolated from the PHP scripts themselves and they are all placed under the top directory 'site-content'. The file path to the content of a given script (or part of a script) follows the following pattern:

``site-content/LANG_COUNTRY/src_path/sometext.txt``

where:

    LANG_COUNTRY is the standard ISO naming for language and countries: either en_US or fr_FR.
    src_path is the name of the directory under src which contains the script the text belongs to.
    sometext.txt is a file name that contains the piece of text itself.

To customise the content of a given script for your site go through the following steps:
    - under /etc/tuleap create the site-content directory if it doesn't exist.

For each piece of text that you want to customize, copy the original sometext.txt file under the ``/etc/tuleap/site-content/``
with the exact same path. For instance if you want to customise the introductory text of the home page,
copy ``/usr/share/tuleap/site-content/en_US/homepage/welcome_intro.txt`` into ``/etc/site-content/en_US/homepage/welcome_intro.txt``
and edit it as you like.
Be careful that some of these files contain PHP scripting that you probably want to preserve in your customised version.
Deleting the PHP scripting could break the entire PHP scripts.
Ask on the Tuleap devel mailing list if you are unsure of what you are doing.

Read also Localization below for additional information on how to customise interface messages.

Localization
------------

Tuleap source code is localized so the interface is displayed in the user-selected language. Currently, Tuleap supports the following languages:

* English (native)
* French (100% translated)
* Community contribution:

  * Brazilian Portugueze (partly translated)

Your language is not in the list? Please refer to `Internationalization <https://tuleap.net/plugins/git/tuleap/tuleap/stable?a=blob&f=doc%2Finternationalization.md>`_ in developer guide to see how you can contribute.

Customized localization (deprecated)
````````````````````````````````````

Messages are stored in the site-content directory: there is one message file per service, with the same name as the service, ending with '.tab'. E.g. 'site-content/en_US/tracker/tracker.tab' contains all tracker messages in English.

The format of the message files is very simple: one line per message, with the following format


    key1 :kbd:`Tab(↹)` key2 :kbd:`Tab(↹)` your message here

As with other site-content files, you may customize the language files, so that you can change a few specific messages:

    Copy the language file you need to customize from the ``/usr/share/tuleap/site-content`` subdirectory to the corresponding subdirectory in ``/etc/tuleap/site-content`` (see Site content above).
    Remove all lines that you don't need to change and only keep the lines you will modify.
    Change the messages.
    Repeat the operation for all the languages you need to support on your server.

For performance reasons, Tuleap localization is kept in a cache file. When your customisations are finished, run the following command to clear this cache and see your modifications:

.. code-block:: bash

    $ tuleap --clear-caches