# Workgroup django CMS v4

###### tags: `workgroup`

Workgroup leader: Andrew

Workgroup members: Narender, Jacob, Mike, Francesco, Paul, Florian, Vinit, Dimitri, Simon, Vel, Gabriel, Mark, Ashis, Andrew, Fabian

* If you want to join this work group, please reach out to Fabian ([e-mail]) or Nicolai ([e-mail]) and they will guide you through the process.
* If you have questions about version 4, please message the team in the dedicated Slack channel #workgroup-django-cms-4-0 (See slack invite below)

# Workgroup onboarding

## Resources

### Documentation
- [django CMS 4.1 code](https://github.com/django-cms/django-cms/tree/develop-4)
- [django CMS 4.1 docs work in progress](https://django-cms-docs.readthedocs.io/en/latest/)
- [django CMS 4.1 compatible packages](https://django-cms-docs.readthedocs.io/en/latest/explanation/commonly_used_plugins.html)
- [django CMS 4.0 compatible packages](https://github.com/django-cms/django-cms/blob/release/4.0.x/docs/4.0.x/packages.md)
- [List of open source packages](https://docs.google.com/spreadsheets/d/1kANl66x5CLoL3ZcL613Qz1sClfnDvh9jk8csrh9cSQM/edit#gid=397686173) - please fill in information
- [djangocms-versioning](https://github.com/django-cms/djangocms-versioning/blob/master/docs/index.rst)
- [djangocms-moderation](https://github.com/django-cms/djangocms-moderation/blob/master/docs/index.rst)

### Quick start projects
- [django-cms-quickstart 4.1 compatible](https://github.com/django-cms/django-cms-quickstart/tree/support/cms-4.1.x)
- Marks example: https://github.com/marksweb/django-cms-4

### Visual clips
- [django CMS 4.0 with djangocms-versioning preview video](https://www.youtube.com/watch?v=72SficeO9N4) by Andrew

### Get involved
- [slack invite](https://www.django-cms.org/slack), channel #workgroup-django-cms-4-0
- [calendar invite](https://calendar.google.com/event?action=TEMPLATE&tmeid=MjBmOTQ1OXNzNTFlMWwwb2Y1OTFsczBkYnRfMjAyMTA2MTBUMTUwMDAwWiBuaWNvbGFpQGRqYW5nby1jbXMub3Jn&tmsrc=nicolai%40django-cms.org&scp=ALL) to bi-weekly meeting, Fridays 2:00pm GMT/BST -
- [Project board (tasks)](https://github.com/django-cms/django-cms/projects/2) - please bookmark!

## Meetings

### Template
Attendees:
-

**Action Points**
To be ideally completed by the next meeting

### Friday, March 17th, 2023
Attendees:
- Mark, Fabian

**Agenda**

Demo new module `cms.admin.utils` allowing to make some v4 improvements better usable by third-party apps (Blog, Alias, etc...):
* Move **changelist action buttons** introduced in versioning to a new `cms.admin.utils`: Regular items: View button (takes you to the view endpoint), Settings button (takes you the the change admin)
* Provide an (optional) **burger menu** for any apps to use with the changelist actions (app-specific actions, like view usage)
* `GrouperModelAdmin` to allow for simple **admin of grouper-content models**, esp. with extra grouping fields:
* Shows missing content elements in the changelist offering the user to create them
* Common change view („settings“) for grouper and content instances (a.g., name of alias and category in the same form)
* Well-known language tabs if language is an extra grouping field
* Available w/o versioning being installed but automatically integrating with versioning
* Potential crystallisation core for a more consistent admin editing experience in the future.

**Action Points**
To be ideally completed by the next meeting
- [ ] Postponed: How-to add versioning docs (**Mike**, based on aldryn-blog and others, postponed until April)

### Friday, March 3rd, 2023
Attendees:
- Mike, Mark, Fabian

**Action Points**
To be ideally completed by the next meeting
- [ ] Postponed: How-to add versioning docs (**Mike**, based on aldryn-blog and others, postponed until April)

**Agenda**
- Update on documentation (new permanent agenda item)
- Feature proposal for the core: Basic grouper - content management as an admin mixin
- Deprecated features
- Review PR and issues.

### Friday, February 17, 2023
Attendees:
- Mike, Andrew, Fabian

**Action Points**
- [X] Align with Nicolai on how and when to develop the DCA website as a demo and reference (**Fabian**)
- [ ] How-to add versioning docs (**Mike**, based on aldryn-blog and others) -> postpone for 4 weeks

**Feeback release candidate**
* Apphooks on the preview endpoint (https://github.com/django-cms/django-cms/pull/7496)
* Ability to delete Pages/PageContents (https://github.com/django-cms/djangocms-versioning/pull/320)
* Ability to edit slug for drafts (https://github.com/django-cms/django-cms/issues/7506)
* Some simple naming/usability improvements (https://github.com/django-cms/djangocms-versioning/pull/317)
* Resuable status indicators (https://github.com/django-cms/djangocms-versioning/pull/319)

**Update on Priorities**
* Djangocms-blog: Nephila have a v4 compatible version running locally
* Djangocms-blog: Roadblock is djangocms-blog's dependency on aldryn-apphooks-config

**Action Points**
To be ideally completed by the next meeting

### Friday, February 3, 2023

Attendees:
- Mike, Fabian

**Action Points**
To be ideally completed by the next meeting

- [ ] Get transifex set up for localization of version-locking (**Fabian** created PR)
- [ ] How-to add versioning docs (**Mike**, based on aldryn-blog and others)

**Priorities**
1. django CMS v4 blog (nothing to see yet): Mario calls Iacopo
2. django CMS v4 version-locking
3. django CMS v4 moderation (django 4 support, remove aldryn-forms as test dependence, missing icons ...)
4. django CMS Alias usability

### Friday, January 20, 2023
Attendees:

**Agenda**
- Who knows translators (and if so for which language)?
- https://django-cms-docs.readthedocs.io/en/latest/explanation/commonly_used_plugins.html
- FIL-owned packages: e.g., djangocms-version-locking

**Action Points**
To be ideally completed by the next meeting
- [ ] Get transifex set up for localization of version-locking (**Fabian**)
- [ ] How-to add versioning docs (**Mike**, based on aldryn-blog and others)

### Friday, January 6, 2023
Attendees:
- Mike, Mark, Fabian

**Agenda**
- Testing the RC (who, how)
- Documentation
- Getting release candidates for versioning and moderation.
- Localization

**Action Points**
To be ideally completed by the next meeting

- [X] Missing Version objects - create a management command to recover (**Fabian** to review)
- [x] Get transifex set up for localization of versioning, moderation, alias (**Fabian**)
- [ ] Get transifex set up for localization of version-locking (**Fabian**)
- [ ] How-to add versioning docs (**Mike**, based on aldryn-blog and others)

### Friday, December 9
Attendees:
- Andrew, Vinit, Fabian

**Agenda**
- Review action points from last meeting
- Next steps monkey patching
- Start of release process for 4.1.0rc1
- django-cms 4.1.0rc1
- djangocms-versioning 2.0.0rc1
- djangocms-alias 1.1.0
- djangocms-text-ckeditor 5.2
- Communication strategy: Keep rc1 "low-key" until documentation is in a reasonable state.
- Next meeting date: tbd

**Action Points**
To be ideally completed by the next meeting
- [X] [djangocms-text-ckeditor - PR-631 ](https://github.com/django-cms/djangocms-text-ckeditor/pull/631)(**Andrew** to review)
- [X] No-more-monkey-patching-PRs - [PR-7446](https://github.com/django-cms/django-cms/pull/7446) and [PR-300](https://github.com/django-cms/djangocms-versioning/pull/300) (**Andrew** to review)
- [ ] Missing Version objects - create a management command to recover (**Fabian** to review)
- [X] Create a rc1 version after merging #7446 and #300 (**Fabian**)

### Friday 25th November 2022
Attendees:
- Andrew, Mark, Fabian

**Agenda**
- Review action points from last meeting
- Discuss immediate merges
- Next steps monkey patching

**Action Points**
To be ideally completed by the next meeting
- [ ] djangocms-text-ckeditor - PR-629 (**Andrew** to review)
- [x] **Fabian** to follow up Andrew with respect to removing monkey patching the core in stead of marking patch hooks.
- [x] Create `support/4.0.x` branch for djangocms-versioning
- [x] Start merging reviewed PR into `master` after branching off 4.0.x
- [x] [Docstrings](https://github.com/django-cms/django-cms/pull/7436)
- [x] [Performance imrovement for title cache](https://github.com/django-cms/django-cms/pull/7177)
- [x] [Support for user models without user name](https://github.com/django-cms/djangocms-versioning/pull/293)
- [x] Change TitleExtension to PageContentExtension ([here in core](https://github.com/django-cms/django-cms/pull/7369) and [here in djangocms-versioning](https://github.com/django-cms/djangocms-versioning/pull/291))
- [x] Reintroduce page content state indicators in page tree ([here in core](https://github.com/django-cms/django-cms/pull/7426) and [here in djangocms-versioning](https://github.com/django-cms/djangocms-versioning/pull/295))

### Friday 11th November 2022
**Attendees:**
- Mike, Luis, Fabian, Andrew

**Agenda**

- Update on engagement with Fidelity and review this document - https://docs.google.com/document/d/1nzhqiaElR2l1Lq__TcssN2FxxcoWTw04YJ0bVRBC4ys/edit#heading=h.w4t5iuviy3dt
- Documentation status and why that’ll lead to a PR for develop-4
- Go through Fabian’s list of issues

**Action Points**
To be ideally completed by the next meeting
- [x] Mike to go back to Joel with Fabian's document and request a contact
- [x] **Fabian and Andrew** to agree on legacy `cms.pluginmodel.Plugin.copy_plugin` method.
- [ ] djangocms-text-ckeditor - PR-629 (**Andrew** to review)
- [ ] django-cms Title Extension PR (**Mark**) to be merged once Joel provided a contact
- [ ] **Fabian** to propose marking monkey patched functions/methods in django CMS core to make contributors aware of potential side-effects
- [x] **All**: Feedback to status indicator PR: https://github.com/django-cms/django-cms/pull/7426 and https://github.com/django-cms/djangocms-versioning/pull/295 (directly to Fabian)

### Friday 28th October 2022
Attendees:

- Mike, Luis, Fabian, Mark, Andrew, Vinit

**Action Points**
To be ideally completed by the next meeting
- [X] django-cms Move plugins PR-7394 (**Andrew** et al to review)
- [X] django-cms Page tree PR (**Andrew** et al to review)
- [X] Fabian: Discuss the documentation updates for the tutorials and other parts of the docs.

### Friday 14th October 2022
Attendees:

- Mike, Luis, Fabian, Mark, Andrew

**Action Points**
To be ideally completed by the next meeting
- [x] Documentation PR for 4.0 (Review by **Fabian and Mark**)
- [x] Documentation Template for release noted (**Fabian** Volunteered)
- [x] django-cms Title Extension Update document (**Mark**)
- [x] **Mike** to speak to potential sponsors / collaborators

### Friday 8th July 2022
Attendees:

- Mike, Andrew

Items discussed
- Documentation for v4
- Using the new projects beta in GitHub

### Friday 27th May 2022
Attendees:

- Andrew, Mario

Updates
- Added more cms-config documentation
- Release / branching strategy now implemented

Items discussed
- django-cms 4.0, 4.1 and 4.2 LTS release. Need to propose something to the Tech committee.

### Friday 13th May 2022
Attendees:

- Fabian, Mark, Mike, Andrew

Items discussed
- Enterprise and SME's using the CMS versions, need to map the process from both angles.
- Action to take away: Collaborate on the process design, how can changes be taken in etc.

## Introduction

### What is v4.0?

django CMS 4.0 is the next major release and a milestone for the django CMS project. Version 4.0 includes versioning, better ways of managing static content (example: footer or menu), better ways of managing URLs and linking to django CMS URLs and more. The release is already quite progressed, but help is always needed.

### How can you get involved?
* Create a project with 4.0 (see quick installer above) and start playing around with it. Try to make your most used plugins work in 4.0 and see if something breaks
* Report back on your findings in #workgroup-django-cms-4-0

## Work group Roadmap

Disclaimer: scope and estimates are tentative and can change along the way

### Create a django CMS 4 website template: Q4 2020
- for everyone to test and review
- instructions for setup
- no aldryn (? tbd, optional)

### django CMS v4 initial version of documentation: TBD
- set up initial version of the documentation
- lead by Daniele

### djangocms-alias cleanup: Q1 2021
- "it needs a bit of a cleanup from a frontend / UX perspective
- language related issues will be fixed outside of community scope
- its replacing static placeholders and the built-in alias plugin

### URL Manager cleanup: Q1 2021
- "it needs a bit of a cleanup from a frontend / UX perspective
- There is already the ability to link everything (?) incl. absolute external URLs: third party apps can already use model/widget/form registration (a.k.a. App Config) to hook into url manager

### djangocms-bootstrap4 Upgrade: Q2+ 2021
- migrate it to django CMS v4
- it has nesting, dependency on filer, etc.
- migrate to bootstrap v5 right away?
- possibly move it to djangocms-bootstrap or djangocms-bootstrap5
- create a blog post or documentation, i.e. document a "reference project"- including documentation

### Alternative: djangocms-frontend Q1 2022
- supports Bootstrap 5
- depends on filer, but drops dependency on djangocms-icon, djangocms-link, and djangocms-picture
- developed for both v3 and v4

### django applications on the example of djangocms-blog: Q3+ 2021
- Iacopo is leading this
- page and plugin architecture has changed, we would need to upgrade djangocms-blog to make it compatible
- create a blog post or documentation, i.e. document a "reference project"

### djangocms-cascade: TBD by Jacob
- Ownership: Jacob Rief
- directly to bootstrap v5

### official django CMS v4 Community Release Q4 2021
- the official release

### django CMS installer (?): TBD by Iacopo
- Iacopo to investigate current usage first

### djangocms-moderation Q1 2022
- it will already work before, but we could officially release it at a later point

# Documentation

The documentation has been moved out of this document and is slowly being added to the codebase of the project. Here is a temporary link that will be updated as and when documentation is merged. :-)

https://github.com/django-cms/django-cms/pull/7367

| Topic | Description |
| - |- |
| New Plugin Architecture (Backend) | Treebeard was previously used. Treebeard only used for pagetree. Migration possible, simple |
| Placeholder field relations| Affected for programmed placeholder fields. Now better to know what plugin is stored where. Should still work on a migration, source is backwards compatible |
| Pages and titles | Placeholders are now separated into languagesBefore you had one placeholder per page for all languages now it is 3placeholders for 3 languages |
| Title is now “page contents” | Basic settings were stored in the title object and advanced settings in the page object. Title is now PageContentSome settings have been moved to PageContent. For example templates can now be set as PageContent meaning if you have different languages each language can have a different template. Should be fine but might eventually require work|
| Changes in how we store the URL information | Slug and path is now stored outside of PageContentIs now stored in PageUrlShould be migrated to new system |
| Publishing of django CMS has been removed | Draft and live pages don’t exist anymore. Migration is possible and has been achieved. |
| ?edit has been removed | There are 3 new endpoints to change contentLive version of the page. Edit button that goes to versioning. Preview view of a websiteKeep ?edit would the same as ?toolbar_on. Should be migrated to new system |
| New system to interact between addons via CMSAppConfig andCMSAppExtension | Is a new systemBackwards compatibility is available |
| Disabled Features – Backwards Incompatible | Page types have been disabled. Why has it been removed, alternative? GOOD Default plugins per placeholder on render (if the placeholder isempty check if it has configured default plugins > create these on rendertime). Handover 3Kryz working on an add-on to do it on addon level. Temporary removal, Ask Andrew Aikman about registering the PageType model with the Placeholder endpoints: https://github.com/django-cms/django-cms/pull/6503 |
| Need to continue conversation | A few things have been removed from the core. Removing / deprecating the alias addon. Upgrade path can be added. Default plugins. Feature from placeholder configurations. Plugin inheritance has been removed. If placeholder is empty take the plugins from the parentKeep or remove? Static placeholders will be gone? As plugins cannot be stored the traditional way. Add warning for deprecations that changes will be removed in 4.2 |

## Documentation TODO:
- Architecture of 3.x vs 4.x, justifying why the code was changed the way that it was
- Advised core packages and link to relevant documentation
- Add migration documentation
- Add cms copy method
- Add App registration documentation to the docs
- Rework reference documentation
- Rework topics documentation

# Migrating code from django-cms 3.x to 4.x

WIP with examples from the following PR's to follow:
- https://github.com/django-cms/djangocms-url-manager/pull/50
- https://github.com/nephila/djangocms-blog/pull/672/files

TODO:
- Reusing the placeholder editing experience for your own models
- Migrating from PlaceholderField to PlaceholderRelationField

## PlaceholderField replaced by PlaceholderRelationField
The `PlaceholderField` has been replaced by the `PlaceholderRelationField`

## Settings changes
TODO:
1. Toolbar ?edit removed
2. Persist toolbar states through page creation: https://github.com/django-cms/django-cms/commit/77a48d6eea33606b50fa1fcacefea530660e6436
3.

## Testing your v3 apps against v4

*(Reported by Fabian when testing djangocms-frontend)*

To test your app against django CMS version 4 you likely will need to adjust your tests.

Frist, we for the time being recommend to following requirements for django CMS v4 (development version) for the Django and django CMS part:

Django>=3.2,<4.0
-e git+https://github.com/django-cms/django-cms.git@develop-4#egg=django-cms
-e git+https://github.com/Aiky30/djangocms-alias.git@feature/django-32-compat#egg=djangocms-alias
-e git+https://github.com/django-cms/djangocms-url-manager.git@master#egg=djangocms-url-manager
https://github.com/django-cms/djangocms-versioning/tarball/master#egg=djangocms-versioning
-e git+https://github.com/FidelityInternational/djangocms-pageadmin.git@1.0.0#egg=djangocms-pageadmin
-e git+https://github.com/FidelityInternational/djangocms-version-locking.git@master#egg=djangocms-version-locking

You might have to adjust your fixtures to differentiate test for django CMS v3 and django CMS v4.

To determine if tests are run against v3 or v4, add this to your test settings (this assumes the above requiremets):

try:
import djangocms_versioning # V4 test?

INSTALLED_APPS += [
"djangocms_versioning",
"djangocms_alias",
"djangocms_url_manager",
]
except ImportError: # Nope
pass

Then you can differentiate within your testing environment (or in your app for that matter) by checking for a v4 app, say `djangocms_versioning`:

from django.apps import apps

DJANGO_CMS4 = apps.is_installed("djangocms_versioning")

Key differences to test against v3 and v4 are:

* **``page.palceholders``** is not present in django CMS v4. Use ``page.get_placeholders(language)`` instead. Note, however, that in v4 ``page.get_placeholders(language)`` requires the language parameter while in v3 it must not be present. A solution can be to add a method ``get_placeholders`` to your test class that calls the page's method with or without the language parameter depending on which version you are testing with.

* **``page.publish``**, **``page.unpublish``**: In django CMS v4 the ``Page`` model does not have ``.publish`` or ``.unpublish`` methods. Publication is handleded by djangocms-versioning. This requires to find all versions of a page and identifying the current draft version to publish or the current published version to unpublish. For an example code fragment see below.

* **``create_page``**: The CMS function ``crate_page`` needs additional arguments in v4:

* ``created_by``: User who creates the page. Can often be ``self.superuser``
* ``in_navigation``: Can default to ``True``
* ``limit_visibility_in_menu``: Can default to ``None``

To test djangocms-frontend I added the following code fragment to by test fixture mixin:

if DJANGO_CMS4: # CMS V4

def _get_version(self, grouper, version_state, language=None):
language = language or self.language

from djangocms_versioning.models import Version

versions = Version.objects.filter_by_grouper(grouper).filter(
state=version_state
)
for version in versions:
if (
hasattr(version.content, "language")
and version.content.language == language
):
return version

def publish(self, grouper, language=None):
from djangocms_versioning.constants import DRAFT

version = self._get_version(grouper, DRAFT, language)
if version is not None:
version.publish(self.superuser)

def unpublish(self, grouper, language=None):
from djangocms_versioning.constants import PUBLISHED

version = self._get_version(grouper, PUBLISHED, language)
if version is not None:
version.unpublish(self.superuser)

def create_page(self, title, **kwargs):
kwargs.setdefault("language", self.language)
kwargs.setdefault("created_by", self.superuser)
kwargs.setdefault("in_navigation", True)
kwargs.setdefault("limit_visibility_in_menu", None)
kwargs.setdefault("menu_title", title)
return create_page(
title=title,
**kwargs
)

def get_placeholders(self, page):
return page.get_placeholders(self.language)

else: # CMS V3

def publish(self, page, language=None):
page.publish(language)

def unpublish(self, page, language=None):
page.unpublish(language)

def create_page(self, title, **kwargs):
kwargs.setdefault("language", self.language)
kwargs.setdefault("menu_title", title)
return create_page(
title=title,
**kwargs
)

def get_placeholders(self, page):
return page.get_placeholders()

# Identified issues in test projects

| Package & date | Issue |
| ---------- | ------------ |
| django-cms 18/03/22| The page tree needs a button to manage page versions if djangocms-versioning is installed.|
| djangocms-versioning 13/04/22 | There is not "view on site" or "view published" link from a published version |

# Status of key cms packages

Date: 28/03/2022

| Package V3 | V4 replacement | Testing against v4 | Importance | Target |
| -------------------------- | ------------------------ | ------------------ | ---------- | ------ |
| django-cms | django-cms | Add depr. warnings?| 5 | ? |
| djangocms-link (depr.) | djangocms-url-manager | Yes | 5 | ? |
| djangocms-link (depr.) | djangocms-frontend | Yes, common code | 4 | Q1/22 |
| | djangocms-moderation | Yes | 5 | ? |
| | djangocms-versioning | Yes | 5 | ? |
| djangocms-alias | djangocms-alias | Yes, common code | 5 | ? |
| djangocms-file | djangocms-file | ? | 5 | ? |
| django-filer | django-filer | ? | 5 | ? |
| djangocms-admin-style | djangocms-admin-style | to do, common code | 3 | ? |
| djangocms-text-ckeditor | djangocms-text-ckeditor | ? | 5 | ? |
| djangocms-text-ckeditor | djangocms-text-ckeditor5 | ? | 3 | ? |
| djangocms-column (depr.) | depr. | - | | - |
| djangocms-attributes-field | djangocms-attributes-field|Yes, common code |  5 | ? |
| djangocms-snippet | djangocms-snippet | to do |  3 | ? |
| djangocms-icon | djangocms-icon | to do |  4 | ? |
| djangocms-audio | djangocms-audio | to do |  3 | ? |
| djangocms-style | djangocms-style | to do |  3 | ? |
| djangocms-history (depr.) | depr. | - | | - |
| djangocms-googlemap (depr.)| djangocms-maps (?) | ? | 3 | ? |
| djangocms-maps (?) | djangocms-maps (?) | ? | 3 | ? |
| djangocms-modules | djangocms-modules | ? |  3 | ? |
| djangocms-transfer | djangocms-transfer | ? | 2 | ? |
| djangocms-video | djangocms-video | ? | 3 | ? |
| djangocms-video | djangocms-frontend? | Yes, common code | 3 | Q2/22 |
| djangocms-picture | djangocms-frontend | Yes, common code | 4 | Q1/22 |
| djangocms-bootstrap4 | djangocms-frontend | Yes, common code | 4 | Q1/22 |
| djangocms-bootstrap5 | djangocms-frontend | Yes, common code | 4 | Q1/22 |
| djangocms-frontend | djangocms-frontend | Yes, common code | 4 | Q1/22 |
| cmsplugin-filer | depr. | - | | - |
| djangocms-blog | djangocms-blog | Not yet | 5 | - |
| ... | ... | - | | - |