1. Extending the CMS: Examples

We assume your main urls.py looks something like this:

A Plugin is a small bit of content that you can place on your pages.

For our polling app we would like to have a small poll plugin which shows a poll and lets the user vote.

In your poll application’s models.py add the following:

from cms.models import CMSPlugin
class PollPlugin(CMSPlugin):
    poll = models.ForeignKey('polls.Poll', related_name='plugins')
    def __unicode__(self):
      return self.poll.question

Note

django CMS plugins must inherit from cms.models.CMSPlugin (or a subclass thereof) and not models.Model.

Run manage.py syncdb to create the database tables for this model or see to see how to do it using South.

Now create a file cms_plugins.py in the same folder your models.py is in. After having followed the and adding this file your polls app folder should look like this:

polls/
    __init__.py
    cms_plugins.py
    models.py
    tests.py
    views.py

The plugin class is responsible for providing the django CMS with the necessary information to render your Plugin.

Note

All plugin classes must inherit from cms.plugin_base.CMSPluginBase and must register themselves with the cms.plugin_pool.plugin_pool.

You probably noticed the attribute in the above plugin class. In order for our plugin to work, that template must exist and is responsible for rendering the plugin.

The template should look something like this:

<h1>{{ instance.poll.question }}</h1>
<form action="{% url polls.views.vote instance.poll.id %}" method="post">
{% csrf_token %}
{% for choice in instance.poll.choice_set.all %}
    <input type="radio" name="choice" id="choice{{ forloop.counter }}" value="{{ choice.id }}" />
    <label for="choice{{ forloop.counter }}">{{ choice.choice }}</label><br />
{% endfor %}
<input type="submit" value="Vote" />
</form>

Note

We don’t show the errors here, because when submitting the form you’re taken off this page to the actual voting page.

Right now, external apps are statically hooked into the main urls.py. This is not the preferred approach in the django CMS. Ideally you attach your apps to CMS pages.

For that purpose you write a CMSApp. That is just a small class telling the CMS how to include that app.

CMS Apps live in a file called cms_app.py, so go ahead and create it to make your polls app look like this:

polls/
    __init__.py
    cms_app.py
    cms_plugins.py
    models.py
    tests.py
    views.py

Now remove the inclusion of the polls urls in your main urls.py so it looks like this:

from django.conf.urls.defaults import *
from django.contrib import admin
admin.autodiscover()
    (r'^admin/', include(admin.site.urls)),
    (r'^', include('cms.urls')),
)

Now open your admin in your browser and edit a CMS Page. Open the ‘Advanced Settings’ tab and choose ‘Polls App’ for your ‘Application’.

Unfortunately, for these changes to take effect, you will have to restart your server. So do that and afterwards if you navigate to that CMS Page, you will see your polls application.

Now you might have noticed that the menu tree stops at the CMS Page you created in the last step. So let’s create a menu that shows a node for each poll you have active.

For this we need a file called menu.py. Create it and ensure your polls app looks like this:

polls/
    __init__.py
    cms_app.py
    cms_plugins.py
    menu.py
    models.py
    tests.py
    views.py

In your menu.py write:

At this point this menu alone doesn’t do a whole lot. We have to attach it to the Apphook first.

So open your cms_apps.py and write:

from cms.app_base import CMSApp
from cms.apphook_pool import apphook_pool
from polls.menu import PollsMenu
from django.utils.translation import ugettext_lazy as _
class PollsApp(CMSApp):
    name = _("Poll App")
    urls = ["polls.urls"]
    menus = [PollsMenu] # attach a CMSAttachMenu to this apphook.