Frequently Asked Questions

These are some of the most frequently asked questions on the Mezzanine mailing list.

What do I need to know to use Mezzanine?

First and foremost, Mezzanine is based on the Django framework. All aspects of working with Mezzanine will benefit from a good understanding of how Django works. Many questions that are asked within the Mezzanine community can easily be answered by reading the Django documentation.

Setting up a development environment, and deploying a Mezzanine site, is the same process as doing so with a regular Django site. Areas such as version control, installing Python packages, and setting up a web server such as Apache or NGINX, will all be touched upon.

Modifying the look and feel of a Mezzanine powered site requires at least an understanding of HTML, CSS and Django’s templating system.

Extending Mezzanine by Creating Custom Content Types or using additional Django apps, will require some knowledge of programming with Python, as well as a good understanding of Django’s components, such as models, views, urlpatterns and the admin.

Back to top

Why aren’t my JavaScript and CSS files showing up?

Mezzanine makes exclusive use of Django’s staticfiles app, for managing static files such as JavaScript, CSS, and images.

When the DEBUG setting is set to True, as it would be during development, the URL defined by the setting STATIC_URL (usually /static/), will host any files found in the static directory of any application listed in the INSTALLED_APPS setting.

When DEBUG is set to False, as it would be for your deployed production site, you must run the collectstatic command on your live site, which will copy all of the files from the static directory in each application, to the location defined by the STATIC_ROOT setting. You then need to configure an alias in your web server’s config (Apache, NGINX, etc) that maps the URL defined by STATIC_URL to serve files from this directory.

Long story short, Django doesn’t serve static content when deployed in production, leaving this up to the public facing web server, which is absolutely the best tool for this job. Consult Django’s staticfiles guide for more information.

Back to top

Why does the WYSIWYG editor strip out my custom HTML?

By default, Mezzanine strips out potentially dangerous HTML from fields controlled by the WYSIWYG editor, such as tags and attributes that could be used to inject JavaScript into a page. If this didn’t occur, a clever staff member could potentially add JavaScript to a page, that when viewed by an administrator (a staff member with superuser status), would cause the administrator’s browser to post an update via the admin, that updates the staff member’s user account and assigns them superuser status.

The above scenario is a fairly obscure one, so it’s possible to customise the level of filtering that occurs. Three levels of filtering are implemented by default, that can be controlled in the settings section of the admin. These are High (the default), Low (which allows extra tags such as those required for embedding videos), and None (no filtering occurs). This is implemented via the RICHTEXT_FILTER_LEVEL setting.

If your situation is one where your staff members are completely trusted, and custom HTML within WYSIWYG fields is required, then you can modify the filter level accordingly. Further customisation is possible via the RICHTEXT_ALLOWED_TAGS, RICHTEXT_ALLOWED_ATTRIBUTES and RICHTEXT_ALLOWED_STYLES settings, which can have extra allowed values appended to using the append argument in Mezzanine’s settings API. See the Registering Settings section for more information.

Back to top

Why isn’t the homepage a Page object I can edit via the admin?

In our experience, the homepage of a beautiful, content driven website, is quite different from other pages of the site, that all fall under sets of repeatable page types. The homepage also differs greatly from site to site. Given this, Mezzanine doesn’t presume how your homepage will be structured and managed. It’s up to you to implement how it works per site.

By default, the homepage provided with Mezzanine is a static template, namely mezzanine/core/templates/index.html (or templates/index.html if stored directly in your project). You can change the urlpattern for the homepage in your project’s urls.py module. Be certain to take a look at the urls.py module, as it contains several examples of different types of homepages. In urls.py you’ll find examples of pointing the homepage to a Page object in the page tree, or pointing the homepage to the blog post listing page, which is useful for sites that are primarily blogs.

Of course with Django’s models, admin classes, and template tags, the sky is the limit and you’re free to set up the homepage to be managed in any way you like.

Back to top

Why is Mezzanine a Django project, and not a Django app?

Mezzanine comes with many features that are related to content driven websites, yet are quite distinct from each other. For example user-built forms and blog posts are both common requirements for a website, yet aren’t particularly related to each other. So Mezzanine as a whole is a collection of different Django apps, all packaged together to work seamlessly.

Mezzanine provides its own project template, with settings.py and urls.py modules that configure all of Mezzanine’s apps, which you can (and should) modify per project.

Back to top

Where are all the templates I can modify?

Each of the templates Mezzanine provides can be found in the templates directory of each Django app that Mezzanine is comprised of. Take the time to explore the structure of these, starting with the base template mezzanine/core/templates/base.html (or templates/base.html if stored directly in your project) which is the foundation for the entire site, going more granular as needed.

Once you’re familiar with the templates you’d like to modify, copy them into your project’s templates directory and modify them there. You can also use the collecttemplates command to copy templates over automatically. Run python manage.py collecttemplates --help for more info. Be mindful that this means the copied templates will always be used, rather than the ones stored within Mezzanine itself, which is something to keep in mind if you upgrade to a newer version of Mezzanine.

Back to top

How do I create/install a theme?

Prior to version 1.0, Mezzanine had a set of features for creating and installing themes. These mostly were in place to address handling static files, since at that time Mezzanine was not integrated with Django’s staticfiles app. Mezzanine 1.0 makes full use of staticfiles, and so the theming features were removed since they became redundant.

