3.1 release notes

django CMS 3.1 has been planned largely as a consolidation release, to build on the progress made in 3.0 and establish a safe, solid base for more ambitious work in the future.

In this release we have tried to maintain maximum backwards-compatibility, particularly for third-party applications, and endeavoured to identify and tidy loose ends in the system wherever possible.

Warning

Upgrading from previous versions

3.1 introduces some changes that require action if you are upgrading from a previous version. Please read Upgrading for django CMS 3.0 to 3.1.

What’s new in 3.1

Switch from MPTT to MP

Since django CMS 2.0 we have relied on MPTT (Modified Preorder Tree Traversal) for efficiently handling tree structures in the database.

In 3.1, Django MPTT has been replaced by django-treebeard, to improve performance and reliability.

Over the years MPTT has proved not to be fast enough for big tree operations (>1000 pages); tree corruption, because of transactional errors, has also been a problem.

django-treebeard uses MP (Materialized Path). MP is more efficient and has more error resistance then MPTT. It should make working with and using django CMS better - faster and reliable.

Other than this, end users should not notice any changes.

Note

User feedback required

We require as much feedback as possible about the performance of django-treebeard in this beta release. Please let us know your experiences with it, especially if you encounter any problems.

Note

Backward incompatible change

While most of the low-level interface is very similar between django-mptt and django-treebeard they are not exactly the same. If any custom code interfaces with plugins and pages tree low level interface, please check the django-treebeard documentation for the updated interface.

Action required

Run manage.py cms fix-mptt before you upgrade.

Developers who use django CMS will need to run the schema and data migrations that are part of this release. Developers of third-party applications that relied on the Django MPTT that shipped with django CMS are advised to update their own applications so that they install it independently.

Dropped support for Django 1.4 and 1.5

Starting from version 3.1, django CMS runs on Django 1.6 and 1.7.

Action required

If you’re still on an earlier version, you will need to install a newer one, and make sure that your third-party applications are also up-to-date with it before attempting to upgrade django CMS.

South is now an optional dependency

As Django South is now required for Django 1.6 only, it’s marked as an optional dependency.

Action required

To install South along with django CMS use pip install django-cms[south].

Migrations moved

Migrations directories have been renamed to conform to the new standard layout:

  • Django 1.7 migrations: in the default cms/migrations and menus/migrations directories
  • South migrations: in the cms/south_migrations and menus/south_migrations directories

Action required

South 1.0.2 or newer is required to handle the new layout correctly, so make sure you have that installed.

If you are upgrading from django CMS 3.0.x running on Django 1.7 you need to remove the old migration path from MIGRATION_MODULES settings.

Structure mode permission

A new *Can use Structure mode* permission has been added.

Without this permission, a non-superuser will no longer have access to structure mode. This makes possible a more strict workflow, in which certain users are abnle to edit content but not structure.

This change includes a data migration that adds the new permission to any staff user or group with cms.change_page permission.

Action required

You may need to adjust these permissions once you have completed migrating your database.

Note that if you have existing users in your database, but are installing django CMS and running its migrations for the first time, you will need to grant them these permissions - they will not acquire them automatically.

Simplified loading of view restrictions in the menu

The system that loads page view restrictions into the menu has been improved, simplifying the queries that are generated, in order to make it faster.

Note

User feedback required

We require as much feedback as possible about the performance of this feature in this beta release. Please let us know your experiences with it, especially if you encounter any problems.

Toolbar API extension

The toolbar API has been extended to permit more powerful use of it in future development, including the use of “clipboard-like” items.

For an example of how this can be used, see the new Blueprint application.

Per-namespace apphook configuration

django CMS provides a new API to define namespaced Apphook configurations.

Aldryn Apphook Config has been created and released as a standard implementation to take advantage of this, but other implementations can be developed.

Improvements to the toolbar user interface

Some minor changes have been implemented to improve the toolbar user interface.

New templatetags

render_model_add_block

The family of render_model templatetags that allow Django developers to make any Django model editable in the frontend has been extended with render_model_add_block, which can offer arbitrary markup as the Edit icon (rather than just an image as previously).

render_plugin_block

Some user interfaces have some plugins hidden from display in edit/preview mode. render_plugin_block provides a way to expose them for editing, and also more generally provides an alternative means of triggering a plugin’s change form.

Drop deprecations

  • cms.context_processor.media has been removed in favor of cms.context_processor.cms_settings, update your settings accordingly;

Upgrading for django CMS 3.0 to 3.1

The two major changes regarding 3.1 are the removal of django-mptt in favor of django-treebeard and the dropped support for Django prior 1.6.

Preliminary steps

Before upgrading, please make sure that you current database is consistent.

To ensure this, run two commands:

  • python manage.py cms delete_orphaned_plugins
  • python manage.py fix_mptt

Settings update

  • Change cms.context_processor.media in cms.context_processor.cms_settings in TEMPLATE_CONTEXT_PROCESSORS;
  • Add treebeard in INSTALLED_APPS and remove mptt if not required by other applications;
  • If using Django 1.7 remove cms and menus from MIGRATION_MODULES to support the new migration layout;
  • If migrating for Django 1.6 and below to Django 1.7, remove south from installed_apps;

Update the database

The migration for mptt to treebeard is handled by the migrations, so just running them will update your database:

  • python manage.py migrate