Installing django CMS into an existing project

This document assumes you are familiar with Python and Django. It should outline the steps necessary for you to follow the Installing django CMS from scratch.

Requirements

Note

When installing the django CMS using pip, Django, django-mptt django-classy-tags, django-sekizai, south and html5lib will be installed automatically.

Installing

Installing in a virtualenv using pip

pip install django-cms

Installing inside a virtualenv is the preferred way to install any Django installation. This should work on any platform where python in installed. The first step is to create the virtualenv:

#!/bin/sh
sudo pip install --upgrade virtualenv
virtualenv --distribute --no-site-packages env

Note

Since virtualenv v1.10 (2013-07-23) –distribute or –setuptools are the same because the new setuptools has been merged with Distribute. Since virtualenv v1.7 (2011-11-30) –no-site-packages was made the default behavior. By the way, we can create a virtualenv typing in our console only virtualenv env.

You can switch to your virtualenv at the command line by typing:

source env/bin/activate

Next, you can install packages one at a time using pip, but we recommend using a requirements.txt file. The following is an example requirements.txt file that can be used with pip to install django CMS and its dependencies:

# Bare minimum
django-cms>=3.0

# These dependencies are brought in by django CMS, but if you want to
# lock-in their version, specify them
Django>=1.6

South==0.8.4
django-mptt==0.6
django-sekizai==0.7
django-classy-tags==0.5
djangocms-admin-style==0.2.2
html5lib==1.0b1
six==1.3.0

# Optional, recommended packages
Pillow==2.0.0
django-filer==0.9.5
cmsplugin-filer==0.9.5
django-reversion==1.7

Note

In the above list, packages are pinned to specific version as an example; those are not mandatory versions; refer to requirements for any version-specific restriction

for Postgresql you would also add:

psycopg2==2.5

and install libpq-dev (on Debian-based distro)

for MySQL you would also add:

mysql-python==1.2.4

and install libmysqlclient-dev (on Debian-based distro)

One example of a script to create a virtualenv Python environment is as follows:

#!/bin/sh
env/bin/pip install --download-cache=~/.pip-cache -r requirements.txt

Installing globally on Ubuntu

Warning

The instructions here install certain packages, such as Django, South, Pillow and django CMS globally, which is not recommended. We recommend you use virtualenv instead (see above).

If you’re using Ubuntu (tested with 10.10), the following should get you started:

sudo aptitude install python2.6 python-setuptools
sudo easy_install pip
sudo pip install Django==1.5 django-cms south Pillow

Additionally, you need the Python driver for your selected database:

sudo aptitude python-psycopg2

or

sudo aptitude install python-mysql

This will install Django, django CMS, South, Pillow, and your database’s driver globally.

You have now everything that is needed for you to follow the Installing django CMS from scratch.

On Mac OSX

All you need to do is

$ sudo easy_install pip

If you’re using Homebrew you can install pip and virtualenv with the python generic package:

$ sudo brew install python

Then create an environment and work on it instead of install the packages in the system path:

$ virtualenv djangocms-env
$ ./djangocms-env/bin/activate
(djangocms-env)$ pip install Django==1.5 South Django-CMS

Note

You can see the general instructions on how to pip install packages after creating the virtualenv here: Installing in a virtualenv using pip

Databases

We recommend using PostgreSQL or MySQL with django CMS. Installing and maintaining database systems is outside the scope of this documentation, but is very well documented on the systems’ respective websites.

To use django CMS efficiently, we recommend:

  • Creating a separate set of credentials for django CMS.
  • Creating a separate database for django CMS to use.

Configuration and setup

Preparing the environment

The following assumes your django project is in ~/workspace/myproject/myproject.

Installing and configuring django CMS in your django project

Open the file ~/workspace/myproject/myproject/settings.py.

To make your life easier, add the following at the top of the file:

# -*- coding: utf-8 -*-
import os
gettext = lambda s: s
PROJECT_PATH = os.path.split(os.path.abspath(os.path.dirname(__file__)))[0]

