Merge branch 'develop' into feature/help-menu

.github/ISSUE_TEMPLATE/---bug-report.md

@@ -54,3 +54,12 @@ A clear and concise description of what is actually happening.
 Add any other context about the problem such as environment,
 CMS/Python/Django versions, logs etc. here.
 -->
+
+## Do you want to help fix this issue?
+
+<!-- 
+The django CMS project is managed and kept alive by its open source community and is backed by the [django CMS Association](https://www.django-cms.org/en/about-us/). We therefore welcome any help and are grateful if people contribute to the project. Please use 'x' to check the items below.
+-->
+
+* [ ] Yes, I want to help fix this issue and I will join #workgroup-pr-review on [Slack](https://www.django-cms.org/slack) to confirm with the community that a PR is welcome. 
+* [ ] No, I only want to report the issue. 

README.rst

@@ -13,7 +13,9 @@ django CMS
    :target: https://codeclimate.com/github/divio/django-cms
    :alt: Code Climate
 
-Open source enterprise content management system based on the Django framework and backed by the non-profit django CMS Association. `Get involved in the dCA <https://www.django-cms.org/en/contribute/>`_ and `win rewards! <https://www.django-cms.org/en/bounty-program/>`_
+Open source enterprise content management system based on the Django framework and backed by the non-profit django CMS Association. 
+
+Because django CMS is a community-driven project, we welcome everyone to `get involved in the project <https://www.django-cms.org/en/contribute/>`_ and `receive a reward <https://www.django-cms.org/en/bounty-program/>`_ for their contribution. Become part of a fantastic community and help us make django CMS the best open source CMS in the world.  
 
 
 .. ATTENTION::
@@ -51,13 +53,13 @@ See the `Python/Django requirements for the current release version
 <http://docs.django-cms.org/en/latest/#software-version-requirements-and-release-notes>`_ in our documentation.
 
 See the `installation how-to guide for an overview of some other requirements and dependencies of the current release
-<http://docs.django-cms.org/en/latest/how_to/install.html>`_
+<http://docs.django-cms.org/en/latest/how_to/install.html>`_.
 
 *************
 Documentation
 *************
 
-We maintain documentation for several versions of the project. Key versions are:
+Our documentation working group maintains documentation for several versions of the project. Key versions are:
 
 * `stable <http://docs.django-cms.org>`_ (default), for the **current release** version
 * `latest <http://docs.django-cms.org/en/latest/>`_, representing the latest build of the **release-3.4.x branch**
@@ -70,38 +72,32 @@ Our documentation is hosted courtesy of `Read the Docs <https://readthedocs.org>
 
 The dependencies for the docs are compiled by `pip-tools <https://github.com/jazzband/pip-tools>`_.
 
-************************
-Developer Bounty Program
-************************
+*****************************************
+Contribute to the project and win rewards
+*****************************************
 
-Win rewards for creating Pull Requests. Take part in our `developer bounty program <https://www.django-cms.org/en/bounty-program/>`_
+This project owes its existence to the many helpers and supporters. Apart from fame and glory, you can also win prizes for creating Pull Requests. Interested? Then take part in our `developer bounty program <https://www.django-cms.org/en/bounty-program/>`_. 
 
-********
-Tutorial
-********
+***********************************************
+5 step installation tutorial for new developers 
+***********************************************
 
-http://docs.django-cms.org/en/latest/introduction/index.html
+Please check out our `quickstart installation tutorial <https://www.django-cms.org/en/blog/2020/07/07/5-step-django-cms-tutorial-for-new-developers/>`_.
 
-***********
-Quick Start
-***********
+***************
+Getting started
+***************
 
-You can use the `django CMS installer <https://djangocms-installer.readthedocs.io>`_::
+These `tutorials <http://docs.django-cms.org/en/latest/introduction/index.html>`_ take you step-by-step through some key aspects of django CMS.
 
-    $ pip install --upgrade virtualenv
-    $ virtualenv env
-    $ source env/bin/activate
-    (env) $ pip install djangocms-installer
-    (env) $ mkdir myproject && cd myproject
-    (env) $ djangocms -f -p . my_demo
-    (env) $ python manage.py runserver
+***************************
+Test django CMS in our demo 
+***************************
 
-****
-Demo
-****
+The demo platform is kindly provided by Divio, platinum member of the django CMS Association.
 
 .. image:: https://raw.githubusercontent.com/django-cms/django-cms/develop/docs/images/try-with-divio.png
-   :target: https://control.divio.com/demo/get-new/django-cms/
+   :target: https://www.django-cms.org/en/django-cms-demo/
    :alt: Try demo with Divio Cloud
 
 ************
@@ -110,17 +106,18 @@ Getting Help
 
 Please head over to our `Slack channel <https://www.django-cms.org/slack>`_ or our `discourse forum <https://discourse.django-cms.org/>`_ for support.
 
-******************
-Commercial support
-******************
+********************
+Professional support
+********************
+
+Choose from a list of `trusted tech partner <https://www.django-cms.org/en/tech-partners/>`_ of the django CMS Association to get your website project delivered successfully. 
+
+Choose a `trusted web host <https://www.django-cms.org/en/hosting-services/>`_ for your django CMS project and get your website online today.
 
-This project is backed by the `django CMS Association <https://www.django-cms.org/about-us>`_.
-If you need help implementing or hosting django CMS, please contact us:
-info@django-cms.org.
 
-**********************
-django CMS Association
-**********************
+**************************
+The django CMS Association
+**************************
 
 The django CMS Association is a non-profit organization that was founded in 2020 with the goal to drive the success of django CMS, by increasing customer happiness, market share and open-source contributions. We provide infrastructure and guidance for the django CMS project.
 

cms/plugin_base.py

@@ -9,7 +9,6 @@
 from django.core.exceptions import (
     ImproperlyConfigured,
     ObjectDoesNotExist,
-    ValidationError,
 )
 from django.utils.encoding import force_str
 from django.utils.html import escapejs
@@ -163,7 +162,7 @@ def _get_render_template(self, context, instance, placeholder):
             template = None
 
         if not template:
-            raise ValidationError("plugin has no render_template: %s" % self.__class__)
+            raise ImproperlyConfigured("plugin has no render_template: %s" % self.__class__)
         return template
 
     @classmethod

docs/how_to/index.rst

@@ -27,6 +27,7 @@ Using core functionality
 
     Use placeholders outside the CMS <placeholders>
     Serve multiple languages <languages>
+    Create a multi-site set-up <multi-site>
     Work with templates <templates>
     Manage caching <caching>
     Enable frontend editing for Page and Django models <frontend_models>

docs/how_to/multi-site.rst

@@ -0,0 +1,37 @@
+#######################
+Multi-Site Installation
+#######################
+
+For operating multiple websites using the same virtualenv you can use copies of ``manage.py``,
+``wsgi.py`` and different versions of settings and the URL configuration for each site. You can
+use the same database for different websites or, if you want a stricter separation, different
+databases. You can define settings for all sites in a file that is imported in the site-specific
+settings, e. g. ``my_project/base_settings.py``. At the end of these site-specific settings you can
+import local settings, which are not under version control, with SECRET_KEY, DATABASES,
+ALLOWED_HOSTS etc., which may be site-specific or not.
+
+#.  Copy and edit ``wsgi.py`` and ``manage.py``  e. g. to ``wsgi_second_site.py`` and
+    ``manage_second_site.py``: Change the reference to the settings like
+    ``os.environ.setdefault("DJANGO_SETTINGS_MODULE", "my_project.settings_second_site")``, if the
+    settings are in ``my_project/settings_second_site.py``. Do this for each site.
+
+#.  In the site-specific settings import common base settings  in the first line like ``from
+    .base_settings import *`` and define ``SITE_ID``, ``ROOT_URLCONF``, ``CMS_LANGUAGES`` and other
+    settings that should be different on the sites. This way all the items from the imported base
+    settings can be overridden by later definitions:
+
+    ``settings.second_site.py``:
+
+    ::
+
+        from .base_settings import *
+
+        SITE_ID: int = 2
+        ROOT_URLCONF: str = 'my_project.urls_second_site'
+        # other site-specific settings…
+
+        from .settings_local import *
+
+#.  In the web server settings for a site you refer to the site-specific ``wsgi*.py`` like
+    ``wsgi_second_site.py``.
+

docs/introduction/01-install.rst

@@ -2,131 +2,106 @@
 
 .. _install-django-cms-tutorial:
 
-#####################
+######################
 Installing django CMS
-#####################
+######################
 
-We'll get started by setting up our environment.
+The setup is incredibly simple, and in this django CMS tutorial, we’ll take you through
+the first five steps to help get you started.
 
-************
-Requirements
-************
+*****************************
+What you need to get started
+*****************************
 
-django CMS requires Django 1.11 or newer, and Python 2.7 or 3.3 or newer. This tutorial assumes
-you are using Python 3.
+First of all, you don’t need to be a senior developer or have prior experience as a developer
+with Django or Python to create your first django CMS demo website. The added benefit of django CMS, is it’s free.
 
-You can find compatibility table for particular python version `here <https://docs.django-cms.org/en/latest/index.html#software-version-requirements-and-release-notes>`_
+Before we begin the django CMS tutorial, you will need to know that there are several ways to
+install django CMS for free.
 
-************************
-Your working environment
-************************
-
-We're going to assume that you have a reasonably recent version of virtualenv
-installed and that you have some basic familiarity with it.
-
-
-Create and activate a virtual environment
-=========================================
-
-Linux
-::
-
-    python3.6 -m venv env   # Python 2 usage: virtualenv env
-    source env/bin/activate
-
-Windows
-::
-
-    py -m venv env
-    env\Scripts\activate
-
-
-Update pip inside the virtual environment
-=========================================
-
-``pip`` is the Python installer. Make sure yours is up-to-date, as earlier versions can be less reliable::
-
-	pip install --upgrade pip
-
-
-Use the django CMS installer
-============================
+1. You can either set up a project on `Divio Cloud <https://www.django-cms.org/en/blog/2020/07/08/simple-django-cms-installation-with-divio-cloud/>`_, which is fast and useful for people without a technical background and a good starting point to experience the CMS User Interface.
 
+2. As another option, you can set up the project `using docker <https://www.django-cms.org/en/blog/2021/01/19/how-you-spin-up-a-django-cms-project-in-less-than-5-minutes/>`_. It is a good way for a developer locally without an external vendor and we use this option in this django CMS demo.
 
-The `django CMS installer <https://github.com/nephila/djangocms-installer>`_ is
-a helpful script that takes care of setting up a new project.
+3. The last option is to install `django CMS manually by using virtualenv <https://docs.django-cms.org/en/latest/how_to/install.html>`_. This option is a good way for developers that want to install everything by hand to understand better and have full control.
 
-Install it::
+For the sake of this demonstration we will use Option 2, please read on.
 
-    pip install djangocms-installer
-
-This provides you with a new command, ``djangocms``.
-
-Create a new directory to work in, and ``cd`` into it::
-
-    mkdir tutorial-project
-    cd tutorial-project
-
-Run it to create a new Django project called ``mysite``::
-
-    djangocms mysite
+************************
+Setup Docker (Step 1)
+************************
 
-This means:
+Install docker from `here <https://docs.docker.com/get-docker/>`_
 
-* run the django CMS installer
-* call the new project directory ``mysite``
+****************************************
+Run the demo project in docker (Step 2)
+****************************************
 
+Info: The `demo project <https://github.com/django-cms/django-cms-quickstart>`_ is a minimal
+django project with some additional requirements in the requirements.txt.
 
-.. warning::
-   djangocms-installer expects current directory to be empty at this stage, and will check for this,
-   and will warn if it's not. You can get it to skip the check and go ahead anyway using the ``-s``
-   flag; **note that this may overwrite existing files**.
+Open the terminal application on your computer and go to a safe folder (i.e. cd ~/Projects), then:
 
 
-Windows users may need to do a little extra to make sure Python files are associated correctly if that doesn't work right away::
+::
 
-    assoc .py=Python.file
-    ftype Python.File="C:\Users\Username\workspace\demo\env\Scripts\python.exe" "%1" %*
+      git clone git@github.com:django-cms/django-cms-quickstart.git
+      cd django-cms-quickstart
+      docker compose build web
+      docker compose up -d database_default
+      docker compose run web python manage.py migrate
+      docker compose run web python manage.py createsuperuser
+      docker compose up -d
 
-By default, the installer runs in `Batch mode
-<https://djangocms-installer.readthedocs.io/en/latest/usage.html#batch-mode-default>`_, and sets up your new project
-with some default values.
+Open your browser and insert http://localhost:8000/; there you should be invited to login
+and continue with Step 4: create your first page
 
-Later, you may wish to manage some of these by yourself, in which case you need to run it in `Wizard mode
-<https://djangocms-installer.readthedocs.io/en/latest/usage.html#wizard-mode>`_. The default in *Batch mode* is to set
-up an English-only project, which will be sufficient for the purposes of this tutorial. You can of course simply edit
-the new project's ``settings.py`` file at any time to change or add site languages or amend other settings.
 
-Start up the runserver
-======================
+********************************
+Create your first page (Step 3)
+********************************
 
-The installer creates an admin user for you, with these credentials:
+* Once you login you can press Create on the top right.
+* Then you will see a pop-up window where the “New page” is marked blue.
+* Press New Page and select Next.
 
-Username: ``admin``
-Password ``admin``
+.. image:: /introduction/images/create_page_with_django_cms1.png
+   :alt: create a page with django cms
+   :width: 400
+   :align: center
 
-Go to mysite directory
 
-::
+After selecting Next, you will add in your title and some basic text content for the new page,
+click Create.
 
-    cd mysite
+.. image:: /introduction/images/create_page_with_django_cms2.png
+   :alt: create a page with django cms
+   :width: 400
+   :align: center
 
-Start the server using following command
+Here is your newly created page.
 
-::
+*********************************
+Publish your first page (Step 4)
+*********************************
 
-    cd mysite
-    python manage.py runserver
+The page we just created is just a draft and needs to be published once you finish.
+As an editor, only you can see and edit your drafts, other visitors to your site will only see your published pages.
 
-Open http://localhost:8000/ in your browser, where you should be invited to login, and then create
-a new page.
+Press "Publish page now."
 
-.. image:: /introduction/images/welcome.png
-   :alt: a django CMS home page
+.. image:: /introduction/images/django_cms_demo_page.png
+   :alt: publish a page with django cms
    :width: 400
    :align: center
 
-Congratulations, you now have installed a fully functional CMS.
+To edit the page, you can switch back into editing mode using the "Edit" button, and
+return to the published version of the page using the "view published" button.
+
+In the editing mode, you can double-click on the paragraph of the text to change it,
+add formatting, and save it again. Any changes that are made after publishing are saved to a draft and will not be visible until you re-publish.
+
+Congratulations, you now have installed django CMS and created your first page.
 
 If you need to log in at any time, append ``?edit`` to the URL and hit Return. This will enable the
 toolbar, from where you can log in and manage your website.

docs/introduction/index.rst

@@ -1,8 +1,8 @@
 .. _tutorials:
 
-#########
-Tutorials
-#########
+###############
+Getting Started
+###############
 
 The pages in this section of the documentation are aimed at the newcomer to
 django CMS. They're designed to help you get started quickly, and show how