Configuring apps to work with django CMS¶

App Hooks¶

class cms.app_base.CMSApp¶

Base class for creating apphooks. Apphooks live in a file called cms_apps.py. To create an AppHook subclass CMSApp in cms_apps.py

class MyAppHook(CMSApp):
    name = "Problem solver"

_urls¶: list of urlconfs: example: _urls = ["myapp.urls"]

_menus¶: list of menu classes: example: _menus = [MyAppMenu]

get_config(namespace)¶

Returns the apphook configuration instance linked to the given namespace

To be implemented by apphook subclass.

get_config_add_url()¶

Returns the url to add a new apphook configuration instance (usually the model admin add view)

To be implemented by apphook subclass.

get_configs()¶

Returns all the apphook configuration instances.

To be implemented by apphook subclass.

get_menus(page=None, language=None, **kwargs)¶

Returns the menus for the apphook instance, eventually selected according to the given arguments.

By default, it returns the menus assigned to CMSApp._menus.

The method accepts page, language and generic keyword arguments: you can customize this function to return different list of menu classes according to the given arguments.

If no menus are returned, then the user will need to attach menus to pages manually in the admin.

If no page and language are provided, this method must return all the menus used by this apphook. Example:

if page and page.reverse_id == 'page1':
    return [Menu1]
elif page and page.reverse_id == 'page2':
    return [Menu2]
else:
    return [Menu1, Menu2]

Parameters:

page – page the apphook is attached to
language – current site language

Returns:

list of menu classes

get_root_template(page=None, language=None, **kwargs)¶

Added in version 5.1.

Returns the template name used by the apphook’s root view.

Best-effort: walks the urlconfs from get_urls() to locate the pattern matching the empty path and returns template_name from its view class (CBVs) or callback (FBVs that expose it). Returns None for views that compute the template dynamically — override this method to return the template name in that case.

Returns:: template name or None

get_urls(page=None, language=None, **kwargs)¶

Returns the urlconfs for the apphook instance, eventually selected according to the given arguments.

By default, it returns the urls assigned to CMSApp._urls

The method accepts page, language and generic keyword arguments: you can customize this function to return different urlconfs according to the given arguments.

This method must return a non-empty list of urlconfs, even if no argument is passed.

Parameters:

page – page the apphook is attached to
language – current site language

Returns:

list of urlconfs strings

app_config = None¶: configuration model (optional)

app_name = None¶: Gives the system a unique way to refer to the apphook. This enables Django namespaces support (optional)

exclude_permissions = []¶: list of application names to exclude from inheriting CMS permissions

name = None¶: Human-readable name of the apphook (required). This name will be displayed on the admin site.

permissions = True¶: if set to true, apphook inherits permissions from the current page

App Config¶

class cms.app_base.CMSAppConfig(django_app_config)¶

Added in version 4.0.

Base class that all cms app configurations should inherit from.

CMSAppConfig live in a file called cms_config.py.

Apps subclassing CMSAppConfig can set cms_enabled = True for their app config to use django CMS’ wizard functionality. Additional wizzwards are listed in the app config’s cms_wizzards property.

The second functionality that django CMS offers is attaching Model objects to the toolbar. To use this functionality, set list the Model classes in cms_toolbar_enabled_models and have cms_enabled = True

static get_contract(contract_name: str) → type¶

Retrieve a contract implementation from registered CMS extension apps.

Searches through all registered CMS extension applications for a contract that matches the given contract name. A contract is a named interface that allows apps to provide functionality that other apps can use.

This method enables an architecture where apps can query for specific contracts and use the implementation provided by any registered extension app that exports that contract.

Parameters:: contract_name (str) – The name identifier of the contract to retrieve
Returns:: The contract class if found, or None if no matching contract exists
Return type:: type or None
Raises:: None

Example:

# Get a versioning contract implementation
versioning_contract = CMSAppConfig.get_contract('versioning')
if versioning_contract:
    # Use the versioning functionality
    version = versioning_contract.create_version(obj)

App Extensions¶

class cms.app_base.CMSAppExtension¶

Added in version 4.0.

Base class that all cms app extensions should inherit from. App extensions allow apps to offer their functionality to other apps, e.g., as done by djangocms-versioning.

CMSAppExtensions live in a file called cms_config.py.

abstract configure_app(cms_config)¶

Implement this method if the app provides functionality that other apps can use and configure.

This method will be run once for every app that defines an attribute like <app_label>_enabled as True on its cms app config class.

So for example, if app A with label “app_a” implements this method and app B and app C define app_a_enabled = True on their cms config classes, the method app A has defined will run twice, once for app B and once for app C.

Parameters:: cms_config (CMSAppConfig subclass) – the cms config class of the app registering for additional functionality

ready()¶

Override this method to run code after all CMS extensions have been configured.

This method will be run once, even if no cms app config sets its <app_label>_enabled attribute to True