2. Introductory Tutorial

This guide assumes your machine meets the requirements outlined in the Installation section of this documentation.

2.1. Configuration and setup

2.1.1. Preparing the environment

Gathering the requirements is a good start, but we now need to give the CMS a Django project to live in, and configure it.

2.1.1.1. Starting your Django project

The following assumes your project will be in ~/workspace/myproject/.

Set up your Django project:

  1. cd ~/workspace
  2. django-admin.py startproject myproject
  3. cd myproject
  4. python manage.py runserver

Open 127.0.0.1:8000 in your browser. You should see a nice “It Worked” message from Django.

it-worked

2.1.1.2. Installing and configuring django CMS in your Django project

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

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

  1. # -*- coding: utf-8 -*-
  2. import os
  3. gettext = lambda s: s
  4. PROJECT_PATH = os.path.abspath(os.path.dirname(__file__))

Add the following apps to your INSTALLED_APPS:

  • 'cms'
  • 'mptt'
  • 'menus'
  • 'south'
  • 'appmedia'

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

  • 'cms.plugins.text'
  • 'cms.plugins.picture'
  • 'cms.plugins.link'
  • 'cms.plugins.file'
  • 'cms.plugins.snippet'
  • 'cms.plugins.googlemap'

If you wish to use the moderation workflow, also add:

  • 'publisher'

Further, make sure you uncomment 'django.contrib.admin'

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

  1. MIDDLEWARE_CLASSES = (
  2.     'django.middleware.common.CommonMiddleware',
  3.     'django.contrib.sessions.middleware.SessionMiddleware',
  4.     'django.middleware.csrf.CsrfViewMiddleware',
  5.     'django.contrib.auth.middleware.AuthenticationMiddleware',
  6.     'django.contrib.messages.middleware.MessageMiddleware',
  7.     'cms.middleware.page.CurrentPageMiddleware',
  8.     'cms.middleware.user.CurrentUserMiddleware',
  9.     'cms.middleware.toolbar.ToolbarMiddleware',
  10.     'cms.middleware.media.PlaceholderMediaMiddleware',
  11. )

You need at least the following TEMPLATE_CONTEXT_PROCESSORS (a default Django settings file will not have any):

  1. TEMPLATE_CONTEXT_PROCESSORS = (
  2.     'django.core.context_processors.auth',
  3.     'django.core.context_processors.i18n',
  4.     'django.core.context_processors.request',
  5.     'django.core.context_processors.media',
  6.     'cms.context_processors.media',
  7. )

Almost there! Point your MEDIA_ROOT to where the static media should live (that is, your images, CSS files, Javascript files…):

  1. MEDIA_ROOT = os.path.join(PROJECT_PATH, "media")
  2. MEDIA_URL = "/media/"
  3. ADMIN_MEDIA_PREFIX="/media/admin/"

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

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

Add at least one template to CMS_TEMPLATES; for example:

  1. CMS_TEMPLATES = (
  2.     ('template_1.html', 'Template One'),
  3.     ('template_2.html', 'Template Two'),
  4. )

We will create the actual template files at a later step, don’t worry about it for now, and simply paste this code in 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. For more details see Creating templates

The django CMS will allow you to edit all languages which Django has built in translations for, this is way too many so we’ll limit it to English for now:

  1. LANGUAGES = [
  2.     ('en', 'English'),
  3. ]

Finally, setup the DATABASES part of the file to reflect your database deployement. 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:

  1. DATABASES = {
  2.     'default': {
  3.         'ENGINE': 'django.db.backends.sqlite3',
  4.         'NAME': os.path.join(PROJECT_DIR, 'database.sqlite'),
  5.     }
  6. }

2.1.2. URL configuration

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

  1. from django.conf.urls.defaults import *
  2. from django.contrib import admin
  3. from django.conf import settings
  5. admin.autodiscover()
  7. urlpatterns = patterns('',
  8.     (r'^admin/', include(admin.site.urls)),
  9.     url(r'^', include('cms.urls')),
  10. )
  12. if settings.DEBUG:
  13.     urlpatterns = patterns('',
  14.         (r'^' + settings.MEDIA_URL.lstrip('/'), include('appmedia.urls')),
  15.     ) + urlpatterns

