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'


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 %}
    {% 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.

Filename, size & hash SHA256 hash help File type Python version Upload date
djangocms-spa-0.1.20.tar.gz (13.1 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page