Add: Basic documentation of new settings

django-cms · fsbraun · Jun 6, 2022 · Feb 9, 2022 · Feb 11, 2022 · Feb 18, 2022
commit f7c4d8f49e22eb3e0afad2d4fe5cd6e8f6daedf7
diff --git a/cms/utils/conf.py b/cms/utils/conf.py
@@ -43,7 +43,6 @@ def wrapper():
 DEFAULTS = {
     'TEMPLATE_INHERITANCE': True,
     'DEFAULT_X_FRAME_OPTIONS': constants.X_FRAME_OPTIONS_INHERIT,
-    'TOOLBAR_SIMPLE_STRUCTURE_MODE': True,
     'PLACEHOLDER_CONF': {},
     'PERMISSION': False,
     # Whether to use raw ID lookups for users when PERMISSION is True

diff --git a/docs/reference/configuration.rst b/docs/reference/configuration.rst
@@ -1044,6 +1044,25 @@ Example::
 This setting adds to the default links of the support menu allowing project or company support links.
 
 
+CMS_COLOR_SCHEME
+================
+
+default
+    ``"light"``
+
+Sets the color scheme for django CMS' editing system. Valid values are ``"light"``,
+``"dark"``, and ``"auto"``. ``"auto"`` will take the user's preference from
+the browser or operating system setting (or light if no preference is available).
+
+CMS_COLOR_SCHEME_TOGGLE
+=======================
+
+default
+    ``False``
+
+If set to ``True`` the toolbar will show a moon or sun icon allowing the user
+to change the current color scheme from light to dark and vice versa.
+
 CMS_TOOLBAR_ANONYMOUS_ON
 ========================
 
@@ -1086,24 +1105,6 @@ This should be an integer preferably taken from the ``cms.constants`` e.g.
 - X_FRAME_OPTIONS_DENY
 
 
-.. _CMS_TOOLBAR_SIMPLE_STRUCTURE_MODE:
-
-CMS_TOOLBAR_SIMPLE_STRUCTURE_MODE
-=================================
-
-default:
-    ``True``
-
-The new structure board operates by default in "simple" mode. The older mode used absolute
-positioning. Setting this attribute to ``False`` will allow the absolute positioning used in
-versions prior to 3.2. This setting will be removed in 3.3.
-
-
-Example::
-
-    CMS_TOOLBAR_SIMPLE_STRUCTURE_MODE = False
-
-
 ..  setting:: CMS_PAGE_WIZARD_DEFAULT_TEMPLATE
 
 CMS_PAGE_WIZARD_DEFAULT_TEMPLATE

diff --git a/docs/topics/colorscheme.rst b/docs/topics/colorscheme.rst
@@ -0,0 +1,63 @@
+.. _colorscheme:
+
+##########################################
+Color schemes (light/dark) with django CMS
+##########################################
+
+.. important::
+
+    These notes about the color scheme apply only to the **django CMS admin and editing
+    interfaces**. The visitor-facing published site is **wholly independent** of this, and the
+    responsibility of the site developer.
+
+    The admin interfaces will only reflect the described behavior if the package
+    ``djangocms-admin-style`` is installed (version XXX or later). If it is not installed the admin
+    interface is managed by your underlying Django installation which usually
+    uses the browser's color scheme.
+
+************************
+Setting the color scheme
+************************
+
+Django CMS' default color scheme is ``"light"``. To change the color scheme use the ``CMS_COLOR_SCHEME``
+setting in your project's ``setting.py``:
+
+``CMS_COLOR_SCHEME = "light"``
+    This is the default appearance and shows the interface with dark text on white background.
+
+``CMS_COLOR_SCHEME = "dark"``
+    This so-called dark mode show light text on dark background.
+
+``CMS_COLOR_SCHEME = "auto"``
+    The auto mode chooses either light or dark color scheme based on the browser or
+    operating system setting of the user.
+
+.. hint::
+
+    If you plan to fix the color scheme to either light or dark, add a corresponding
+    ``data-color-scheme`` attribute to the ``html`` tag in your base template, e.g.
+
+    .. code-block::
+
+        <html data-color-scheme="light">
+
+    This will pin the color scheme early when loading pages and avoid potential
+    flickering if the browser preference differs from the ``CMS_COLOR_SCHEME``
+    setting.
+
+
+.. important::
+
+    Not all plugin admin interfaces might support a dark color scheme, especially
+    if plugin forms contain custom widgets. See XXXX on how to make your widgets
+    compatible with django CMS' color scheme support.
+
+**********************************
+Toggle button for the color scheme
+**********************************
+
+Adding the setting ``CMS_COLOR_SCHEME_TOGGLE = True`` to the project's ``settings.py``
+will add a toggle icon (sun/moon) to the toolbar allowing a user to switch their
+color scheme for their session.
+
+
diff --git a/docs/topics/index.rst b/docs/topics/index.rst
@@ -18,6 +18,7 @@ concerned with explaining *how to do things* than with helping you understand
     i18n
     permissions
     touch
+    colorscheme
     menu_system
     commonly_used_plugins
     searchdocs