Add the following apps to your INSTALLED_APPS. This includes django CMS itself as well as its dependenices and other highly recommended applications/libraries:

'cms',  # django CMS itself
'mptt',  # utilities for implementing a modified pre-order traversal tree
'menus',  # helper for model independent hierarchical website navigation
'south',  # intelligent schema and data migrations
'sekizai',  # for javascript and css management
'djangocms_admin_style',  # for the admin skin. You **must** add 'djangocms_admin_style' in the list **before** 'django.contrib.admin'.
'django.contrib.messages',  # to enable messages framework (see :ref:`Enable messages <enable-messages>`)

Also add any (or all) of the following plugins, depending on your needs:

'djangocms_file',
'djangocms_flash',
'djangocms_googlemap',
'djangocms_inherit',
'djangocms_picture',
'djangocms_teaser',
'djangocms_video',
'djangocms_link',
'djangocms_snippet',
'djangocms_text_ckeditor',  # note this needs to be above the 'cms' entry

Note

Most of the above plugins were previously distributed with django CMS, however, most of them are now located in their own repositories and renamed. Furthermore plugins: 'cms.plugins.text' and 'cms.plugins.twitter' have been removed from the django CMS bundle. Read 3.0 release notes for detailed information.

Warning

Adding the 'djangocms_snippet' plugin is a potential security hazard. For more information, refer to snippet_plugin.

The plugins are described in more detail in chapter Plugins reference. There are even more plugins available on the django CMS extensions page.

In addition, make sure you uncomment (enable) 'django.contrib.admin'

You may also wish to use django-filer and its components with the django CMS plugin instead of the djangocms_file, djangocms_picture, djangocms_teaser and djangocms_video core plugins. In this case you should check the django-filer documentation and django CMS plugin documentation for detailed installation information, and then return to this tutorial.

If you opt for the core plugins you should take care that directory to which the CMS_PAGE_MEDIA_PATH setting points (by default cms_page_media/ relative to MEDIA_ROOT) is writable by the user under which Django will be running. If you have opted for django-filer there is a similar requirement for its configuration.

If you want versioning of your content you should also install django-reversion and add it to INSTALLED_APPS:

  • 'reversion'

You need to add the django CMS middlewares to your MIDDLEWARE_CLASSES at the right position:

MIDDLEWARE_CLASSES = (
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.locale.LocaleMiddleware',
    'django.middleware.doc.XViewMiddleware',
    'django.middleware.common.CommonMiddleware',
    'cms.middleware.user.CurrentUserMiddleware',
    'cms.middleware.page.CurrentPageMiddleware',
    'cms.middleware.toolbar.ToolbarMiddleware',
    'cms.middleware.language.LanguageCookieMiddleware',
)

You need at least the following TEMPLATE_CONTEXT_PROCESSORS:

TEMPLATE_CONTEXT_PROCESSORS = (
    'django.contrib.auth.context_processors.auth',
    'django.contrib.messages.context_processors.messages',
    'django.core.context_processors.i18n',
    'django.core.context_processors.request',
    'django.core.context_processors.media',
    'django.core.context_processors.static',
    'sekizai.context_processors.sekizai',
    'cms.context_processors.cms_settings',
)

Note

This setting will be missing from automatically generated Django settings files, so you will have to add it.

Warning

Be sure to have 'django.contrib.sites' in INSTALLED_APPS and set SITE_ID parameter in your settings: they may be missing from the settings file generated by django-admin depending on your Django version and project template.

Changed in version 3.0.0.

Warning

Django messages framework is now required for the toolbar to work properly.

To enable it you must be check the following settings:

  • INSTALLED_APPS: must contain 'django.contrib.messages'
  • MIDDLEWARE_CLASSES: must contain 'django.contrib.messages.middleware.MessageMiddleware'
  • TEMPLATE_CONTEXT_PROCESSORS: must contain 'django.contrib.messages.context_processors.messages'

Point your STATIC_ROOT to where the static files should live (that is, your images, CSS files, Javascript files, etc.):

