Upgrade to DjangoCMS 4

En 2022, l’équipe de Django CMS a commencé une branche 4.x de leur application qui aboutira finalement en décembre 2023 avec la 4.1.0, les versions 4.0.x n’étant que de l’expérimentation.

L’objectif de cette nouvelle version majeure était de réorganiser et nettoyer le code hérité de plusieurs années, pour ouvrir la voie à de nouvelles fonctionnalités ou améliorations.

Courant 2024, Django CMS s’est finalement stabilisé avec la 4.1.3 pour ensuite commencer à mettre son écosystème à niveau.

Néanmoins le passage à la V4 n’est pas sans complication du fait de nombreux changements de fond et à ce jour il n’y a pas de solution efficace pour passer un projet existant en V3 à la V4, nous y reviendrons en fin d’article.

Résumé des changements

Mise à jour du support des versions

La couverture actuelle de support (v4.1.4) est :

• Django 3.2 à 5.0;
• Python 3.8 à 3.12;

Un support assez large reste en vigueur, mais ce n’est pas très important puisque du fait de l’impossibilité de migrer un projet existant en V3 il est probable que vous démarrerez un nouveau projet avec le Python et le Django le plus récent possible.

Changement de la modélisation des données

Le modèle PageTitle a été renommé en PageContent et plusieurs attributs du modèle Page ont été déportés sur PageContent.

PageContent contient donc maintenant des attributs anciennement sur Page et l’on n'accède plus programmatiquement aux contenus d’une page comme on y accédait jadis avec le modèle Title car on ne cible plus une langue mais un placeholder.

La plupart des méthodes pour les placeholder, versions et contenus nécessite de passer un réel utilisateur en argument pour être viable.

Par exemple si on crée un PageContent ou Version sans fournir d’objet utilisateur cela reste valide mais ces objets deviennent quasiment impossibles à retrouver.

Ceci est causé par le manager de Page et PageContent qui force maintenant des filtres de queryset pour empêcher de retourner des objets privés. Et un objet sans réel utilisateur est considéré comme privé.

Référence: Page, Title (now PageContent) and Placeholder refactor.

État de publication simplifié

Dans la V3, la publication se faisait via un objet Title et il n’y avait que deux états: Brouillon ou Publié. Un objet Page avait aussi un état global de ses Title.

Désormais dans la V4, il n’y a plus d’état de publication implémenté et il n’y a plus de brouillon pouvant retenir temporairement des changements sans les publier. Une fois validé, les changements sont directement publiés et il n’y a plus de retour en arrière possible.

La fonctionnalité de l’état de publication a en fait été déportée à une application tierce djangocms-versioning. Une fois installée et configurée cette application reproduira par défaut le comportement de publication (brouillon, publié) de la V3. On peut aussi éventuellement développer un état de publication plus évolué si besoin.

Si djangocms-versioning est officiellement optionnel, il est cependant fortement recommandé par les développeurs.

Référence: Publishing has been moved to djangocms-versioning.

La fonctionnalité des ‘static placeholder’ est abandonnée

On pouvait avant désigner un identifiant de placeholder pour le considérer comme générique et partagé. On pouvait alors partager son contenu dans plusieurs pages tout en appliquant les changements qu’une seule fois (sur n’importe quelle page qui l’intégrait).

Cette fonctionnalité a été abandonnée dans Django CMS lui même et déportée dans une application tierce optionnelle djangocms-alias.

Référence: Static Placeholders.

Ouverture à une API REST

Django CMS a ouvert plusieurs nouveaux endpoints pour permettre de l’utiliser soit exclusivement en mode headless ou bien mélangé avec le mode standard HTML.

Il n’y a pas de référence unique à ce sujet, vous pourrez trouver l’annonce de l’ouverture de certains endpoints dans la documentation des différentes versions depuis la 4.0.0 à la version en cours.

Notez qu’à ce jour (v4.1.4), la couverture des fonctionnaltiés du CMS n’est pas encore complète et la prochaine version à venir devrait améliorer la situation pour être réellement utilisable.

Enfin les endpoints existants ne sont pas exposés par défaut dans Django CMS, cela reste à votre charge mais l’application tierce djangocms-rest peut le faire pour vous en se reposant sur Django REST framework.

À propos de l’API programmatique

L’API programmatique (l’interface permettant d’exploiter les fonctionnalités de Django CMS directement depuis votre code) a été adaptée à tous les nombreux changements de la V4.

Cependant ces changements compliquent un peu les tâches et globalement il est devenu moins aisé d’accéder, créer et modifier des contenus et des pages.

