How to share capabilities between apps#
New in version 4.0.
To understand how to use the app registration system, lets use an example. Let’s say our
INSTALLED_APPS
include these three apps:
INSTALLED_APPS = [
...
'pink_cms_admin',
'pony_cms_icons',
'blog_posts',
]
The pink_cms_admin
is an app that extends the cms by making apps, that are
accordingly configured, to have a pink admin. To do that, it would define a
pink_cms_admin/cms_config.py
file, which would look like this:
from cms.app_base import CMSAppExtension
from pink_cms_admin import make_admin_pink
class PinkAdminCMSExtension(CMSAppExtension):
def configure_app(self, cms_config):
# Do anything you need to do to each app that wants to be pink
make_admin_pink(cms_config)
The blog_posts
app wants to be pink and wants to have pony icons everywhere. So it
would define blog_posts/cms_config.py
like this:
from cms.app_base import CMSAppConfig
class BlogPostsCMSConfig(CMSAppConfig):
# To enable functionality define an attribute like <app_label>_enabled
# and set it to True
pink_cms_admin_enabled = True
pony_cms_icons_enabled = True
# pony_cms_icons also has additional settings. These are defined here.
pony_cms_icons_pony_colours = ['purple', 'pink']
pony_cms_icons_ponies_with_wings = True
The pony_cms_icons app lets other apps have pony icons everywhere, but also wants to
have a pink admin. So it would define pony_cms_icons/cms_config.py
like this:
from django.core.exceptions import ImproperlyConfigured
from cms.app_base import CMSAppConfig, CMSAppExtension
from pony_cms_icons import add_pony_icons
class PonyIconsCMSConfig(CMSAppConfig):
pink_cms_admin_enabled = True
class PonyIconsCMSExtension(CMSAppExtension):
def configure_app(self, cms_config):
# Do anything you need to do to each app that wants to have
# pony icons here
# As pony icons defines additional settings, you will also need to check
# for any required settings here
pony_colours = getattr(cms_config, 'pony_cms_icons_pony_colours', None)
if not pony_colours:
raise ImproperlyConfigured(
"Apps that use pony_cms_icons, must define pony_cms_icons_pony_colours")
ponies_with_wings = getattr(cms_config, 'pony_cms_icons_ponies_with_wings', False)
add_pony_icons(cms_config.django_app, pony_colours, ponies_with_wings)
The configure_app()
method, as is already apparent,
takes one param - cms_config
. cms_config
is an instance of an app’s
CMSAppConfig
class. In addition to that you can also access the
django app object (as defined in the app’s apps.py) by using cms_config.app_config
.
In this way you can access attributes that django provides (such as label
,
verbose_name
etc.).
The configure_app()
method is run once for every
django cms app that declares a feature as enabled.
If an app asks for a feature of another app that is not installed this feature is simply
ignored. This in turn implies that you cannot assume that the feature you request in a
CMSAppConfig
is also available. Therefore, make sure your app’s
code also runs without that feature or check if your providing app is present in your
CMSAppConfig
and raise an ImproperlyConfigured
exception if
it is missing.