These are some of the most frequently asked questions on the Mezzanine mailing list.
- What do I need to know to use Mezzanine?
- Why does the WYSIWYG editor strip out my custom HTML?
- Why isn’t the homepage a Page object I can edit via the admin?
- Why is Mezzanine a Django project, and not a Django app?
- Where are all the templates I can modify?
- How do I create/install a theme?
- Why does Mezzanine contain its own [FEATURE] instead of using [PACKAGE]?
- How can I add Mezzanine to an existing Django project?
- Why are Grappelli and Filebrowser forked?
- What is this Pillow dependency?
- Why doesn’t Mezzanine have [FEATURE]?
- Can I use Cartridge without Mezzanine?
- I don’t know how to code, how can I contribute?
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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.
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.