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 ‘/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.

See also

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.

See also

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 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

{% 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 <title> 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.

{% block site_title %}m.ox | {% endblock %}
{% block breadcrumb_0 %}m.ox{% endblock %}

This will change the start of the <title> 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 %}