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.
Upgrading from previous versions
3.1 introduces some changes that require action if you are upgrading from a previous version. Please read Upgrading django CMS 3.0 to 3.1 for a step-by-step guide to the process of upgrading from 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.
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.
User feedback required
We require as much feedback as possible about the performance of django-treebeard in this release. Please let us know your experiences with it, especially if you encounter any problems.
Backward incompatible change
While most of the low-level interface is very similar between
django-treebeard they are not exactly the same. If any custom code needs to make use of the
low-level interfaces of the page or plugins tree, please see the django-treebeard
documentation for information
on how to use equivalent calls in
Handling plugin data migrations
Please check Plugin data migrations for information on how to create migrations compatible with django CMS 3.0 and 3.1
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.
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.
To install South along with django CMS use
pip install django-cms[south].
Migrations directories have been renamed to conform to the new standard layout:
- Django 1.7 migrations: in the default
- South migrations: in the
Plugins migrations moving process¶
Core plugins are being changeed to follow the new convention for the migration modules, starting with djangocms_text_ckeditor 2.5 released together with django CMS 3.1.
Check the readme file of each plugin when upgrading to know the actions required.
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 able to edit content but not structure.
This change includes a data migration that adds the new permission to any staff user or group with
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.
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 Aldryn Blueprint application.
Per-namespace apphook configuration¶
django CMS provides a new API to define namespaced Apphook configurations.
Aldryn Apphooks 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. The old Draft/Live switch has been replaced to achieve a more clear distinction between page states, and Edit and Save as draft buttons are now available in the toolbar to control the page editing workflow.
Placeholder language fallback default to True¶
True by default.
Plugin table naming¶
Old-style plugin table names (for example,
cmsplugin_<plugin name> are no longer
supported. Relevant code has been removed.
Any plugin table name must be migrated to the standard (
<application name>_<table name> layout.
Upgrading django CMS 3.0 to 3.1¶
Before upgrading, please make sure that your current database is consistent and in a healthy state.
To ensure this, run two commands:
python manage.py cms delete_orphaned_plugins
python manage.py cms fix-mptt
Make a copy of the database before proceeding further.
INSTALLED_APPS, and remove
mpttif not required by other applications.
- If using Django 1.7 remove
MIGRATION_MODULESto support the new migration layout.
- If migrating from Django 1.6 and below to Django 1.7, remove
- Eventually set
CMS_PLACEHOLDER_CONFif you do not want language fallback behavior for placeholders.
Update the database¶
Rename the custom plugin table names, either by applying relevant migrations (if any) or renaming the tables manually;
The migration for MPTT to
django-treebeardis handled by the django CMS migrations, thus apply migrations to update your database:
python manage.py migrate