From that point on, a theme in Mezzanine can be implemented entirely as a standard Django app. Simply create a Django app with templates and static directories, copy the relevant HTML, CSS and JavaScript files into it from Mezzanine that you wish to modify, and then add the theme app’s name to your project’s INSTALLED_APPS setting. Be sure to add the theme to the top of the INSTALLED_APPS list, so that its templates are found before Mezzanine’s versions of the templates.

Have you created a cool theme that you’d like to share with the community? Package your theme up and put it on PyPI and let us know via the mailing list- that way people can automatically install it along with their Mezzanine project.

Back to top

Why does Mezzanine contain its own [FEATURE] instead of using [PACKAGE]?

To be honest you could implement most of Mezzanine’s features by gluing together dozens of smaller, stand-alone, open source Django apps. Several larger Django site-building frameworks take this approach, and it’s a noble one. The downside to this is that a significant portion of time on your project will be spent maintaining the glue between these apps, as their development evolves independently from each other, as well as from your project itself. At best you’ll be able to work with the apps’ developers to ease this evolution, at worst you’ll be stuck hacking work-arounds for incompatibilities between the apps.

One of the core goals of Mezzanine is to avoid this situation, by providing all of the features commonly required by content driven sites, with just the right level of extensibility to customize your Mezzanine powered site as required. By taking this approach, the team behind Mezzanine is in complete control over its components, and can ensure they work together seamlessly.

Back to top

How can I add Mezzanine to an existing Django project?

Mezzanine is a Django project made up of multiple Django apps, and is geared towards being used as the basis for new Django projects, however adding Mezzanine to an existing Django project should be as simple as adding the necessary settings and urlpatterns.

Mezzanine contains a project_template directory, which it uses to create new projects. In here you’ll find the necessary settings.py and urls.py modules, containing the project-level setup for Mezzanine. Of particular note are the following settings:

  • INSTALLED_APPS
  • TEMPLATE_CONTEXT_PROCESSORS
  • MIDDLEWARE_CLASSES
  • PACKAGE_NAME_GRAPPELLI and PACKAGE_NAME_FILEBROWSER (for django-grappelli and django-filebrowser integration)
  • The call to mezzanine.utils.conf.set_dynamic_settings at the very end of the settings.py module.

Back to top

Why are Grappelli and Filebrowser forked?

Grappelli and Filebrowser are fantastic Django apps, and Mezzanine’s admin interface would be much poorer without them. When Mezzanine was first created, both of these apps had packaging issues that went unaddressed for quite some time. Development of Mezzanine moved extremely quickly during its early days, and so the forks grappelli_safe and filebrowser_safe were created to allow Mezzanine to be packaged up and installed in a single step.

Over time the packaging issues were resolved, but Grappelli and Filebrowser took paths that weren’t desired in Mezzanine. They’re only used in Mezzanine for skinning the admin, and providing a generic media library. Extra features that have been added to Grappelli and Filebrowser along the way, haven’t been necessary for Mezzanine.

Over time, small changes have also been made to the grappelli_safe and filebrowser_safe forks, in order to integrate them more closely with Mezzanine. So to this day, the forks are still used as dependencies. They’re stable, and have relatively low activity.

Back to top

What is this Pillow dependency?

Mezzanine makes use of Python Imaging Library (PIL) for generating thumbnails. Having PIL as a dependency that gets automatically installed with Mezzanine has caused issues for some people, due to certain issues with PIL’s own packaging setup.

Pillow is simply a packaging wrapper around PIL that addresses these issues, and ensures PIL is automatically installed correctly when installing Mezzanine. Pillow is only used when PIL is not already installed.

Back to top

Why doesn’t Mezzanine have [FEATURE]?

The best answer to this might be found by searching the mailing list, where many features that aren’t currently in Mezzanine have been thoroughly discussed.

Sometimes the conclusion is that certain features aren’t within the scope of what Mezzanine aims to be. Sometimes they’re great ideas, yet no one has had the time to implement them yet. In the case of the latter, the quickest way to get your feature added is to get working on it yourself.

Communication via the mailing list is key though. Features have been developed and rejected before, simply because they were relatively large in size, and developed in a silo without any feedback from the community. Unfortunately these types of contributions are difficult to accept, since they have the greatest resource requirements in understanding everything involved, without any previous communication.

Back to top

Can I use Cartridge without Mezzanine?

No. Cartridge (an ecommerce app) heavily leverages Mezzanine, and in fact it is implemented as an advanced example of a Mezzanine content type, where each shop category is a page in Mezzanine’s navigation tree. This allows for a very flexible shop structure, where hierarchical categories can be set up to create your shop.

You could very well use Cartridge and Mezzanine to build a pure Cartridge site, without using any of Mezzanine’s features that aren’t relevant to Cartridge. However more often than not, you’ll find that general content pages and forms, will be required to some extent anyway.

Back to top

I don’t know how to code, how can I contribute?

You’re in luck! Programming is by far the most abundant skill contributed to Mezzanine, and subsequently the least needed. There are many ways to contribute without writing any code:

If you don’t have time for any of these things, and still want to contribute back to Mezzanine, donations are always welcome and can be made via Flattr or PayPal on the Mezzanine homepage. Donations help to support the continued development of Mezzanine, and go towards paying for infrastructure, such as hosting for the demo site.

Back to top