1.. _configuration: 2 3############# 4Configuration 5############# 6 7django CMS has a number of settings to configure its behaviour. These should 8be available in your ``settings.py`` file. 9 10 11.. _installed_apps: 12 13****************************** 14The ``INSTALLED_APPS`` setting 15****************************** 16 17The ordering of items in ``INSTALLED_APPS`` matters. Entries for applications with plugins 18should come *after* ``cms``. 19 20 21.. _middleware: 22 23********************************** 24The ``MIDDLEWARE_CLASSES`` setting 25********************************** 26 27.. _ApphookReloadMiddleware: 28 29``cms.middleware.utils.ApphookReloadMiddleware`` 30================================================ 31 32Adding ``ApphookReloadMiddleware`` to the ``MIDDLEWARE_CLASSES`` tuple will enable automatic server 33restarts when changes are made to apphook configurations. It should be placed as near to the top of 34the classes as possible. 35 36.. note:: 37 38 This has been tested and works in many production environments and deployment configurations, 39 but we haven't been able to test it with all possible set-ups. Please file an issue if you 40 discover one where it fails. 41 42 43************************ 44Custom User Requirements 45************************ 46 47.. setting:: AUTH_USER_MODEL 48 49When using a custom user model (i.e. the ``AUTH_USER_MODEL`` Django setting), there are a few 50requirements that must be met. 51 52django CMS expects a user model with at minimum the following fields: ``email``, ``password``, 53``is_active``, ``is_staff``, and ``is_superuser``. Additionally, it should inherit from 54``AbstractBaseUser`` and ``PermissionsMixin`` (or ``AbstractUser``), and must define one field as 55the ``USERNAME_FIELD`` (see Django documentation for more details) and define a ``get_full_name()`` 56method. 57 58The models must also be editable via Django's admin and have an admin class registered. 59 60Additionally, the application in which the model is defined **must** be loaded before ``cms`` in ``INSTALLED_APPS``. 61 62.. note:: 63 64 In most cases, it is better to create a ``UserProfile`` model with a one to one relationship to 65 ``auth.User`` rather than creating a custom user model. Custom user models are only necessary if 66 you intended to alter the default behaviour of the User model, not simply extend it. 67 68 Additionally, if you do intend to use a custom user model, it is generally advisable to do so 69 only at the beginning of a project, before the database is created. 70 71 72***************** 73Required Settings 74***************** 75 76.. setting:: CMS_TEMPLATES 77 78CMS_TEMPLATES 79============= 80 81default 82 ``()`` (Not a valid setting!) 83 84A list of templates you can select for a page. 85 86Example:: 87 88 CMS_TEMPLATES = ( 89 ('base.html', gettext('default')), 90 ('2col.html', gettext('2 Column')), 91 ('3col.html', gettext('3 Column')), 92 ('extra.html', gettext('Some extra fancy template')), 93 ) 94 95.. note:: 96 97 All templates defined in :setting:`CMS_TEMPLATES` **must** contain at least the ``js`` and ``css`` sekizai 98 namespaces. For an example, see :ref:`basic_template`. 99 100.. note:: 101 102 Alternatively you can use :setting:`CMS_TEMPLATES_DIR` to define a directory 103 containing templates for django CMS. 104 105.. warning:: 106 107 django CMS requires some special templates to function correctly. These are 108 provided within ``cms/templates/cms``. You are strongly advised not to use 109 ``cms`` as a directory name for your own project templates. 110 111 112******************* 113Basic Customisation 114******************* 115 116.. setting:: CMS_TEMPLATE_INHERITANCE 117 118CMS_TEMPLATE_INHERITANCE 119======================== 120 121default 122 ``True`` 123 124Enables the inheritance of templates from parent pages. 125 126When enabled, pages' ``Template`` options will include a new default: *Inherit 127from the parent page* (unless the page is a root page). 128 129 130.. setting:: CMS_TEMPLATES_DIR 131 132CMS_TEMPLATES_DIR 133================= 134 135default 136 ``None`` 137 138Instead of explicitly providing a set of templates via :setting:`CMS_TEMPLATES` 139a directory can be provided using this configuration. 140 141`CMS_TEMPLATES_DIR` can be set to the (absolute) path of the templates directory, 142or set to a dictionary with `SITE_ID: template path` items:: 143 144 CMS_TEMPLATES_DIR: { 145 1: '/absolute/path/for/site/1/', 146 2: '/absolute/path/for/site/2/', 147 } 148 149 150The provided directory is scanned and all templates in it are loaded as templates for 151django CMS. 152 153Template loaded and their names can be customised using the templates dir as a 154python module, by creating a ``__init__.py`` file in the templates directory. 155The file contains a single ``TEMPLATES`` dictionary with the list of templates 156as keys and template names as values:::: 157 158 # -*- coding: utf-8 -*- 159 from django.utils.translation import ugettext_lazy as _ 160 TEMPLATES = { 161 'col_two.html': _('Two columns'), 162 'col_three.html': _('Three columns'), 163 } 164 165Being a normal python file, templates labels can be passed through gettext 166for translation. 167 168.. note:: 169 170 As templates are still loaded by the Django template loader, the given 171 directory **must** be reachable by the template loading system. 172 Currently **filesystem** and **app_directory** loader schemas are tested and 173 supported. 174 175 176.. setting:: CMS_PLACEHOLDER_CONF 177 178CMS_PLACEHOLDER_CONF 179==================== 180 181default 182 ``{}`` 183 184Used to configure placeholders. If not given, all plugins will be available in 185all placeholders. 186 187Example:: 188 189 CMS_PLACEHOLDER_CONF = { 190 None: { 191 "plugins": ['TextPlugin'], 192 'excluded_plugins': ['InheritPlugin'], 193 }, 194 'content': { 195 'plugins': ['TextPlugin', 'PicturePlugin'], 196 'text_only_plugins': ['LinkPlugin'], 197 'extra_context': {"width":640}, 198 'name': gettext("Content"), 199 'language_fallback': True, 200 'default_plugins': [ 201 { 202 'plugin_type': 'TextPlugin', 203 'values': { 204 'body':'<p>Lorem ipsum dolor sit amet...</p>', 205 }, 206 }, 207 ], 208 'child_classes': { 209 'TextPlugin': ['PicturePlugin', 'LinkPlugin'], 210 }, 211 'parent_classes': { 212 'LinkPlugin': ['TextPlugin'], 213 }, 214 }, 215 'right-column': { 216 "plugins": ['TeaserPlugin', 'LinkPlugin'], 217 "extra_context": {"width": 280}, 218 'name': gettext("Right Column"), 219 'limits': { 220 'global': 2, 221 'TeaserPlugin': 1, 222 'LinkPlugin': 1, 223 }, 224 'plugin_modules': { 225 'LinkPlugin': 'Extra', 226 }, 227 'plugin_labels': { 228 'LinkPlugin': 'Add a link', 229 }, 230 }, 231 'base.html content': { 232 "plugins": ['TextPlugin', 'PicturePlugin', 'TeaserPlugin'], 233 'inherit': 'content', 234 }, 235 } 236 237.. _placeholder_conf_precedence: 238 239You can combine template names and placeholder names to define 240plugins in a granular fashion, as shown above with ``base.html content``. 241 242Configuration is retrieved in the following order: 243 244* CMS_PLACEHOLDER_CONF['template placeholder'] 245* CMS_PLACEHOLDER_CONF['placeholder'] 246* CMS_PLACEHOLDER_CONF['template'] 247* CMS_PLACEHOLDER_CONF[None] 248 249The first ``CMS_PLACEHOLDER_CONF`` key that matches for the required configuration attribute 250is used. 251 252E.g: given the example above if the ``plugins`` configuration is retrieved for the ``content`` 253placeholder in a page using the ``base.html`` template, the value 254``['TextPlugin', 'PicturePlugin', 'TeaserPlugin']`` will be returned as ``'base.html content'`` 255matches; if the same configuration is retrieved for the ``content`` placeholder in a page using 256``fullwidth.html`` template, the returned value will be ``['TextPlugin', 'PicturePlugin']``. If 257``plugins`` configuration is retrieved for ``sidebar_left`` placeholder, ``['TextPlugin']`` from 258``CMS_PLACEHOLDER_CONF`` key ``None`` will be returned. 259 260 261``plugins`` 262 A list of plugins that can be added to this placeholder. If not supplied, 263 all plugins can be selected. 264 265``text_only_plugins`` 266 A list of additional plugins available only in the TextPlugin, these 267 plugins can't be added directly to this placeholder. 268 269``excluded_plugins`` 270 A list of plugins that will not be added to the given placeholder; this takes precedence 271 over ``plugins`` configuration: if a plugin is present in both lists, it **will not** be 272 available in the placeholder. This is basically a way to **blacklist** a plugin: even if 273 registered, it will not be available in the placeholder. If set on the ``None`` (default) 274 key, the plugins will not be available in any placeholder (except the ``excluded_plugins`` 275 configuration is overridden in more specific ``CMS_PLACEHOLDER_KEYS``. 276 277``extra_context`` 278 Extra context that plugins in this placeholder receive. 279 280``name`` 281 The name displayed in the Django admin. With the gettext stub, the name can 282 be internationalised. 283 284``limits`` 285 Limit the number of plugins that can be placed inside this placeholder. 286 Dictionary keys are plugin names and the values are their respective 287 limits. Special case: ``global`` - Limit the absolute number of plugins in 288 this placeholder regardless of type (takes precedence over the 289 type-specific limits). 290 291``language_fallback`` 292 When ``True``, if the placeholder has no plugin for the current language 293 it falls back to the fallback languages as specified in :setting:`CMS_LANGUAGES`. 294 Defaults to ``True`` since version 3.1. 295 296.. _placeholder_default_plugins: 297 298``default_plugins`` 299 You can specify the list of default plugins which will be automatically 300 added when the placeholder will be created (or rendered). 301 Each element of the list is a dictionary with following keys : 302 303 ``plugin_type`` 304 The plugin type to add to the placeholder 305 Example : ``TextPlugin`` 306 307 ``values`` 308 Dictionary to use for the plugin creation. 309 It depends on the ``plugin_type``. See the documentation of each 310 plugin type to see which parameters are required and available. 311 Example for a text plugin: 312 ``{'body':'<p>Lorem ipsum</p>'}`` 313 Example for a link plugin: 314 ``{'name':'Django-CMS','url':'https://www.django-cms.org'}`` 315 316 ``children`` 317 It is a list of dictionaries to configure default plugins 318 to add as children for the current plugin (it must accepts children). 319 Each dictionary accepts same args than dictionaries of 320 ``default_plugins`` : ``plugin_type``, ``values``, ``children`` 321 (yes, it is recursive). 322 323 Complete example of default_plugins usage:: 324 325 CMS_PLACEHOLDER_CONF = { 326 'content': { 327 'name' : _('Content'), 328 'plugins': ['TextPlugin', 'LinkPlugin'], 329 'default_plugins':[ 330 { 331 'plugin_type':'TextPlugin', 332 'values':{ 333 'body':'<p>Great websites : %(_tag_child_1)s and %(_tag_child_2)s</p>' 334 }, 335 'children':[ 336 { 337 'plugin_type':'LinkPlugin', 338 'values':{ 339 'name':'django', 340 'url':'https://www.djangoproject.com/' 341 }, 342 }, 343 { 344 'plugin_type':'LinkPlugin', 345 'values':{ 346 'name':'django-cms', 347 'url':'https://www.django-cms.org' 348 }, 349 # If using LinkPlugin from djangocms-link which 350 # accepts children, you could add some grandchildren : 351 # 'children' : [ 352 # ... 353 # ] 354 }, 355 ] 356 }, 357 ] 358 } 359 } 360 361``plugin_modules`` 362 A dictionary of plugins and custom module names to group plugin in the 363 toolbar UI. 364 365``plugin_labels`` 366 A dictionary of plugins and custom labels to show in the toolbar UI. 367 368``child_classes`` 369 A dictionary of plugin names with lists describing which plugins may be 370 placed inside each plugin. If not supplied, all plugins can be selected. 371 372``parent_classes`` 373 A dictionary of plugin names with lists describing which plugins may contain 374 each plugin. If not supplied, all plugins can be selected. 375 376``require_parent`` 377 A Boolean indication whether that plugin requires another plugin as parent or 378 not. 379 380``inherit`` 381 Placeholder name or template name + placeholder name which inherit. In the 382 example, the configuration for ``base.html content`` inherits from ``content`` 383 and just overwrites the ``plugins`` setting to allow ``TeaserPlugin``, thus you 384 have not to duplicate the configuration of ``content``. 385 386 387.. setting:: CMS_PLUGIN_CONTEXT_PROCESSORS 388 389CMS_PLUGIN_CONTEXT_PROCESSORS 390============================= 391 392default 393 ``[]`` 394 395A list of plugin context processors. Plugin context processors are callables 396that modify all plugins' context *before* rendering. See 397:doc:`/how_to/custom_plugins` for more information. 398 399 400.. setting:: CMS_PLUGIN_PROCESSORS 401 402CMS_PLUGIN_PROCESSORS 403===================== 404 405default 406 ``[]`` 407 408A list of plugin processors. Plugin processors are callables that modify all 409plugins' output *after* rendering. See :doc:`/how_to/custom_plugins` 410for more information. 411 412.. setting:: CMS_APPHOOKS 413 414 415CMS_APPHOOKS 416============ 417 418default: 419 ``()`` 420 421A list of import paths for :class:`cms.app_base.CMSApp` sub-classes. 422 423By default, apphooks are auto-discovered in applications listed in all 424:setting:`django:INSTALLED_APPS`, by trying to import their ``cms_app`` module. 425 426When ``CMS_APPHOOKS`` is set, auto-discovery is disabled. 427 428Example:: 429 430 CMS_APPHOOKS = ( 431 'myapp.cms_app.MyApp', 432 'otherapp.cms_app.MyFancyApp', 433 'sampleapp.cms_app.SampleApp', 434 ) 435 436 437.. _i18n_l10n_reference: 438 439***************************************************** 440Internationalisation and localisation (I18N and L10N) 441***************************************************** 442 443CMS_LANGUAGES 444============= 445 446.. setting:: CMS_LANGUAGES 447 448 449default 450 Value of :setting:`django:LANGUAGES` converted to this format 451 452Defines the languages available in django CMS. 453 454Example:: 455 456 CMS_LANGUAGES = { 457 1: [ 458 { 459 'code': 'en', 460 'name': gettext('English'), 461 'fallbacks': ['de', 'fr'], 462 'public': True, 463 'hide_untranslated': True, 464 'redirect_on_fallback': False, 465 }, 466 { 467 'code': 'de', 468 'name': gettext('Deutsch'), 469 'fallbacks': ['en', 'fr'], 470 'public': True, 471 }, 472 { 473 'code': 'fr', 474 'name': gettext('French'), 475 'public': False, 476 }, 477 ], 478 2: [ 479 { 480 'code': 'nl', 481 'name': gettext('Dutch'), 482 'public': True, 483 'fallbacks': ['en'], 484 }, 485 ], 486 'default': { 487 'fallbacks': ['en', 'de', 'fr'], 488 'redirect_on_fallback': True, 489 'public': True, 490 'hide_untranslated': False, 491 } 492 } 493 494.. note:: Make sure you only define languages which are also in :setting:`django:LANGUAGES`. 495 496.. warning:: 497 498 Make sure you use **language codes** (`en-us`) and not **locale names** 499 (`en_US`) here and in :setting:`django:LANGUAGES`. 500 Use :ref:`check command <cms-check-command>` to check for correct syntax. 501 502``CMS_LANGUAGES`` has different options where you can define how different 503languages behave, with granular control. 504 505On the first level you can set values for each ``SITE_ID``. In the example 506above we define two sites. The first site has 3 languages (English, German and 507French) and the second site has only Dutch. 508 509The ``default`` node defines default behaviour for all languages. You can 510overwrite the default settings with language-specific properties. For example 511we define ``hide_untranslated`` as ``False`` globally, but the English language 512overwrites this behaviour. 513 514Every language node needs at least a ``code`` and a ``name`` property. ``code`` 515is the ISO 2 code for the language, and ``name`` is the verbose name of the 516language. 517 518.. note:: 519 520 With a ``gettext()`` lambda function you can make language names translatable. 521 To enable this add ``gettext = lambda s: s`` at the beginning of your 522 settings file. 523 524What are the properties a language node can have? 525 526 527.. setting:: code 528 529code 530---- 531String. RFC5646 code of the language. 532 533example 534 ``"en"``. 535 536 537.. note:: Is required for every language. 538 539name 540---- 541String. The verbose name of the language. 542 543.. note:: Is required for every language. 544 545 546.. setting:: public 547 548public 549------ 550Determines whether this language is accessible in the frontend. You may want for example to keep a language private until your content has been fully translated. 551 552type 553 Boolean 554default 555 ``True`` 556 557 558.. setting:: fallbacks 559 560fallbacks 561--------- 562A list of alternative languages, in order of preference, that are to be used if 563a page is not translated yet.. 564 565example 566 ``['de', 'fr']`` 567default 568 ``[]`` 569 570 571.. setting:: hide_untranslated 572 573hide_untranslated 574----------------- 575 576Hides untranslated pages in menus. 577 578When applied to the ``default`` directive, if ``False``, all pages in menus will be listed in all languages, including those 579that don't yet have content in a particular language. If ``True``, untranslated pages will be hidden. 580 581When applied to a particular language, hides that language's pages in menus until translations exist for them. 582 583type 584 Boolean 585default 586 ``True`` 587 588 589.. setting:: redirect_on_fallback 590 591redirect_on_fallback 592-------------------- 593Determines behaviour when the preferred language is not available. If ``True``, 594will redirect to the URL of the same page in the fallback language. If 595``False``, the content will be displayed in the fallback language, but there 596will be no redirect. 597 598Note that this applies to the fallback behaviour of *pages*. Starting for 3.1 *placeholders* 599**will** default to the same behaviour. If you do not want a placeholder to follow a page's 600fallback behaviour, you must set its ``language_fallback`` to ``False`` 601in :setting:`CMS_PLACEHOLDER_CONF`, above. 602 603type 604 Boolean 605default 606 ``True`` 607 608 609Unicode support for automated slugs 610=================================== 611 612If your site has languages which use non-ASCII character sets, :setting:`CMS_UNIHANDECODE_HOST` and 613:setting:`CMS_UNIHANDECODE_VERSION` will allow it to automate slug generation for those languages too. 614 615Support for this is provided by the unihandecode.js project. 616 617 618.. setting:: CMS_UNIHANDECODE_HOST 619 620CMS_UNIHANDECODE_HOST 621--------------------- 622 623default 624 ``None`` 625 626Must be set to the URL where you host your unihandecode.js files. For licensing 627reasons, django CMS does not include unihandecode.js. 628 629If set to ``None``, the default, unihandecode.js is not used. 630 631 632.. note:: 633 634 Unihandecode.js is a rather large library, especially when loading support 635 for Japanese. It is therefore very important that you serve it from a 636 server that supports gzip compression. Further, make sure that those files 637 can be cached by the browser for a very long period. 638 639 640.. setting:: CMS_UNIHANDECODE_VERSION 641 642CMS_UNIHANDECODE_VERSION 643------------------------ 644 645default 646 ``None`` 647 648Must be set to the version number (eg ``'1.0.0'``) you want to use. Together 649with :setting:`CMS_UNIHANDECODE_HOST` this setting is used to build the full 650URLs for the javascript files. URLs are built like this: 651``<CMS_UNIHANDECODE_HOST>-<CMS_UNIHANDECODE_VERSION>.<DECODER>.min.js``. 652 653 654.. setting:: CMS_UNIHANDECODE_DECODERS 655 656CMS_UNIHANDECODE_DECODERS 657------------------------- 658 659default 660 ``['ja', 'zh', 'vn', 'kr', 'diacritic']`` 661 662If you add additional decoders to your :setting:`CMS_UNIHANDECODE_HOST`, you can add them to this setting. 663 664 665.. setting:: CMS_UNIHANDECODE_DEFAULT_DECODER 666 667CMS_UNIHANDECODE_DEFAULT_DECODER 668-------------------------------- 669 670default 671 ``'diacritic'`` 672 673The default decoder to use when unihandecode.js support is enabled, but the 674current language does not provide a specific decoder in 675:setting:`CMS_UNIHANDECODE_DECODERS`. If set to ``None``, failing to find a 676specific decoder will disable unihandecode.js for this language. 677 678 679Example 680------- 681 682Add these to your project's settings:: 683 684 CMS_UNIHANDECODE_HOST = '/static/unihandecode/' 685 CMS_UNIHANDECODE_VERSION = '1.0.0' 686 CMS_UNIHANDECODE_DECODERS = ['ja', 'zh', 'vn', 'kr', 'diacritic'] 687 688Add the library files from `GitHub ojii/unihandecode.js tree/dist <https://github.com/ojii/unihandecode.js/tree/master/dist>`_ to your static folder:: 689 690 project/ 691 static/ 692 unihandecode/ 693 unihandecode-1.0.0.core.min.js 694 unihandecode-1.0.0.diacritic.min.js 695 unihandecode-1.0.0.ja.min.js 696 unihandecode-1.0.0.kr.min.js 697 unihandecode-1.0.0.vn.min.js 698 unihandecode-1.0.0.zh.min.js 699 700More documentation is available on `unihandecode.js' Read the Docs <https://unihandecodejs.readthedocs.io/>`_. 701 702 703************** 704Media Settings 705************** 706 707 708.. setting:: CMS_MEDIA_PATH 709 710CMS_MEDIA_PATH 711============== 712 713default 714 ``cms/`` 715 716The path from :setting:`django:MEDIA_ROOT` to the media files located in ``cms/media/`` 717 718 719.. setting:: CMS_MEDIA_ROOT 720 721CMS_MEDIA_ROOT 722============== 723 724default 725 :setting:`django:MEDIA_ROOT` + :setting:`CMS_MEDIA_PATH` 726 727The path to the media root of the cms media files. 728 729 730.. setting:: CMS_MEDIA_URL 731 732CMS_MEDIA_URL 733============= 734 735default 736 :setting:`django:MEDIA_URL` + :setting:`CMS_MEDIA_PATH` 737 738The location of the media files that are located in ``cms/media/cms/`` 739 740 741.. setting:: CMS_PAGE_MEDIA_PATH 742 743CMS_PAGE_MEDIA_PATH 744=================== 745 746default 747 ``'cms_page_media/'`` 748 749By default, django CMS creates a folder called ``cms_page_media`` in your 750static files folder where all uploaded media files are stored. The media files 751are stored in sub-folders numbered with the id of the page. 752 753You need to ensure that the directory to which it points is writeable by the 754user under which Django will be running. 755 756 757***************** 758Advanced Settings 759***************** 760 761.. setting:: CMS_INTERNAL_IPS 762 763CMS_INTERNAL_IPS 764================ 765 766default 767 ``[]`` 768 769By default ``CMS_INTERNAL_IPS`` is an empty list (``[]``). 770 771If left as an empty list, this setting does not add any restrictions to the 772toolbar. However, if set, the toolbar will only appear for client IP addresses 773that are in this list. 774 775This setting may also be set to an `IpRangeList` from the external package 776``iptools``. This package allows convenient syntax for defining complex IP 777address ranges. 778 779The client IP address is obtained via the :setting:`CMS_REQUEST_IP_RESOLVER` 780in the ``cms.middleware.toolbar.ToolbarMiddleware`` middleware. 781 782 783.. setting:: CMS_REQUEST_IP_RESOLVER 784 785CMS_REQUEST_IP_RESOLVER 786======================= 787 788default 789 '`cms.utils.request_ip_resolvers.default_request_ip_resolver`' 790 791This setting is used system-wide to provide a consistent and plug-able means 792of extracting a client IP address from the HTTP request. The default 793implementation should work for most project architectures, but if not, the 794administrator can provide their own method to handle the project's 795specific circumstances. 796 797The supplied method should accept a single argument `request` and return an 798IP address String. 799 800 801.. setting:: CMS_PERMISSION 802 803CMS_PERMISSION 804============== 805 806default 807 ``False`` 808 809When enabled, 3 new models are provided in Admin: 810 811- Pages global permissions 812- User groups - page 813- Users - page 814 815In the edit-view of the pages you can now assign users to pages and grant them 816permissions. In the global permissions you can set the permissions for users 817globally. 818 819If a user has the right to create new users he can now do so in the "Users - 820page", but he will only see the users he created. The users he created can also 821only inherit the rights he has. So if he only has been granted the right to 822edit a certain page all users he creates can, in turn, only edit this page. 823Naturally he can limit the rights of the users he creates even further, 824allowing them to see only a subset of the pages to which he is allowed access. 825 826 827.. setting:: CMS_RAW_ID_USERS 828 829CMS_RAW_ID_USERS 830================ 831 832default 833 ``False`` 834 835This setting only applies if :setting:`CMS_PERMISSION` is ``True`` 836 837The ``view restrictions`` and ``page permissions`` inlines on the 838:class:`cms.models.Page` admin change forms can cause performance problems 839where there are many thousands of users being put into simple select boxes. If 840set to a positive integer, this setting forces the inlines on that page to use 841standard Django admin raw ID widgets rather than select boxes if the number of 842users in the system is greater than that number, dramatically improving 843performance. 844 845.. note:: Using raw ID fields in combination with ``limit_choices_to`` causes 846 errors due to excessively long URLs if you have many thousands of 847 users (the PKs are all included in the URL of the popup window). For 848 this reason, we only apply this limit if the number of users is 849 relatively small (fewer than 500). If the number of users we need to 850 limit to is greater than that, we use the usual input field instead 851 unless the user is a CMS superuser, in which case we bypass the 852 limit. Unfortunately, this means that non-superusers won't see any 853 benefit from this setting. 854 855.. versionchanged:: 3.2.1: CMS_RAW_ID_USERS also applies to 856 ``GlobalPagePermission`` admin. 857 858 859.. setting:: CMS_PUBLIC_FOR 860 861CMS_PUBLIC_FOR 862============== 863 864default 865 ``all`` 866 867Determines whether pages without any view restrictions are public by default or 868staff only. Possible values are ``all`` and ``staff``. 869 870 871.. setting:: CMS_CACHE_DURATIONS 872 873CMS_CACHE_DURATIONS 874=================== 875 876This dictionary carries the various cache duration settings. 877 878 879``'content'`` 880------------- 881 882default 883 ``60`` 884 885Cache expiration (in seconds) for :ttag:`show_placeholder`, :ttag:`page_url`, :ttag:`placeholder` and :ttag:`static_placeholder` 886template tags. 887 888.. note:: 889 890 This settings was previously called ``CMS_CONTENT_CACHE_DURATION`` 891 892 893``'menus'`` 894----------- 895 896default 897 ``3600`` 898 899Cache expiration (in seconds) for the menu tree. 900 901.. note:: 902 903 This settings was previously called ``MENU_CACHE_DURATION`` 904 905 906``'permissions'`` 907----------------- 908 909default 910 ``3600`` 911 912Cache expiration (in seconds) for view and other permissions. 913 914 915.. setting:: CMS_CACHE_PREFIX 916 917CMS_CACHE_PREFIX 918================ 919 920default 921 ``cms-`` 922 923 924The CMS will prepend the value associated with this key to every cache access 925(set and get). This is useful when you have several django CMS installations, 926and you don't want them to share cache objects. 927 928Example:: 929 930 CMS_CACHE_PREFIX = 'mysite-live' 931 932.. note:: 933 934 Django 1.3 introduced a site-wide cache key prefix. See Django's own docs 935 on :ref:`cache key prefixing <django:cache_key_prefixing>` 936 937 938.. setting:: CMS_PAGE_CACHE 939 940CMS_PAGE_CACHE 941============== 942 943default 944 ``True`` 945 946Should the output of pages be cached? 947Takes the language, and time zone into account. Pages for logged in users are not cached. 948If the toolbar is visible the page is not cached as well. 949 950 951.. setting:: CMS_PLACEHOLDER_CACHE 952 953CMS_PLACEHOLDER_CACHE 954===================== 955 956default 957 ``True`` 958 959Should the output of the various placeholder template tags be cached? 960Takes the current language and time zone into account. If the toolbar is in edit mode or a plugin with ``cache=False`` is 961present the placeholders will not be cached. 962 963 964.. setting:: CMS_PLUGIN_CACHE 965 966CMS_PLUGIN_CACHE 967================ 968 969default 970 ``True`` 971 972Default value of the ``cache`` attribute of plugins. Should plugins be cached by default if not set explicitly? 973 974.. warning:: 975 If you disable the plugin cache be sure to restart the server and clear the cache afterwards. 976 977 978.. setting:: CMS_MAX_PAGE_PUBLISH_REVERSIONS 979 980 981.. setting:: CMS_TOOLBARS 982 983CMS_TOOLBARS 984============ 985 986default 987 ``None`` 988 989If defined, specifies the list of toolbar modifiers to be used to populate the 990toolbar, as import paths. Otherwise, all available toolbars from both the CMS and 991the third-party apps will be loaded. 992 993Example:: 994 995 CMS_TOOLBARS = [ 996 # CMS Toolbars 997 'cms.cms_toolbars.PlaceholderToolbar', 998 'cms.cms_toolbars.BasicToolbar', 999 'cms.cms_toolbars.PageToolbar', 1000 1001 # third-party Toolbar 1002 'aldryn_blog.cms_toolbars.BlogToolbar', 1003 ] 1004 1005.. _unihandecode.js: https://github.com/ojii/unihandecode.js 1006 1007 1008CMS_TOOLBAR_ANONYMOUS_ON 1009======================== 1010 1011default 1012 ``True`` 1013 1014This setting controls if anonymous users can see the CMS toolbar with 1015a login form when ``?edit`` is appended to a URL. The default behaviour 1016is to show the toolbar to anonymous users. 1017 1018 1019CMS_TOOLBAR_HIDE 1020================ 1021 1022default 1023 ``False`` 1024 1025By default, the django CMS toolbar is displayed to logged-in admin users on all pages that use the ``{% cms_toolbar 1026%}`` template tag. Its appearance can be optionally restricted to django CMS pages only (technically, pages that are 1027rendered by a django CMS view). 1028 1029When this is set to ``True``, all other pages will no longer display the toolbar. This includes pages with apphooks 1030applied to them, as they are handled by the other application's views, and not django CMS's. 1031 1032 1033.. versionchanged:: 3.2.1: CMS_APP_NAME has been removed as it's no longer required. 1034 1035CMS_DEFAULT_X_FRAME_OPTIONS 1036=========================== 1037 1038default 1039 ``constants.X_FRAME_OPTIONS_INHERIT`` 1040 1041This setting is the default value for a Page's X Frame Options setting. 1042This should be an integer preferably taken from the ``cms.constants`` e.g. 1043 1044- X_FRAME_OPTIONS_INHERIT 1045- X_FRAME_OPTIONS_ALLOW 1046- X_FRAME_OPTIONS_SAMEORIGIN 1047- X_FRAME_OPTIONS_DENY 1048 1049 1050.. _CMS_TOOLBAR_SIMPLE_STRUCTURE_MODE: 1051 1052CMS_TOOLBAR_SIMPLE_STRUCTURE_MODE 1053================================= 1054 1055default: 1056 ``True`` 1057 1058The new structure board operates by default in "simple" mode. The older mode used absolute 1059positioning. Setting this attribute to ``False`` will allow the absolute positioning used in 1060versions prior to 3.2. This setting will be removed in 3.3. 1061 1062 1063Example:: 1064 1065 CMS_TOOLBAR_SIMPLE_STRUCTURE_MODE = False 1066 1067 1068.. setting:: CMS_PAGE_WIZARD_DEFAULT_TEMPLATE 1069 1070CMS_PAGE_WIZARD_DEFAULT_TEMPLATE 1071================================ 1072 1073default 1074 ``TEMPLATE_INHERITANCE_MAGIC`` 1075 1076This is the path of the template used to create pages in the wizard. It must be 1077one of the templates in :setting:`CMS_TEMPLATES`. 1078 1079.. setting:: CMS_PAGE_WIZARD_CONTENT_PLACEHOLDER 1080 1081CMS_PAGE_WIZARD_CONTENT_PLACEHOLDER 1082=================================== 1083 1084default 1085 None 1086 1087When set to an editable, non-static placeholder that is available on the page 1088template, the CMS page wizards will target the specified placeholder when 1089adding any content supplied in the wizards' "Content" field. If this is left 1090unset, then the content will target the first suitable placeholder found on 1091the page's template. 1092 1093 1094.. setting:: CMS_PAGE_WIZARD_CONTENT_PLUGIN 1095 1096CMS_PAGE_WIZARD_CONTENT_PLUGIN 1097============================== 1098 1099default 1100 ``TextPlugin`` 1101 1102This is the name of the plugin created in the Page Wizard when the "Content" 1103field is filled in. There should be no need to change it, unless you 1104**don't** use ``djangocms-text-ckeditor`` in your project. 1105 1106.. setting:: CMS_PAGE_WIZARD_CONTENT_PLUGIN_BODY 1107 1108CMS_PAGE_WIZARD_CONTENT_PLUGIN_BODY 1109=================================== 1110 1111default 1112 ``body`` 1113 1114This is the name of the body field in the plugin created in the Page Wizard 1115when the "Content" field is filled in. There should be no need to change it, 1116unless you **don't** use ``djangocms-text-ckeditor`` in your project **and** 1117your custom plugin defined in :setting:`CMS_PAGE_WIZARD_CONTENT_PLUGIN` have a 1118body field **different** than ``body``. 1119