1.. _upgrade-to-3.3:
2
3#################
43.3 release notes
5#################
6
7django CMS 3.3 has been planned largely as a consolidation release, to build on the progress made
8in 3.2 and pave the way for the future ones.
9
10The largest major change is dropped support for Django 1.6 and 1.7, and Python 2.6 followed
11by major code cleanup to remove compatibility shims.
12
13.. _whats_new_3.3:
14
15*****************
16What's new in 3.3
17*****************
18
19* Removed support for Django 1.6, 1.7 and python 2.6
20* Changed the default value of CMSPlugin.position to 0 instead of null
21* Refactored the language menu to allow for better integration with many languages
22* Refactored management commands completely for better consistency
23* Fixed "failed to load resource" for favicon on welcome screen
24* Changed behaviour of toolbar CSS classes: ``cms-toolbar-expanded`` class is only added now when toolbar is fully
25  expanded and not at the beginning of the animation. ``cms-toolbar-expanding`` and ``cms-toolbar-collapsing`` classes
26  are added at the beginning of their respective animations.
27* Added unit tests for CMS JavaScript files
28* Added frontend integration tests (written with Casper JS)
29* Removed frontend integration tests (written with Selenium)
30* Added the ability to declare cache expiration periods on a per-plugin basis
31* Improved UI of page tree
32* Improved UI in various minor ways
33* Added a new setting CMS_INTERNAL_IPS for defining a set of IP addresses for which
34  the toolbar will appear for authorized users. If left unset, retains the
35  existing behaviour of allowing toolbar for authorized users at any IP address.
36* Changed behaviour of sideframe; is no longer resizable, opens to 90% of the screen or 100% on
37  small screens.
38* Removed some unnecessary reloads after closing sideframe.
39* Added the ability to make pagetree actions work on currently picked language
40* Removed deprecated CMS_TOOLBAR_SIMPLE_STRUCTURE_MODE setting
41* Introduced the method ``get_cache_expiration`` on CMSPluginBase to be used
42  by plugins for declaring their rendered content's period of validity.
43* Introduced the method ``get_vary_cache_on`` on CMSPluginBase to be used
44  by plugins for declaring ``VARY`` headers.
45* Improved performance of plugin moving; no longer saves all plugins inside the placeholder.
46* Fixed breadcrumbs of recently moved plugin reflecting previous position in
47  the tree
48* Refactored plugin adding logic to no longer create the plugin before the user submits the form.
49* Improved the behaviour of the placeholder cache
50* Improved fix-tree command to sort by position and path when rebuilding positions.
51* Fixed several regressions and tree corruptions on page move.
52* Added new class method on CMSPlugin ``requires_parent_plugin``
53* Fixed behaviour of ``get_child_classes``; now correctly calculates child classes when not
54  configured in the placeholder.
55* Removed internal ``ExtraMenuItems`` tag.
56* Removed internal ``PluginChildClasses`` tag.
57* Modified RenderPlugin tag; no longer renders the ``content.html`` template
58  and instead just returns the results.
59* Added a ``get_cached_template`` method to the ``Toolbar()`` main class to reuse loaded templates per request. It
60  works like Django's cached template loader, but on a request basis.
61* Added a new method ``get_urls()`` on the appbase class to get CMSApp.urls, to allow passing a page object to it.
62* Changed JavaScript linting from JSHint and JSCS to ESLint
63* Fixed a bug when it was possible to drag plugin into clipboard
64* Fixed a bug where clearing clipboard was closing any open modal
65* Added CMS_WIZARD_CONTENT_PLACEHOLDER setting
66* Renamed the CMS_WIZARD_* settings to CMS_PAGE_WIZARD_*
67* Deprecated the old-style wizard-related settings
68* Improved documentation further
69* Improved handling of uninstalled apphooks
70* Fixed toolbar placement when foundation is installed
71* Fixed an issue which could lead to an apphook without a slug
72* Fixed numerous frontend issues
73* Added contribution policies documentation
74* Corrected an issue where someone could see and use the internal placeholder plugin in the structure board
75* Fixed a regression where the first page created was not automatically published
76* Corrected the instructions for using the ``delete-orphaned-plugins`` command
77* Re-pinned django-treebeard to >=4.0.1
78
79.. _backward_incompatible_3.3:
80
81****************
82Upgrading to 3.3
83****************
84
85A database migration is required because the default value of CMSPlugin.position was set to 0 instead of null.
86
87Please make sure that your current database is consistent and in a healthy state,
88and **make a copy of the database before proceeding further.**
89
90Then run::
91
92    python manage.py migrate
93    python manage.py cms fix-tree
94
95
96Deprecation of Old-Style Page Wizard Settings
97=============================================
98
99In this release, we introduce a new naming scheme for the Page Wizard settings
100that better reflects that they effect the CMS's Page Wizards, rather than all
101wizards. This will also allow future settings for different wizards with a
102smaller chance of confusion or naming-collision.
103
104This release simultaneously deprecates the old naming scheme for these settings.
105Support for the old naming scheme will be dropped in version 3.5.0.
106
107Action Required
108---------------
109
110Developers using any of the following settings in their projects should rename
111them as follows at their earliest convenience. ::
112
113    CMS_WIZARD_DEFAULT_TEMPLATE => CMS_PAGE_WIZARD_DEFAULT_TEMPLATE
114    CMS_WIZARD_CONTENT_PLUGIN => CMS_PAGE_WIZARD_CONTENT_PLUGIN
115    CMS_WIZARD_CONTENT_PLUGIN_BODY => CMS_PAGE_WIZARD_CONTENT_PLUGIN_BODY
116    CMS_WIZARD_CONTENT_PLACEHOLDER => CMS_PAGE_WIZARD_CONTENT_PLACEHOLDER
117
118The CMS will accept both-schemes until 3.5.0 when support for the old scheme
119will be dropped. During this transition period, the CMS prefers the new-style
120naming if both schemes are used in a project's settings.
121
122
123*****************************
124Backward incompatible changes
125*****************************
126
127Management commands
128===================
129
130Management commands uses now argparse instead of optparse, following the Django deprecation
131of the latter API.
132
133The commands behaviour has remained untouched.
134
135Detailed changes:
136
137 * commands now use argparse subcommand API which leads to slightly different help output
138   and other internal differences. If you use the commands by using Django's ``call_command``
139   function you will have to adapt the command invocation to reflect this.
140 * some commands have been rename replacing underscores with hyphens for consistency
141 * all arguments are now non-positional. If you use the commands by using Django's
142   ``call_command`` function you will have to adapt the command invocation to reflect this.
143
144
145Signature changes
146=================
147
148The signatures of the toolbar methods ``get_or_create_menu`` have a new kwarg
149``disabled`` *inserted* (not appended). This was done to maintain consistency with
150other, existing toolbar methods. The signatures are now:
151
152 * ``cms.toolbar.items.Menu.get_or_create_menu(key, verbose_name, disabled=False, side=LEFT, position=None)``
153 * ``cms.toolbar.toolbar.CMSToolbar.get_or_create_menu(key, verbose_name=None, disabled=False, side=LEFT, position=None)``
154
155It should only affect developers who use kwargs as positional args.
156