2.4 release notes

    Upgrading from previous versions

    2.4 introduces some changes that require action if you are upgrading from a previous version.

    You will need to read the sections Migrations overhaul and below.

    Django CMS 2.4 introduces Django 1.5 support.

    In django CMS 2.4 we dropped support for Django 1.3 and Python 2.5. Django 1.4 and Python 2.6 are now the minimum required versions.

    Migrations overhaul

    In version 2.4, migrations have been completely rewritten to address issues with newer South releases.

    To ease the upgrading process, all the migrations for the cms application have been consolidated into a single migration file, 0001_initial.py.

    • migration 0001 is a real migration, that gets you to the same point migrations 0001-0036 used to
    • the migrations 0002 to 0036 inclusive still exist, but are now all dummy migrations
    • migrations 0037 and later are new migrations

    How this affects you

    If you’re starting with a new installation, you don’t need to worry about this. Don’t even bother reading this section; it’s for upgraders.

    If you’re using version 2.3.2 or newer, you don’t need to worry about this either.

    If you’re using version 2.3.1 or older, you will need to run a two-step process.

    First, you’ll need to upgrade to 2.3.3, to bring your migration history up-to-date with the new scheme. Then you’ll need to perform the migrations for 2.4.

    For the two-step upgrade process do the following in your project main directory:

    Added delete orphaned plugins command

    Added a management command for deleting orphaned plugins from the database.

    The command can be run with:

    1. manage.py cms delete_orphaned_plugins

    Please read before using.

    Added a check command

    Added a management command to check your configuration and environment.

    To use this command, simply run:

    This replaces the old at-runtime checks.

    CMS_MODERATOR

    Has been removed since it is no longer in use. From 2.4 onward, all pages exist in a public and draft version. Users with the publish_page permission can publish changes to the public site.

    Management command required

    To bring a previous version of your site’s database up-to-date, you’ll need to run manage.py cms moderator on. Never run this command without first checking for orphaned plugins, using the cms list plugins command. If it reports problems, run manage.py cms delete_orphaned_plugins. Running cms moderator with orphaned plugins will fail and leave bad data in your database. See cms list and .

    Added Fix MPTT Management command

    Added a management command for fixing MPTT tree data.

    The command can be run with:

    1. manage.py cms fix-mptt

    We removed the MultilingualMiddleware. This removed rather some unattractive monkey-patching of the reverse() function as well. As a benefit we now support localisation of URLs and apphook URLs with standard Django helpers.

    For django 1.4 more information can be found here:

    If you are still running django 1.3 you are able to achieve the same functionality with django-i18nurl. It is a backport of the new functionality in django 1.4 and can be found here:

    What you need to do:

    • Remove cms.middleware.multilingual.MultilingualURLMiddleware from your settings.

    • Be sure django.middleware.locale.LocaleMiddleware is in your settings, and that it comes after the SessionMiddleware.

    • Be sure that the cms.urls is included in a i18n_patterns:

    • Change your url and reverse calls to language namespaces. We now support the django way of calling other language urls either via {% language %} template tag or via activate("de") function call in views.

      Before:

      1. {% url "de:myview" %}

      After:

      1. {% load i18n %}{% language "de" %}
      2. {% url "myview_name" %}

    • reverse urls now return the language prefix as well. So maybe there is some code that adds language prefixes. Remove this code.

    Added LanguageCookieMiddleware

    To fix the behaviour of django to determine the language every time from new, when you visit / on a page, this middleware saves the current language in a cookie with every response.

    To enable this middleware add the following to your MIDDLEWARE_CLASSES setting:

    cms.middleware.language.LanguageCookieMiddleware

    CMS_LANGUAGES

    CMS_LANGUAGES has be overhauled. It is no longer a list of tuples like the LANGUAGES settings.

    An example explains more than thousand words:

    For more details on what all the parameters mean please refer to the docs.

    The following settings are not needed any more and have been removed:

    • CMS_HIDE_UNTRANSLATED
    • CMS_LANGUAGE_FALLBACK
    • CMS_LANGUAGE_CONF
    • CMS_SITE_LANGUAGES

    CMS_FLAT_URLS

    Was marked deprecated in 2.3 and has now been removed.

    Plugins in Plugins

    We added the ability to have plugins in plugins. Until now only the TextPlugin supported this. For demonstration purposes we created a MultiColumn Plugin. The possibilities for this are endless. Imagine: StylePlugin, TablePlugin, GalleryPlugin etc.

    The column plugin can be found here:

    At the moment the limitation is that plugins in plugins is only editable in the frontend.

    Here is the MultiColumn Plugin as an example:

    1. class MultiColumnPlugin(CMSPluginBase):
    2.     model = MultiColumns
    3.     name = _("Multi Columns")
    4.     render_template = "cms/plugins/multi_column.html"
    5.     allow_children = True
    6.     child_classes = ["ColumnPlugin"]

    There are 2 new properties for plugins:

    allow_children

    Boolean If set to True it allows adding Plugins.

    child_classes

    List A List of Plugin Classes that can be added to this plugin. If not provided you can add all plugins that are available in this placeholder.

    How to render your child plugins in the template

    We introduce a new template tag in the cms_tags called {% render_plugin %} Here is an example of how the MultiColumn plugin uses it:

    1. {% load cms_tags %}
    2. <div class="multicolumn">
    3. {% for plugin in instance.child_plugins %}
    4.     {% render_plugin plugin %}
    5. {% endfor %}
    6. </div>

    As you can see the children are accessible via the plugins children attribute.

    New way to handle django CMS settings

    If you have code that needs to access django CMS settings (settings prefixed with CMS_ or PLACEHOLDER_) you would have used for example . This will no longer guarantee to return sane values, instead you should use cms.utils.conf.get_cms_setting which takes the name of the setting without the CMS_ prefix as argument and returns the setting.

    Example of old, now deprecated style:

    Should be replaced with the new API:

    1. from cms.utils.conf import get_cms_setting
    3. get_cms_setting('TEMPLATES')
    4. get_cms_setting('PLACEHOLDER_FRONTEND_EDITING')

    This release adds the cms.constants module which will hold generic django CMS constant values. Currently it only contains TEMPLATE_INHERITANCE_MAGIC which used to live in cms.conf.global_settings but was moved to the new cms.constants module in the settings overhaul mentioned above.

    django-reversion integration changes

    integration has changed. Because of huge databases after some time we introduce some changes to the way revisions are handled for pages.

    1. Only publish revisions are saved. All other revisions are deleted when you publish a page.
    2. By default only the latest 25 publish revisions are kept. You can change this behaviour with the new CMS_MAX_PAGE_PUBLISH_REVERSIONS setting.

    Changes to the show_sub_menu template tag

    the show_sub_menu has received two new parameters. The first stays the same and is still: how many levels of menu should be displayed.

    The second: root_level (default=None), specifies at what level, if any, the menu should root at. For example, if root_level is 0 the menu will start at that level regardless of what level the current page is on.

    The third argument: nephews (default=100), specifies how many levels of nephews (children of siblings) are shown.

    PlaceholderAdmin support i18n

    If you use placeholders in other apps or models we now support more than one language out of the box. If you just use the PlaceholderAdmin it will display language tabs like the cms. If you use django-hvad it uses the hvad language tabs.

    Added CMS_RAW_ID_USERS

    If you have a lot of users (500+) you can set this setting to a number after which admin User fields are displayed in a raw Id field. This improves performance a lot in the admin as it has not to load all the users into the html.

    New minimum requirements for dependencies

    • Django 1.3 and Python 2.5 are no longer supported.
    • will be removed in version 3.0. A bug-fix makes this redundant as every non-managed URL will behave like this.