Customising Molly
=================
The Molly framework contains powerful functionality to allow for customisations
of the HTML, CSS and images to be displayed to users. Below, we cover the ways
you can use to customise the look and feel of your Molly install.
Changing Images and CSS
-----------------------
The first, and simplest, way to customise Molly is simply to replace whole
images in the final result. This can be images, icons, or anything else you
want.
.. note:: This assumes you are using the standard layout generated by the
installer. If you are using a non-standard layout, then the folder
which is used must be defined in ``STATICFILE_DIRS`` before the Molly
media directory.
This is simply done by placing any images you want to replace in the
'site_media' folder which have exactly the same path and name as the image in
the original Molly media.
.. note:: You can also replace CSS and JavaScript in the same way, although at
present you must replace the entire file, rather than individual
rules.
There are multiple ways to find the path of the image you want to replace.
Firstly, you should check the documentation of the app which should list all of
the media provided by that app, and its location.
.. warning:: At the time of writing, documentation is incomplete and not all
apps contain a complete list of media.
Other ways of finding media include looking at the URL of the image, and then
removing the URL component, e.g., if your STATIC_URL is set to '/compiled_media/' and
the URL of the image is '/media/weather/images/cloudy5.png', then the file to
place into the site_media folder is 'weather/images/cloudy5.png'. Alternatively,
looking in 'molly/media/' or 'molly/apps/APP/static/' will also find the media
associated with a particular app.
.. note:: Any changes to images won't take effect until the media folder is
rebuilt, the quickest way to do this is to re-run the installer.
Customising Templates
---------------------
As Molly is built on the Django framework, it should come as no surprise that
Molly uses Django's templating framework. For a thorough introduction to Django
templating, `Django's own documentation `_
is the best introduction, however a brief overview is presented below.
When Molly prepares a page to be rendered, it first executes a view, which
builds a "context" - a Python dictionary consisting of variables which are
available in the view for rendering. It then passes this dictionary to a
particular template file for rendering. For the filename of a particular
template file which is rendered on a particular view is listed in the
documentation for that app.
.. warning:: At the time of writing, documentation is incomplete and not all
apps contain a complete list of templates, views and context
variables.
Syntax of a Template
""""""""""""""""""""
The syntax of a template file consists of HTML interspersed with variables and
template tags. Variables are code like ``{{ bus_stop }}``, which inserts the
value of the variable in the context called ``bus_stop``. The ``.`` seperator
can be used to access members of variables, e.g., ``{{ entity.title }}`` will
print the title of an entity object.
.. note:: The list of variables available in the context is shown in the
documentation for that app.
Template variables can also be put through filters, this is done with the ``|``
character, and this modifies a variable in a way defined by the filter. e.g.,
`` {{ entity.title|upper }}`` results in the title of a passed in entity being
displayed in upper case.
.. note:: Some non-core template tags must first be loaded before they can be
used in a template. This is done by placing ``{% load LIBRARY %}`` at
the top of the file, where LIBRARY is the name of the library
containing that template tag or filter. The Molly utilities section of
the documentation contains a list of all template tag libraries
available with Molly.
Also available are template tags, which are like function calls. These use
syntax such as: ``{% for entity in entities %} ... {% endfor %}``. This code
loops over a list in the context (called entities) and exposes one entity at a
time in a variable called ``entity`` which the code inside the for loop can use.
Also available are if statements and code to lookup URLs.
.. seealso:: The `Django reference documentation `_
contains a full list of template tags and filters.
Blocks
""""""
Templates support inheritance, which means that a template can "inherit" from
another template, taking its styling and other content from another template,
and then replacing part of the other template with the content you specifically
want to render. This is accomplished in Molly by providing a base template, and
then having individual templates replace the body of this base template with the
actual content to be displayed to the user.
This is indicated in code by ``{% extends "base.html" %}``, which indicates that
this page "extends" base.html. The blocks then defined in that particular
template override the content that would have been shown in that place in
base.html, resulting in a consistent template for the user.
Molly extends this further by allowing even smaller parts of a template to be
replaced with other content, which allows you to only alter part of a template
without having to replace the entire template that comes bundled with Molly.
Replacing Whole Templates
"""""""""""""""""""""""""
.. note:: This assumes you are using the standard layout generated by the
installer. If you are using a non-standard layout, then the folder
which is used must be defined in ``TEMPLATE_DIRS`` before the Molly
templates directory.
If in your site you would like to replace an entire page with your custom
template, this is done by creating a file in the ``templates/`` directory in
your site with the same name as the template being overriden. This file is then
rendered instead of the file that comes with Molly.
Overriding Parts of Templates
"""""""""""""""""""""""""""""
If you wish to only override a part of a template that comes with Molly, rather
than the entire template, this is also supported, using the 'Blocks' mechanism
outlined above. In this case, you can keep almost all of the original template
code in Molly, benefitting from any updates or changes that affect it, and then
customise only the small part of it you want to do.
.. seealso:: The applications reference pages have a list of blocks that are
extendable for each view.
To do this, you must first create a template in the same way as for a whole
template, but instead of replacing the entire content, you can simply extend
the original template, which is available with the path
``molly_default/app/template.html``, and then add a new block for each part of
the template you wish to change, rather than the entire template.
`base.html` - an example
""""""""""""""""""""""""
This section works through an example of styling Molly's base template. It may
be beneficial to have the Molly development server running (see the
:doc:`install guide ` for details on how to do this) so you can see
your changes in real time.
`base.html` is the very root of the entire template tree, it defines the basic
styling which is on every page of the site (apart from the desktop app). Most
sites will want to start by styling this.
To start, you must create a file called ``base.html`` in the ``templates/``
directory of your site. If you create this as an empty file, you should now
start seeing a blank page on your site, which means that your new base template
is being rendered. As the base template does not contain anything yet, the blank
page should be expected!
.. note:: The front page is not a good example, as it makes multiple changes to
the base template. It would be best to use a sub-page, such as the
weather page, to view the changes.
The next step is to make the new base template inherit from the one that comes
included in Molly. We can do this by simply adding one line to the new base.html
.. code-block:: html
{% extends "molly_default/base.html" %}
This should now result in a page which looks exactly like the one that comes
with Molly. The key difference now is that all requests are going through our
new base template, so we can start adding and changing things to do what we
would like to do.
Two things you may want to change to get started are the page name as it appears
in the of the document and in the navigation options for non-smart
phones. There are two blocks to do this, called ``site_title`` and
``breadcrumb_0``. We can now override these by adding the following two lines to
``base.html``.
.. code-block:: html
{% block site_title %}m.ox | {% endblock %}
{% block breadcrumb_0 %}m.ox{% endblock %}
This will change the start of the for each page to be "m.ox" followed by
a pipe, and then the first navigation breadcrumb for non-smart phones to be
"m.ox".
.. note:: If you're looking to just change the logo, this can be done using the
methods for replacing images above - simply place your logo with the
same name in the ``site_media`` folder.
With these simple changes and suitable logo replacements, your Molly instance
should now be ready to go!
Referring to other views
""""""""""""""""""""""""
To get a link to another view, this can be generated by the
`Django url tag `_
using the namespace prefix of the app and the name of the view (as documented
on that application's page)
E.g., for the 'index' view of the contact app, the following template tag will
generate a URL::
{% url contact:index %}