# Customizing Pootle

In some cases it might be desirable to customize the styling of Pootle to fit in with your other websites or other aspects of your identity. It might also be required to add a common header or footer for proper visual integration and even adjust and enhance existing functionality.

It’s highly recommended to put any custom changes separate from the distributed files, so that upgrades are unlikely to affect your customizations.

## Customizing templates

In case you need to change a template, copy it into your custom `TEMPLATE_DIRS` with the same path name as it had before.

Warning

If you edit any templates, keep in mind that changes to the text could result in untranslated text for users of the non-English user interface.

You can customize specific blocks of templates by indicating which template the current template is customizing. Use the `{% overextends %}` template tag for that (requires to install the django-overextends package). This must be the first tag in the template.

    {% overextends 'browser/overview.html' %}

    {% block pre_content %}
    {{ block.super }}
    <h1>My custom content</h1>
    {% endblock %}

Check the original templates in order to know which blocks can be customized.

On upgrades, you will want to check if the templates and the contained blocks differ.

## Customizing JavaScript

You can place any custom scripts in your custom `STATICFILES_DIRS` directory and make them part of the default Pootle bundles by adding a very simple manifest.json file under the js/ directory of your custom `STATICFILES_DIRS`.

This file must contain an object of key-values where the keys correspond to the entry points defined by Pootle and the values are arrays of module names to include in the output bundle. Check out the pootle/static/js/webpack.config.js file to see the existing entry points.

Example:

    {
      "common": ["login.js", "extra_module.js"]
    }

In the example above, the login.js and the extra_module.js JavaScript modules will be added as part of the common bundle. If common didn’t exist as an entry point before, a new bundle will be output.

Note that the manifest.json file has to be valid JSON, otherwise it will be omitted.

Custom scripts can `require()` Pootle modules that are part of the core bundles by prefixing paths with `pootle/`. For instance the `require('pootle/models')` call will make Pootle’s own `models` module available in the scope of a 3rd party script.

Needless to say, you can refer to your custom scripts the same way as you would refer to any other static asset, i.e. by using the `{% static %}` template tag.

## Customizing CSS

Create any needed files under your custom `STATICFILES_DIRS` and reference them from your custom templates using the `{% static %}` template tag. You can also inline styles in your templates as usual.

## Customizing images

You should put your custom images in your custom `STATICFILES_DIRS`. From CSS you would just reference them using a relative path.

On the contrary, if you want to reference images from HTML code or inline CSS, you should use the `{% static %}` template tag.

## Customising robots.txt

The site robots.txt file uses a static template. There is no dynamic content. Place your custom robots.txt file in your custom templates folder and this will be served instead of Pootle’s default robots.txt file.

Larger installs will want to serve this file statically, bypassing Django completely. You can safely serve the robots.txt template file as is, statically, via your configured webserver.

## Installing JS build libraries

Before you can rebuild your static assets with any CSS or JavaScript customisations, you will need to install some Node.js libraries.

Before proceeding please make sure you have Node.js and npm installed in your system.

    (env) $ cd $pootle_dir
    (env) $ cd pootle/static/js/
    (env) $ npm install

`$pootle_dir` is the directory where Pootle is installed.

## Rebuilding assets after customization

Before rebuilding your assets for the first time you must install the JavaScript build libraries.

After doing any customizations, you will need to regenerate any modified bundles and gather all the static assets in a single place for public consumption.

You will need to activate your virtual environment before running these commands.

    (env) $ pootle webpack
    (env) $ pootle collectstatic --noinput --clear -i node_modules
    (env) $ pootle assets build