Skip to main content

Library to auto setup apphooks

Project description

Join the Gitter chat Latest PyPI version Python versions Latest Travis CI build status Test coverage Code Climate License

Utility function to auto setup apphooks on project startup.

Supported Django versions:

  • Django 1.11 to 2.2

Supported django CMS versions:

  • django CMS 3.5, 3.6, 3.7


The mixin included in this utility allows to automatically add an Apphook to a django CMS project on the first access to the website.

This is intended for use by the django CMS application developers by extending their own CMSApp classes.

This behavior simplify the initial setup of a project and lower the barrier for the end user.

The setup function included here does the following:

  • Check if the Apphook is already added to a CMS page
  • If it is, it skips any further step
  • If not:
    • Creates the home page (if not present)
    • Creates a sub page of the home
    • Adds the application Apphook to it

In case the application uses aldryn-apphooks-config, a Apphook Config instance is created and added to the application page together with the Apphook.


To avoid issues with AldrynSearch during the creation of pages, the url of the pages is faked; this is normally not an issues as the pages will be reindexed whenever the content is updated.


This utility can be used by extending the CMSApp class, adding the auto_setup attribute with relevant configuration options and triggering setup at the end of

class App4(AutoCMSAppMixin, CMSConfigApp):
    name = _('App4')
    urls = ['sample_app_4.urls']
    app_name = 'app4'
    app_config = App4Config
    # djangocms-apphook-setup attribute
    auto_setup = {
        'enabled': True,
        'home title': 'home title',
        'page title': 'page 4 title',
        'namespace': 'namespace',
        'config_fields': {'random_option': True},
        'config_translated_fields': {'app_title': 'app title', 'object_name': 'name'},
        'sites': True,

# trigger djangocms-apphook-setup function

Customizing ApphookConfig instances creation

While config_fields and config_translated_fields should cover most use cases when it comes to ApphookConfig instances creation, you may need more control over the process.

For this, it’s possible to override AutoCMSAppMixin._create_config and AutoCMSAppMixin._create_config_translation.

Default implementation:

def _create_config(cls):
    return cls.app_config.objects.create(
        namespace=cls.auto_setup['namespace'], **cls.auto_setup['config_fields']

def _create_config_translation(cls, config, lang):
    config.set_current_language(lang, initialize=True)
    for field, data in cls.auto_setup['config_translated_fields'].items():
        setattr(config, field, data)

You can completely redefine the methods, provided you return an ApphookConfig instance in _create_config.

Configuration options

The behavior of the setup function can be customized by setting the following keys in the auto_setup attribute:

  • enabled: If True the setup is invoked; a good option is to use a setting to control this to allow application users to disable the behavior (default: True)
  • home title: Title of the home page if created by the setup function; this must be set in the application CMSApp, otherwise the setup function will exit with a warning.
  • page title: Title of the page created by the setup function; this must be set in the application CMSApp, otherwise the setup function will exit with a warning.
  • namespace: Application instance name used when attaching the Apphook; this must be set in the application CMSApp if an app_name is defined, otherwise the setup function will exit with a warning.
  • config_fields: Fields used when creating the ApphookConfigModel instance; use this attribute for non-translated fields.
  • config_translated_fields: Fields used when creating the ApphookConfigModel instance; use this attribute for translated fields (currently only django-parler is supported).
  • sites: List of site ids for which to create the pages; if set to True (the default value) pages will be created for all sites. A single apphook config is created for all the sites; instance is created only on first page creation.

Notes on testing

As this utility works by triggering setup function at import time, extra steps must be taken in the tests to unload the modules between the tests (this is only needed when testing the setup).

Example cleanup to be included in setUp method:

def setUp(self):
    super(SetupAppBaseTest, self).setUp()
    from cms.apphook_pool import apphook_pool

    delete = [
    for module in delete:
        if module in sys.modules:
            del sys.modules[module]
    MyApphoolConfigModel.cmsapp = None



  • Nothing yet

0.4.1 (2019-12-22)

  • Fix classifiers

0.4.0 (2019-12-22)

  • Add Django 2.2 support
  • Add django CMS 3.6, 3.7 support
  • Drop Django < 1.11 support
  • Drop django CMS < 3.6 support
  • Fix monkey-patch not applied consistently

0.3.0 (2018-01-15)

  • Add support for multisite setups
  • Add Django 1.11 support
  • Add django CMS 3.5 support

0.2.0 (2016-12-04)

  • Add support for multisite setups
  • Add Django 1.9, 1.10 support
  • Add django CMS 3.4 support

0.1.2 (2015-12-22)

  • Monekypatch aldryn_search index to avoid errors

0.1.1 (2015-11-02)

  • Easier extension of ApphookConfig creation

0.1.0 (2015-10-24)

  • First experimental release

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for djangocms-apphook-setup, version 0.4.1
Filename, size File type Python version Upload date Hashes
Filename, size djangocms_apphook_setup-0.4.1-py2.py3-none-any.whl (7.4 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size djangocms-apphook-setup-0.4.1.tar.gz (9.0 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page