How to create apphooks¶

The basics of apphook creation¶

To create an apphook, create a cms_apps.py file in your application.

The file needs to contain a CMSApp sub-class. For example:

from cms.app_base import CMSApp
from cms.apphook_pool import apphook_pool

@apphook_pool.register
class MyApphook(CMSApp):
    app_name = "myapp"  # must match the application namespace
    name = "My Apphook"

    def get_urls(self, page=None, language=None, **kwargs):
        return ["myapp.urls"] # replace this with the path to your application's URLs module

re_path(r'^myapp/', include('myapp.urls', app_name='myapp'))

from django.urls import re_path
from myapp.views import SomeListView, SomeDetailView

class MyApphook(CMSApp):
    # ...
    def get_urls(self, page=None, language=None, **kwargs):
        return [
            re_path(r'^$', SomeListView.as_view()),
            re_path(r'^(?P<slug>[\w-]+)/?$', SomeDetailView.as_view()),
        ]

Using an apphook¶

Once your apphook has been set up and loaded, you’ll now be able to select the Application that’s hooked into that page from its Advanced settings.

The apphook attaches all of the apphooked application’s URLs to the page; its root URL will be the page’s own URL, and any lower-level URLs will be on the same URL path.

So, given an application with the urls.py for the views index_view and archive_view:

urlpatterns = [
    re_path(r'^$', index_view),
    re_path(r'^archive/$', archive_view),
]

attached to a page whose URL path is /hello/world/, the views will be exposed as follows:

• index_view at /hello/world/

• archive_view at /hello/world/archive/

Managing apphooks¶

manage.py cms uninstall apphooks MyApphook MyOtherApphook

manage.py cms list apphooks

Adding menus to apphooks¶

Generally, it is recommended to allow the user to control whether a menu is attached to a page (See Attach Menus for more on these menus). However, an apphook can be made to do this automatically if required. It will behave just as if the menu had been attached to the page using its Advanced settings).

Menus can be added to an apphook using the get_menus() method. On the basis of the example above:

# [...]
from myapp.cms_menus import MyAppMenu

class MyApphook(CMSApp):
    # [...]
    def get_menus(self, page=None, language=None, **kwargs):
        return [MyAppMenu]

The menus returned in the get_menus() method need to return a list of nodes, in their get_nodes() methods. Attach Menus has more information on creating menu classes that generate nodes.

You can return multiple menu classes; all will be attached to the same page:

def get_menus(self, page=None, language=None, **kwargs):
    return [MyAppMenu, CategoryMenu]

Managing permissions on apphooks¶

By default the content represented by an apphook has the same permissions set as the page it is assigned to. So if for example a page requires the user to be logged in, then the attached apphook and all its URLs will have the same requirements.

To disable this behaviour set permissions = False on your apphook:

class MyApphook(CMSApp):
    [...]
    permissions = False

If you still want some of your views to use the CMS’s permission checks you can enable them via a decorator, cms.utils.decorators.cms_perms

Here is a simple example:

from cms.utils.decorators import cms_perms

@cms_perms
def my_view(request, **kw):
    ...

If you make your own permission checks in your application, then use the exclude_permissions property of the apphook:

class MyApphook(CMSApp):
    [...]
    permissions = True
    exclude_permissions = ["some_nested_app"]

where you provide the name of the application in question

Automatically restart server on apphook changes¶

As mentioned above, whenever you:

• add or remove an apphook

• change the slug of a page containing an apphook

• change the slug of a page with a descendant with an apphook

The CMS the server will reload its URL caches. It does this by listening for the signal cms.signals.urls_need_reloading.

Apphooks and placeholder template tags¶

It’s important to understand that while an apphooked application takes over the CMS page at that location completely, depending on how the application’s templates extend other templates, a django CMS {% placeholder %} template tag may be invoked - but will not work.

{% static_placeholder %} tags on the other hand are not page-specific and will function normally.