Blame doc/usage/theming.rst

Pierre-Yves Chibon 704577
Theme your pagure
Pierre-Yves Chibon 704577
=================
Pierre-Yves Chibon 704577
Pierre-Yves Chibon 704577
Pagure via `flask-multistatic <https: flask-multistatic="" pagure.io="">`_</https:>
Pierre-Yves Chibon 704577
offers the possibility to override the default theme allowing to customize
Pierre-Yves Chibon 704577
the style of your instance.
Pierre-Yves Chibon 704577
Pierre-Yves Chibon 704577
By default pagure looks for its templates and static files in the folders
Pierre-Yves Chibon 704577
``pagure/templates`` and ``pagure/static``, but you can ask pagure to look
Pierre-Yves Chibon 704577
for templates and static files in another folder.
Pierre-Yves Chibon 704577
Pierre-Yves Chibon 704577
By specifying the configuration keys ``THEME_TEMPLATE_FOLDER`` and
Pierre-Yves Chibon 704577
``THEME_STATIC_FOLDER`` in pagure's configuration file, you tell pagure to
Pierre-Yves Chibon 704577
look for templates and static files first in these folders, then in its
Pierre-Yves Chibon 704577
usual folders.
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 9dd1c0
.. note: The principal is that pagure will look in the folder specified in
Pierre-Yves Chibon 9dd1c0
         the configuration file first and then in its usual folder, so the
Pierre-Yves Chibon 9dd1c0
         **file names must be identical**.
Pierre-Yves Chibon 9dd1c0
Pierre-Yves Chibon 129555
Example
Pierre-Yves Chibon 129555
-------
Pierre-Yves Chibon 9dd1c0
Pierre-Yves Chibon 1342a6
Let's take an example, you wish to replace the pagure logo at the top right
Pierre-Yves Chibon 1342a6
of all the pages.
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
This logo is part of the ``master.html`` template which all pages inherit
Pierre-Yves Chibon 1342a6
from. So what you want to do is replace this ``master.html`` by your own.
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
* First, create the folder where your templates and static files will be stored:
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
::
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
    mkdir /var/www/mypaguretheme/templates
Pierre-Yves Chibon 1342a6
    mkdir /var/www/mypaguretheme/static
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
* Place your own logo in the static folder
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
::
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 7b0a42
    cp /path/to/your/my-logo.png /var/www/mypaguretheme/static
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
* Place in there the original ``master.html``
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
::
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
    cp /path/to/original/pagure/templates/master.html /var/www/mypaguretheme/templates
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
* Edit it and replace the url pointing to the pagure logo (around line 27)
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
::
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
    - 
Pierre-Yves Chibon 1342a6
    + 
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
* Adjust pagure's configuration file:
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon c669d2
::
Pierre-Yves Chibon c669d2
Pierre-Yves Chibon 1342a6
    + THEME_TEMPLATE_FOLDER='/var/www/mypaguretheme/templates'
Pierre-Yves Chibon 1342a6
    + THEME_STATIC_FOLDER='/var/www/mypaguretheme/static'
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
* Restart pagure
Pierre-Yves Chibon d66fc1
Pierre-Yves Chibon d66fc1
Pierre-Yves Chibon d66fc1
.. note: you could just have replaced the `pagure-logo.png` file with your
Pierre-Yves Chibon d66fc1
         own logo which would have avoided overriding the template.
Pierre-Yves Chibon d66fc1
Pierre-Yves Chibon d66fc1
Pierre-Yves Chibon d66fc1
In production
Pierre-Yves Chibon d66fc1
-------------
Pierre-Yves Chibon d66fc1
Pierre-Yves Chibon d66fc1
Serving static files via flask is fine for development but in production
Pierre-Yves Chibon d66fc1
you will probably want to have apache server them. This will allow caching
Pierre-Yves Chibon d66fc1
either on the server side or on the client side.
Pierre-Yves Chibon d66fc1
Pierre-Yves Chibon d66fc1
You can ask apache to behave in a similar way as does flask-multistatic with
Pierre-Yves Chibon d66fc1
flask here, ie: search in one folder and if you don't find the file look
Pierre-Yves Chibon d66fc1
in another one.
Pierre-Yves Chibon d66fc1
Pierre-Yves Chibon d66fc1
`An example apache configuration <https: blob="" example.conf="" f="" flask-multistatic="" master="" pagure.io="">`_</https:>
Pierre-Yves Chibon 918dfa
is provided as part of the sources of `flask-multistatic`_.