Skip to main content

Run your django CMS project as a single-page application (SPA)

Project description

Run your django CMS project as a single-page application (SPA). This package provides a REST-API that returns all page contents serialized as JSON. A couple of helpers and base classes can be used to create API endpoints for custom views. djangocms-spa was build to use it together with a concrete implementation:


Install djangocms_spa:

pip install djangocms-spa

Add it to your INSTALLED_APPS:


Add the Locale middleware (if it isn’t already):


Set your default template:


The settings variable DJANGOCMS_SPA_TEMPLATES expects a dictionary of templates. It should cover all templates of CMS_TEMPLATES and use the path as key. The frontend component name and a list of partials (e.g. static placeholders) are valid options.

    'pages/content.html': {
        'frontend_component_name': 'content',
        'partials': ['menu', 'meta', 'footer']
    'pages/content_with_section_navigation.html': {
        'frontend_component_name': 'content-with-section-navigation',
        'partials': ['menu', 'meta', 'footer']

Configure your custom partials:

    'menu': 'djangocms_spa.partial_callbacks.get_cms_menu_data_dict'

Render the initial app version (commit hash) in the template so your client can check it:

{% load app_version_tags %}
{% app_version %}


Your plugins don’t need a rendering template but a render_spa method that returns a dictionary. To have a clean structure, we usually put the context inside a content key of the dictionary:

class TextPlugin(JsonOnlyPluginBase):
    name = _('Text')
    model = TextPluginModel
    frontend_component_name = 'cmp-text'
    def render_spa(self, request, context, instance):
        context = super(TextPlugin, self).render_spa(request, context, instance)
        context['content']['text']. = instance.text
        return context



CACHE_TIMEOUT (default: 60 * 10)

If you are using a caching backend, the API responses are cached.

DJANGOCMS_SPA_DEFAULT_TEMPLATE (default: 'index.html')

DEFAULT_LIST_CONTAINER_NAME (default: 'object_list')

The list view uses this key to group its data.


This hook allows you to post process the data of a CMS page by defining a module path.


This hook allows you to post process the data of a placeholder by defining a module path.


We call global page elements that are used to render a template “partial”. The contents of a partial do not change from one page to another. In a django CMS project partials are implemented as static placeholders. Because we don’t render any HTML templates, we need to configure the static placeholders for each template in DJANGOCMS_SPA_TEMPLATES as partials. To edit your placeholder and static placeholder data, you need to render both in the edit mode:

{% if request.toolbar.edit_mode_active %}
    {% placeholder "main" %}
    {% static_placeholder "footer" %}
{% endif %}

Usually there are other parts like the menu or any other template tag that work pretty much like static placeholders. Because we don’t have a template that allows us to render template tags, we need to have a custom implementation for those needs. We decided to use a callback approach that allows developers to bring custom data into the partial list. Define your callbacks in DJANGOCMS_SPA_PARTIAL_CALLBACKS by adding a partial key and the module path of the callback function. You will find an example in djangocms_spa/ Your function should return a dictionary like this:

    'type': 'generic',
    'content': {
        'my_var': 1


Tools used in rendering this package:


Project details

Download files

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

Source Distribution

djangocms-spa-0.1.28.tar.gz (20.4 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page