To have access to app specific media files, use python manage.py symlinkmedia and django-appmedia will do all the work for you.

2.1.3. 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.

2.1.3.1. Fresh install

Run:

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

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

2.1.3.2. Upgrade

Run:

  1. python manage.py syncdb
  2. python manage.py migrate

2.1.4. 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 “It Worked” screen.

it-works-cms

Head over to the admin panel <http://127.0.0.1:8000/admin/&gt; and 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.

2.2. 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:

  1. CMS_TEMPLATES = (
  2.     ('template_1.html', 'Template One'),
  3.     ('template_2.html', 'Template Two'),
  4. )

If you followed this tutorial from the beginning, we already put this code 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:

  1. {% load cms_tags %}
  2. <html>
  3.   <body>
  4.    {% placeholder base_content %}
  5.    {% block base_content%}{% endblock %}
  6.   </body>
  7. </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:

  1. {% extends "base.html" %}
  2. {% load cms_tags %}
  4. {% block base_content %}
  5.   {% placeholder template_1_content %}
  6. {% 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 for your placeholders, to more easily identify them 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”.

2.3. Creating your first CMS page!

That’s it, now the best part: you can start using the CMS! Run your server with python manage.py runserver, then point a web browser to 127.0.0.1:8000/admin/ , 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:

first-admin

2.3.1. Adding a page

Adding a page is as simple as clicking “Pages” in the admin view, then the “add page” button on the top right-hand corner of the screen.

This is where you select which template to use (remember, we created two), as well as pretty obvious things like which language the page is in (used for internationalisation), the page’s title, and the url slug it will use.

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

my-first-page

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

2.3.2. Publishing a page

The list of pages available is a handy way to change a few parameters about your pages:

2.3.2.1. Visibility

By default, pages are “invisible”. To let people access them you should mark them as “published”.

2.3.2.2. Menus

Another option this view lets you tweak is wether or not the page should appear in your site’s navigation (that is, wether there should be a menu entry to reach it or not)

2.3.3. Adding content to a page

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

Ignore most of the interface for now, and click the “view on site” button on the top right-hand corner of the screen. As expected, your page is blank for the time being, since our template is really a minimal one.

Let’s get to it now then!

Press your browser’s back button, so as to see the page’s admin interface. If you followed the tutorial so far, your template (template_1.html) defines two placeholders. The admin interfaces shows you theses placeholders as sub menus:

first-placeholders

Scroll down the “Available plugins” drop-down list. This displays the plugins you added to your INSTALLED_APPS settings. Choose the “text” plugin in the drop-down, then press the “Add” button.

The right part of the plugin area displays a rich text editor (TinyMCE).

Type in whatever you please there, then press the “Save” button.

Go back to your website using the top right-hand “View on site” button. That’s it!

hello-cms-world

2.3.4. 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 build great websites!

2.4. Troubleshooting

If you’ve created a page & you don’t see it in the cms list of the Django admin:

  • Be sure you copied all the media files. Check with firebug and its “net” panel to see if you have any 404s.

If you’re editing a Page in the Django admin, but don’t see an “Add Plugin” button with a dropdown-list of plugins:

  • Be sure your CMS_TEMPLATES setting is correct, the templates specified exist, and they contain at least one {% placeholder %} templatetag.

2.4.1. Template errors

If your placeholder content isn’t displayed when you view a CMS page: change the CMS_MODERATOR variable in settings.py to False. This bug has been recently fixed, so upgrade to the latest version of Django CMS. See: https://github.com/divio/django-cms/issues/issue/430

2.4.2. Javascript errors

If plugins don’t work (e.g.: you add a text plugin, but don’t see the Javascript text editor in the plugin window), you should use a Javascript inspector in your browser to investigate the issue (e.g.: Firebug for Firefox, Web Inspector for Safari or Chrome). The Javascript inspector may report the following errors:

  • TypeError: Result of expression ‘jQuery’ [undefined] is not a function.

If you see this, check the MEDIA_URL variable in your settings.py file. Your webserver (e.g.: Apache) should be configured to serve static media files from this URL.

This error is due to the Django test server running on a different port and URL than the main webserver. In your test environment, you can overcome this issue by adding a CMS_MEDIA_URL variable to your settings.py file, and adding a url rule in urls.py to make the Django development serve the Django CMS files from this location.