Content: Blog

Preparation Phase: Get to know djangocms-text

To get started with djangocms-text, begin by installing the latest version of the package of a test system where you cannot loose data:

> pip uninstall djangocms-text-ckeditor
> pip install djangocms-text

Update your INSTALLED_APPS setting to reflect the new package:

INSTALLED_APPS = [
    ...,
    "djangocms-text",
    ...,
]

By default, djangocms-text uses TipTap as its rich text editor. TipTap stores content as structured JSON, which means that not all custom HTML attributes manually added to your project will be retained.

Run migrations. Migrations will copy existing djangocms-text-ckeditor plugins to new djangocms-text plugins. The djangocms-text-ckeditor database tables will only be read and not be written to. 

djangocms-text allows for integration with different rich text editors. Depending on your project different scenarios might suit your needs better.

One new feature is relevant for the decision: djangocms-text supports "dynamic HTML" which means that it can store references to pages or other Django objects which only are resolved into actual URLs when the HTML is fetched from the database. This allows djangocms-text to have references to pages which adjust automatically when pages are, say, moved or renamed ̣⨪ also in both HTMLFields and text plugins. There is no need to add a link plugin inside the text plugin.

Scenario Evalutation

* Automatically updating links, also in HTML fields.

The code base of djangocms-text is identical for all scenarios. What gets swpped out is the integration of the rich text editor package. I've summarized the different settings needed for the non-standard scenarios at the bottom.

Validation and Optimization Phase

Comprehensive Testing:

During this phase, thoroughly test all pages, placeholders, and plugins to ensure that the migration has preserved content integrity and that everything renders consistently across the site. Pay special attention to how content is displayed in different sections to confirm that the editor handles formatting and custom styles as expected. In addition, validate functionality across multiple browsers and devices to ensure that the user experience remains consistent and accessible for all audiences.

Collect Feedback:

Gather feedback from key stakeholders, including editors and developers, to identify usability concerns or feature gaps. Editors can provide insights on how intuitive the new editor is for day-to-day content management, while developers can identify any technical issues or areas for optimization. Use this feedback to make necessary adjustments and refine the configuration of djangocms-text and its associated editor. 

Report issues and propose improvements:

Please report issues on github to help improve the experience. You are kindly invited to share any improvements by creating a pull request on github. We strive to provide an excellent editing experience, but only can achieve this with the help of the community!

Post-Migration

Monitor Performance and User Feedback:

After the migration, continuously monitor the performance and stability of djangocms-text and the chosen editor. Watch for any unexpected behavior or performance bottlenecks that may arise during regular usage. Actively collect user feedback to address concerns and ensure the solution meets their needs. Additionally, stay proactive by regularly updating to the latest version of djangocms-text and its editor to benefit from ongoing improvements, bug fixes, and contributions from the community.

Documentation Updates:

Update your internal documentation to reflect the configuration and usage of the new editor. Include detailed setup instructions, usage tips, and troubleshooting guidelines for both editors and developers. Clear, updated documentation will ensure smooth onboarding for new team members and reduce the learning curve for those transitioning to the new edit

Integration Phase

Update Dependencies  

When migrating from djangocms-text-ckeditor to djangocms-text, it is crucial to ensure that both packages are not installed at the same time. These two packages are incompatible with each other and can cause conflicts if they coexist in the same environment. To prevent potential issues, completely uninstall djangocms-text-ckeditor before installing djangocms-text. You can do this by running:  

pip uninstall djangocms-text-ckeditor
pip install djangocms-text

In addition to replacing djangocms-text-ckeditor with djangocms-text in your project’s dependencies, check for any indirect dependencies that may still reference the old package. Some third-party plugins or legacy configurations might still require djangocms-text-ckeditor, so it’s important to update those dependencies accordingly. Make sure your dependency management files (such as requirements.txt or pyproject.toml) no longer list djangocms-text-ckeditor before proceeding.  

Once the transition is complete, verify that all required plugins are compatible with djangocms-text and your chosen editor, whether it’s TipTap or CKEditor5. Fortunately, djangocms-text includes compatibility shims to handle imports of HTML fields, so most plugins should continue to function without modification. However, it's a good practice to test your setup thoroughly to ensure a smooth migration and avoid unexpected formatting issues.

Update project settings

If your project contains outdated settings related to djangocms-text-ckeditor, djangocms-text will issue warnings to help identify deprecated configurations. Pay attention to these warnings, as they provide guidance on what needs to be changed. For more detailed information on configuring djangocms-text, refer to the README file included in the package.

Non-standard Scenarios

djangocms-text

...,
"djangocms_text",
...

TEXT_EDITOR = "djangocms_text.contrib.text_ckeditor4.ckeditor4"

djangocms-text
djangocms-text-ckeditor5

...,
"djangocms_text",
"djangocms_text_ckeditor5",
...

TEXT_EDITOR = "djangocms_text_ckeditor5.ckeditor5"