[djangocms] Integrate djangocms with existing projects

This instruction assumes you are using CentOS 7 and MariaDB.
The Official instruction is good and clear, but I prefer to do it in a different order and point out something you should pay attention to.

Install and configure MariaDB

yum install mariadb-server mariadb
systemctl start mariadb
mysql_secure_installation
systemctl enable mariadb

Follow the mysql instruction and finish installation. Then we need to create a database and a user, and assign full privileges for the user to the database.

mysql -u root -p
CREATE DATABASE db_name_here;
CREATE USER 'user_name_here'@'localhost' IDENTIFIED BY 'password_here';
GRANT ALL ON db_name_here.* TO 'user_name_here'@'localhost';

Install mysqlclient

pip install mysqlclient

If you encounter errors like “mysql_config not found”, you can use

yum whatprovides */mysql_config

to find the required package and use

yum install package_name_here

to install that package.

Configure database in settings.py

DATABASES = {
    default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'db_name_here',
        'USER': 'user_name_here',
        'PASSWORD': 'password_here',
        'HOST': '127.0.0.1',
        'PORT': '3306',
    }
}

Install django-cms

pip install django-cms

Install djangocms-text-ckeditor

pip install djangocms-text-ckeditor

Configuring your project for django CMS

Open the settings.py file in your project.

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

# -*- coding: utf-8 -*-
import os
gettext = lambda s: s
BASE_DIR = os.path.dirname(os.path.dirname(__file__))

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

'cms',  # django CMS itself
'treebeard',  # utilities for implementing a tree
'menus',  # helper for model independent hierarchical website navigation
'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>`)
'djangocms_text_ckeditor'

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

MIDDLEWARE_CLASSES = (
    'cms.middleware.utils.ApphookReloadMiddleware',
    '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.common.CommonMiddleware',
    'cms.middleware.user.CurrentUserMiddleware',
    'cms.middleware.page.CurrentPageMiddleware',
    'cms.middleware.toolbar.ToolbarMiddleware',
    'cms.middleware.language.LanguageCookieMiddleware',
)

Configure TEMPLATES

 TEMPLATES = [
         {
         'DIRS': [os.path.join(BASE_DIR, "templates"),],
         'OPTIONS': {
             'context_processors': [
                 # ...
                 'sekizai.context_processors.sekizai',
                 'cms.context_processors.cms_settings',
                 ],
             },
         },
     ]

IMPORTANT

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

Configure static and media

Please make sure both the static and media sub-folders exist in your project and are writeable.

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(BASE_DIR, "static")
STATIC_URL = "/static/"

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

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

Add templates

Add at least one template to CMS_TEMPLATES; for example:

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

Configure language

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

If you have LANGUAGE_CODE = 'en-us' in your settings.py, you need to change en to en-us in the LANGUAGES.

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 import settings
from django.conf.urls import include, url
from django.conf.urls.i18n import i18n_patterns
from django.conf.urls.static import static
from django.contrib import admin

urlpatterns = i18n_patterns('',
    url(r'^admin/', include(admin.site.urls)),
    url(r'^', include('cms.urls')),
) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

Creating templates

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 favourite 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 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 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 HTML tag and the {% render_block “js” %} tag as the last thing before the closing HTML tag.

Migrateion

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.

---

Up to now, the basic integration is done. Below are some points I feel like to mention.

• Where to find plugin and how to use it
  Plugins are being found using google, also check out djangocms marketplace
  Plugins are installed using pip, then added it to your INSTALLED_APPS in settings and python manage.py migrate
• After install ALDRYN BOOTSTRAP 3, migrate shows error
  ALDRYN BOOTSTRAP 3 depends on filer and mptt, so you need to add filer and mptt in your INSTALLED_APPS
• What if you encounter “This can happen if you are inheriting models from an app with migrations (e.g. contrib.auth)” error when doing migration after adding a plugin
  Disable that plugin in your INSTALLED_APPS and then try migration again.
  Enable the plugin and then try migration.
• ALDRYN BOOTSTRAP 3 is not working
  You need to make sure the original Bootstrap 3 is installed and configured for your project

• Encountered error “‘thumbnail’ tag received a bad argument: ‘subject_location’” after adding a image?
  You need to add the following configuration in settings.py, according to official docs

  THUMBNAIL_PROCESSORS = (
  'easy_thumbnails.processors.colorspace',
  'easy_thumbnails.processors.autocrop',
  #'easy_thumbnails.processors.scale_and_crop',
  'filer.thumbnail_processors.scale_and_crop_with_subject_location',
  'easy_thumbnails.processors.filters',
  )
  

• What if your djangocms_admin_style is working with runserver, but NOT working with production server such as Nginx?
  You need to sym link the following two folders:
  ln -s /usr/local/lib/python2.7/site-packages/cms/static/cms /your_project/static
ln -s /usr/local/lib/python2.7/site-packages/djangocms_admin_style/static/djangocms_admin_style/ /your_project/static

-What if you encountered error ValueError: jpeg is required unless explicitly disabled using --disable-jpeg, aborting when installing djangocms-text-ckeditor(It actually installs Pillow as its dependency)
You need to install external lib dependency on CentOS
yum install libtiff-devel libjpeg-devel libzip-devel freetype-devel lcms2-devel libwebp-devel tcl-devel tk-devel