Navigation

Mezzanine provides a central system for defining settings within
your project and applications that can then be edited by admin users.
The package mezzanine.conf contains the models for storing
editable settings in the database as well as the functions for
registering and loading these settings throughout your project.

Settings are defined by creating a module named defaults.py inside
one or more of the applications defined in your project’s
settings.INSTALLED_APPS setting. Inside your defaults.py module
you then call the function mezzanine.conf.register_setting for
each setting you want to define which takes several keyword arguments:

name: The name of the setting.

label: The verbose name of the setting for the admin.

description: The description of the setting.

editable: If True, the setting will be editable via the admin.

default: The default value of the setting.

choices: A list of choices the user can select from when the
setting is editable.

append: If registering an existing setting, the default value
given will be appended to the current.

translatable: If django-modeltranslation is activated, this
setting will store and display values on a per-language basis.

Note

For settings registered with editable as True, currently only
strings, integers/floats and boolean values are supported for the
default value.

For example suppose we had a authors application and we wanted to
create a setting that controls the number of books displayed per author
page, we would define the following in authors.defaults:

frommezzanine.confimportregister_settingregister_setting(name="AUTHORS_BOOKS_PER_PAGE",label="Authors books per page",description="The number of books to show per author page.",editable=True,default=10,)

Note

If you are using Django 1.7 or greater and your app is included in your
INSTALLED_APPS as an AppConfig (eg authors.apps.MyCrazyConfig), Mezzanine
won’t import your defaults.py automatically. Instead you must import it
manually in your AppConfig’s ready() method.

Mezzanine provides a settings object via mezzanine.conf.settings in a
similar way to Django’s django.conf.settings. This settings object
contains each of the settings registered above using their names as
attributes. Continuing on from our previous example, suppose we have a view
for photos:

When defining editable settings, care should be taken when considering
where in your project the setting will be used. For example if a setting
is used in a urlpattern or the creation of a model class it would
only be read when your site is first loaded, and therefore having it
change at a later point by an admin user would not have any effect without
reloading your entire project. In the snippet above, since the settings is
being read within a view, the value of the setting being accessed is
loaded each time the view is run. This ensures that if the value of the
setting has been changed by an admin user it will be reflected on
the website.

Note

It’s also important to realize that with any settings flagged as
editable, defining a value for these in your project’s
settings.py will only serve to provide their default values.
Once editable settings are modified via the admin, their values
stored in the database will always be used.

Mezzanine’s settings object integrates with Django’s settings object in a
couple of ways.

Firstly it’s possible to override the default value for any setting defined
using mezzanine.conf.register_setting by adding its name and value as
a regular setting to your project’s settings module. This is especially useful
when any of your project’s INSTALLED_APPS (including Mezzanine
itself) register settings that aren’t editable and you want to override
these settings without modifying the application that registered them.

Secondly it’s possible to access any of the settings defined by Django or
your project’s settings module via Mezzanine’s settings object in the same
way you would use Django’s settings object. This allows for a single access
point for all settings regardless of how they are defined.

A string containing the value year, month, or day, which controls the granularity of the date portion in the URL for each blog post. Eg: year will define URLs in the format /blog/yyyy/slug/, while day will define URLs with the format /blog/yyyy/mm/dd/slug/. An empty string means the URLs will only use the slug, and not contain any portion of the date at all.

Mezzanine’s caching uses a technique know as mint caching. This is where the requested expiry for a cache entry is stored with the cache entry in cache, and the real expiry used has the CACHE_SET_DELAY added to it. Then on a cache get, the store expiry is checked, and if it has passed, the cache entry is set again, and no entry is returned. This tries to ensure that cache misses never occur, and if many clients were to get a cache miss at once, only one would actually need to re-generated the cache entry.

A sequence of fields that will be injected into Mezzanine’s (or any library’s) models. Each item in the sequence is a four item sequence. The first two items are the dotted path to the model and its field name to be added, and the dotted path to the field class to use for the field. The third and fourth items are a sequence of positional args and a dictionary of keyword args, to use when creating the field instance. When specifying the field class, the path django.models.db. can be omitted for regular Django model fields.

Extra field types for the forms app. Should contain a sequence of three-item sequences, each containing the ID, dotted import path for the field class, and field name, for each custom field type. The ID is simply a numeric constant for the field, but cannot be a value already used, so choose a high number such as 100 or greater to avoid conflicts.

A sequence mapping host names to themes, allowing different templates to be served per HTTP host. Each item in the sequence is a two item sequence, containing a host such as othersite.example.com, and the name of an importable Python package for the theme. If the host is matched for a request, the templates directory inside the theme package will be first searched when loading templates.

Models that subclass Ownable and use the OwnableAdmin have their admin change-list records filtered down to records owned by the current user. This setting contains a sequence of models in the format app_label.object_name, that when subclassing Ownable, will still show all records in the admin change-list interface, regardless of the current user.

If True, pages with login_required checked will still be listed in menus and search results, for unauthenticated users. Regardless of this setting, when an unauthenticated user accesses a page with login_required checked, they’ll be redirected to the login page.

A sequence of templates used by the page_menu template tag. Each item in the sequence is a three item sequence, containing a unique ID for the template, a label for the template, and the template path. These templates are then available for selection when editing which menus a page should appear in. Note that if a menu template is used that doesn’t appear in this setting, all pages will appear in it.

A sequence of IDs from the PAGE_MENU_TEMPLATES setting that defines the default menu templates selected when creating new pages. By default all menu templates are selected. Set this setting to an empty sequence to have no templates selected by default.

When content is saved in a Rich Text (WYSIWYG) field, unsafe HTML tags and attributes are stripped from the content to protect against staff members intentionally adding code that could be used to cause problems, such as changing their account to a super-user with full access to the system.

This setting allows you to change the level of filtering that occurs. Setting it to low will allow certain extra tags to be permitted, such as those required for embedding video. While these tags are not the main candidates for users adding malicious code, they are still considered dangerous and could potentially be mis-used by a particularly technical user, and so are filtered out when the filtering level is set to high.

Setting the filtering level to no filtering, will disable all filtering, and allow any code to be entered by staff members, including script tags.

Sequence of models that will be provided by default as choices in the search form. Each model should be in the format app_label.model_name. Only models that subclass mezzanine.core.models.Displayable should be used.

A URL prefix for mounting all of Mezzanine’s urlpatterns under. When using this, you’ll also need to manually apply it to your project’s root urls.py module. The root urls.py module provided by Mezzanine’s mezzanine-project command contains an example of this towards its end.

Dotted Python path to the callable for converting strings into URL slugs. Defaults to mezzanine.utils.urls.slugify_unicode which allows for non-ascii URLs. Change to django.template.defaultfilters.slugify to use Django’s slugify function, or something of your own if required.

Sequence of dotted Python paths to callable functions used for checking posted content (such as forms or comments) is spam. Each function should accept three arguments: the request object, the form object, and the URL that was posted from. Defaults to mezzanine.utils.views.is_spam_akismet which will use the http://akismet.com spam filtering service when the AKISMET_API_KEY setting is configured.

Note: Once you change this from the default, you’ll need to configure each of the oAuth consumer/access key/secret settings. Please refer to http://dev.twitter.com for more information on creating an application and acquiring these settings.