STATIC_ROOT = os.path.join(PROJECT_PATH, "static")
STATIC_URL = "/static/"

For uploaded files, you will need to set up the MEDIA_ROOT setting:

MEDIA_ROOT = os.path.join(PROJECT_PATH, "media")
MEDIA_URL = "/media/"

Note

Please make sure both the static and media subfolders exist in your project and are writable.

Now add a little magic to the TEMPLATE_DIRS section of the file:

TEMPLATE_DIRS = (
    # The docs say it should be absolute path: PROJECT_PATH is precisely one.
    # Life is wonderful!
    os.path.join(PROJECT_PATH, "templates"),
)

Add at least one template to CMS_TEMPLATES; for example:

CMS_TEMPLATES = (
    ('template_1.html', 'Template One'),
    ('template_2.html', 'Template Two'),
)

We will create the actual template files at a later step, don’t worry about it for now. Simply paste this code into your settings file.

Note

The templates you define in CMS_TEMPLATES have to exist at runtime and contain at least one {% placeholder <name> %} template tag to be useful for django CMS.

The django CMS allows you to edit all languages for which Django has built in translations. Since these are numerous, we’ll limit it to English for now:

LANGUAGES = [
    ('en', 'English'),
]

Finally, set up the DATABASES part of the file to reflect your database deployment. If you just want to try out things locally, sqlite3 is the easiest database to set up, however it should not be used in production. If you still wish to use it for now, this is what your DATABASES setting should look like:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': os.path.join(PROJECT_PATH, 'database.sqlite'),
    }
}

URL configuration

You need to include the 'cms.urls' urlpatterns at the end of your urlpatterns. We suggest starting with the following ~/workspace/myproject/myproject/urls.py:

from django.conf.urls import include, patterns, url
from django.conf.urls.i18n import i18n_patterns
from django.contrib import admin
from django.conf import settings

admin.autodiscover()

urlpatterns = i18n_patterns('',
    url(r'^admin/', include(admin.site.urls)),
    url(r'^', include('cms.urls')),
)

if settings.DEBUG:
    urlpatterns = patterns('',
    url(r'^media/(?P<path>.*)$', 'django.views.static.serve',
        {'document_root': settings.MEDIA_ROOT, 'show_indexes': True}),
    url(r'', include('django.contrib.staticfiles.urls')),
) + urlpatterns

Creating templates

django CMS uses templates to define how a page should look and what parts of it are editable. Editable areas are called placeholders. These templates are standard Django templates and you may use them as described in the official documentation.

Templates you wish to use on your pages must be declared in the CMS_TEMPLATES setting:

CMS_TEMPLATES = (
    ('template_1.html', 'Template One'),
    ('template_2.html', 'Template Two'),
)

If you have followed this tutorial from the beginning, this code should already be in your settings file.

Now, on with the actual template files!

Fire up your favorite editor and create a file called base.html in a folder called templates in your myproject directory.

Here is a simple example for a base template called base.html:

{% load cms_tags sekizai_tags %}
<html>
  <head>
      <title>{% page_attribute "page_title" %}</title>
      {% render_block "css" %}
  </head>
  <body>
      {% cms_toolbar %}
      {% placeholder base_content %}
      {% block base_content %}{% endblock %}
      {% render_block "js" %}
  </body>
</html>

Now, create a file called template_1.html in the same directory. This will use your base template, and add extra content to it:

{% extends "base.html" %}
{% load cms_tags %}

{% block base_content %}
  {% placeholder template_1_content %}
{% endblock %}

When you set template_1.html as a template on a page you will get two placeholders to put plugins in. One is template_1_content from the page template template_1.html and another is base_content from the extended base.html.

When working with a lot of placeholders, make sure to give descriptive names to your placeholders so you can identify them more easily in the admin panel.

Now, feel free to experiment and make a template_2.html file! If you don’t feel creative, just copy template_1 and name the second placeholder something like “template_2_content”.

Static files handling with sekizai