Concrètement si vous aviez du code pour créer des pages pour vos tests unitaires ou une moulinette de création de contenus avec la V3, il ne sera plus fonctionnel avec la V4.

La migration de votre code programmatique ne se fera pas simplement puisque certains paradigmes du CMS ont changé vis à vis de la langue, des contenus et de la publication.

Évolution du système des plugins

Les plugins ont légèrement changé pour s’adapter à la remodélisation des pages et contenus.

Cependant les plugins existants depuis la V3 ont globalement la possibilité d’être compatibles avec la V4 à très peu de frais. Si un plugin se résume à modifier ses options et rendre du contenu, il aura de grandes chances de ne nécessiter qu’une migration supplémentaire (pour une mise à jour de clé relationnelle).

Éditeur de texte

Historiquement l’édition des textes de contenu se faisait avec l’éditeur CKEditor dans sa version 4. Cet éditeur était inclus via l’application djangocms-text-ckeditor qui était une dépendance quasiment obligatoire.

Cependant cette application est restreinte à la version 4 de CKEditor dont le développement s’est totalement arrêté en 2023 au profit de la version 5. CKEditor 4 a quelques failles potentielles de sécurité connues et CKEditor 5 a subi un changement de licence qui peut poser soucis.

C’est pourquoi les développeurs de Django CMS ont créé une nouvelle application djangocms-text dont le but est de ne pas être lié uniquement à CKEditor et donc de permettre d’utiliser potentiellement n’importe quel autre type d’éditeur de texte.

Actuellement (v0.7.1) l’application pourvoit les éditeurs TipTap, CKEditor 4, CKEditor 5 et TinyMCE.

TipTap est l’éditeur par défaut, vous pouvez aisément passer à un autre si besoin et l’implémentation CKEditor 4 reproduit la même expérience utilisateur que Django CMS v3. Vous pouvez basculer votre projet d’un éditeur à l’autre si besoin, et cela, sans aucune perte.

Au final djangocms-text reste une alternative optionnelle et il est toujours possible actuellement de créer un projet Django CMS 4 avec djangocms-text-ckeditor, mais il est en voie d’abandon et il est clairement plus judicieux de démarrer avec djangocms-text. Ces deux applications ne sont pas compatibles et vous ne pourrez pas passer de l’une à l’autre sans perdre vos contenus.

Écosystème

Les développeurs ont déjà réalisé beaucoup de travail pour que les applications de l’écosystème de DjangoCMS soient compatibles avec la V4 mais il reste encore beaucoup de plugins officiels (maintenus par le groupe ‘djangocms’) qui ne sont pas encore officiellement compatibles.

C’est souvent la cause d’un manque de main d’oeuvre et de temps pour s’occuper de ces applications qui n’ont pas un intérêt aussi critique que d’autres.

Beaucoup pourront problablement fonctionner mais sans garantie de stabilité, il vous faudra donc les recenser et décider d’abandonner leur fonctionnalité, de la prendre en charge ou de participer à leur développement.

Bilan

Nous n’avons détaillé ici que les changements majeurs parmi de nombreux autres changements dont des améliorations de performance et d’expérience utilisateurs. Vous pouvez d’ailleurs consulter les différents entrées d’historiques de changements de DjangoCMS pour retrouver l’intégralité des changements.

La version 4 est une évolution positive sans pour autant dénaturer Django CMS. Cependant il reste le problème de la migration d’un projet existant en version 3.

En effet la nouvelle version combine une rémodélisation majeure, la déportation de fonctionnalités natives dans des applications additionnelles et l’absence de solution convenable pour migrer les données existantes.

Migration d’un projet existant

En 2023 les développeurs ont commencé l’outil djangocms-4-migration qui aurait pu permettre une migration moins pénible mais malheuresement il a été abandonné en cours de route. Cet outil pourrait finalement vous aider à la migration mais pas sans manipulations supplémentaires de votre part.

Dans le cas d’un projet qui ferait un usage basique de Django CMS qui consiste à utiliser des plugins dans des pages, une procédure ETL (Extract, Transform, Load) pourrait probablement achever une migration. Il faudra cependant développer une commande d’extraction pour exporter les données utiles d’un projet en V3 et en développer une autre pour les injecter dans un projet en V4.

Nous vous recommandons par contre d’utiliser l’API programmatique de Django CMS pour pratiquer l’injection de données car c’est le seul moyen assuré d’achever une migration stable et complète puisque Django CMS maintient en interne des clés relationnelles, index et hiérarchies lors des enregistrements et il vous sera difficile de faire de même.