Define (background-/banner-)images per page
Switch branches/tags
Clone or download
kampfschlaefer Optional select for the page
When an optional page-parameter is given, the named image for that page is searched. Usable to select images for sub-pages on index pages.
Latest commit acaacf5 Aug 21, 2014


Define (background-/banner-)images per page

The Problem

At least our designer likes to create websites where pages can have individual backgrounds. Or individual banners. So for example the index-page has a generic background, while all pages under Contact should have another background.

Mezzanine has this great feature that templates are searched by page-name.html, <content_type>.html and then page.html. so one would just create specific templates for the pages that get different background. Its a nice solution that even works. But it has drawbacks:

  • To change the background, the designer has to ask the programmer because it can't be changed in the admin-backend.
  • When you have multiple child-pages which should all get the background of the parent-page, you end up with templates for each page.
  • When the designer or writer adds another page, the programmer has to add another template.

Mostly the problem is mixing content with design-code.

The Solution

Here is how mezzanine-pageimages solves this:

  • In the admin-backend we just add a way to define images for certain roles and specific to certain pages. Plus a way to define default-images for the roles.
  • We define a template-tag pageimage that takes a role and the looks for the fitting image for the current page.
  • When there is no image for that role for the current page, it looks for an image on the parent page. It goes upwards until there is no parent or an image is found.
  • When there is still no image found, the default image for that role is returned, if there is one defined.


This package is on To simply install it just do pip install mezzanine-pageimage. Or define it as a requirement in your requirements.txt or

For hacking on mezzanine-pageimages do a git-checkout and install via pip install -e. Or install by pip install -e git+


Add the app to your INSTALLED_APPS. You can define your own image-roles in the SETTINGS in

    ('BACKGROUND', 'Description text'),

Then use it in your templates:

{% load pageimage_tags %}

Lets get the url for the background image: {% pageimage 'BACKGROUND' %}