The django CMS handles media files (css stylesheets and javascript files) required by CMS plugins using django-sekizai. This requires you to define at least two sekizai namespaces in your templates: js and css. You can do so using the render_block template tag from the sekizai_tags template tag library. We highly recommended putting the {% render_block "css" %} tag as the last thing before the closing </head> HTML tag and the {% render_block "js" %} tag as the last thing before the closing </body> HTML tag.

Initial database setup

This command depends on whether you upgrade your installation or do a fresh install. We recommend that you get familiar with the way South works, as it is a very powerful, easy and convenient tool. django CMS uses it extensively.

Fresh install

Run:

python manage.py syncdb --all
python manage.py migrate --fake

The first command will prompt you to create a super user. Choose ‘yes’ and enter appropriate values.

Upgrade

Run:

python manage.py syncdb
python manage.py migrate

Check you did everything right

Now, use the following command to check if you did everything correctly:

python manage.py cms check

Up and running!

That should be it. Restart your development server using python manage.py runserver and point a web browser to 127.0.0.1:8000 : you should get the django CMS “Installation Successful” screen.

it-works-cms

Use the new side-frame-based administration by appending ‘?edit’ to your URL as follows: http://127.0.0.1:8000/?edit. This will reveal a login form.

login-form

Log in with the user you created during the database setup.

To deploy your django CMS project on a production webserver, please refer to the Django documentation.

Creating your first CMS Page!

That’s it. Now the best part: you can start using the CMS! If you haven’t already, run your server with python manage.py runserver, then point a web browser to 127.0.0.1:8000/?edit , and log in using the super user credentials you defined when you ran syncdb earlier.

Once in the admin part of your site, you should see something like the following:

logged-in

Adding a page

Adding a page is as simple as clicking the “Pages...” menu-item in the “example.com” (or similar) menu in the toolbar.

pages-menu-item

This will reveal the new side-frame for administration.

no-pages

Now, click the “add page” button at the top right-hand corner of the side-frame.

basic-page-form

This is a basic form where you complete the title of the new page. The slug field is also required but a sensible value will be completed as you type the page’s title.

Hitting the “Save” button, unsurprisingly, saves the page. It will now display in the list of pages.

my-first-page

You can click the page title in the “page tree” to navigate to the page in the main window.

empty-page

Congratulations! You now have a fully functional django CMS installation!

Publishing a page

There are multiple ways to publish a page including a blue “Publishe page now” button on the right side of the toolbar if the page is not currently published. Other ways include a “Publish page” menu item in the “Page” menu in the toolbar and a publish link inside the “tool-tip” over the colored, round icon in the language column of the page tree. The latter is useful for publishing pages without first navigating to them.

Please review this image of the page-tree in the side-frame maximized with the page menu invoked.

page-options

Template

Choosing a template for your page is as simple as selecting the desired template from the “Templates” sub-menu (see image in publishing a page above). The list of available templates is determined by the CMS_TEMPLATES list as defined in your project’s settings.

Adding content to a page

So far, our page doesn’t do much. Make sure it’s marked as “published” (see above), then click on the page’s “edit” button.

To add content to your page, click the “structure” mode-button in the toolbar. This will reveal all of the page’s available placeholders and allow you to add CMS plugin instances to them.

On any placeholder, click the menu icon on the right side to reveal the list of available plugins. In this case, we’ll choose the Text plugin. Invoking the Text plugin will display your installed WYSIWYG Text editor plugin. Type in some text and press “Save”. When you save the plugin, your plugin will now be displayed “inside” the placeholder as shown in this progession of images.

add-text-plugin

To preview the page, click the “Content” mode button in the toolbar. You can continue editing existing plugins in Content mode simply by double-clicking the content they present. To add new plugins, or to re-arrange existing ones, click back into Structure more. When you’re ready to share your content with the world, press the “Publish page now” button.

That’s it!

Where to go from here

Congratulations, you now have a fully functional CMS! Feel free to play around with the different plugins provided out of the box and to build great websites!

Furthermore you can continue your introduction into django CMS on https://github.com/divio/django-cms-tutorial.