Metadata-Version: 2.4
Name: djangocms-history
Version: 3.0.0
Summary: Adds undo/redo functionality to django CMS
Author-email: Divio AG <info@divio.ch>
Maintainer-email: Django CMS Association and contributors <info@django-cms.org>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/django-cms/djangocms-history
Project-URL: Repository, https://github.com/django-cms/djangocms-history
Project-URL: Issues, https://github.com/django-cms/djangocms-history
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Framework :: Django :: 6.1
Classifier: Framework :: Django CMS
Classifier: Framework :: Django CMS :: 4.1
Classifier: Framework :: Django CMS :: 5.0
Classifier: Framework :: Django CMS :: 5.1
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: django-cms>=4.1
Provides-Extra: test
Requires-Dist: coverage; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-django; extra == "test"
Dynamic: license-file

==================
django CMS History
==================

|pypi| |coverage| |python| |django| |djangocms|

**django CMS History** is an addon application to provide undo/redo functionality in `django CMS
<https://django-cms.org/>`_, by maintaining content history.

Some of the functionality in this application was previously included in django CMS itself. However, it became apparent
that some users did not want it, and some wanted functionality that worked differently.

In keeping with the django CMS philosophy of maintaining only core CMS functionality as part of the package itself,
history management was removed from django CMS in version 3.4 and has been spun off into an independent application.

django CMS History has been rewritten from the ground up. It will continue to be developed. New functionality and
improvements will be introduced in future releases.


.. image:: preview.jpg

*******************************************
Contribute to this project and win rewards
*******************************************

Because this is an open-source 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 CMS in the world.

We'll be delighted to receive your
feedback in the form of issues and pull requests. Before submitting your
pull request, please review our `contribution guidelines
<https://docs.django-cms.org/en/latest/contributing/index.html>`_.

We're grateful to all contributors who have helped create and maintain this package.
Contributors are listed at the `contributors <https://github.com/django-cms/djangocms-history/graphs/contributors>`_
section.

Documentation
=============

Version support
---------------

djangocms-history 3.x supports Python 3.9 through 3.13, Django 4.2, 5.2, 6.0
and 6.1, and django CMS 4.1, 5.0 and 5.1. **If you are using django CMS 3.x,
use djangocms-history 2.x.**

The supported Python, Django and django CMS versions are shown by the badges at the top of this page (latest
release read directly from the published PyPI classifiers). The latest supported versions of the master branch
are declared in ``pyproject.toml``; the tested combinations are defined in
``tox.ini`` and ``tests/requirements``.

Installation
------------

For a manual install:

* run ``pip install djangocms-history``
* add ``djangocms_history`` to your ``INSTALLED_APPS``
* run ``python manage.py migrate djangocms_history``

.. warning::

    Upgrading from djangocms-history 2.x: history records created with
    django CMS 3.x cannot be replayed against the plugin tree of
    django CMS 4 and later. All existing history records are deleted by
    the migrations of version 3.0. Since the undo window is 24 hours,
    this only affects operations performed right before the upgrade.

Configuration
-------------

Once installed, django CMS History will make new options available to the web content manager. These will be visible in
the django CMS toolbar when managing content that is supported by the application.

In-place updates
................

On django CMS 5.1 and later, undo and redo update the structure board in place
(through the data bridge the endpoints return), preserving scroll position and
board state. On earlier versions the page is reloaded after each undo/redo
instead.

History scope and limitations
.............................

History records plugin operations rather than arbitrary model or page changes.
Undo/redo is available for the last 24 hours and for one content origin per
user session. Editing another page supersedes the previous page's history;
another user's edit supersedes history only when it affects the same content.
Changing a plugin with a many-to-many relation clears the history for that
content because the change cannot be restored reliably.

Operations older than 24 hours are ignored, but age alone does not immediately
delete or archive their database rows. Superseded operations and operations
from an earlier login session are retired when the corresponding cleanup path
runs.

Retiring operations: archive or delete
......................................

By default retired operations are **deleted** outright. If you would rather
retain them for inspection, enable archiving::

    DJANGOCMS_HISTORY_ARCHIVE_OPERATIONS = True

Archived operations are flagged with ``is_archived=True`` and are still never
used by undo/redo. They are not durable audit records: deleting related users,
placeholders or other referenced content may delete them through database
cascades. To remove archived operations later and reclaim database space, run::

    python manage.py purge_archived_operations

The command supports ``--days N`` (only purge archived operations older than
``N`` days) and ``--dry-run`` (report what would be deleted without deleting).

djangocms-versioning
--------------------

When `djangocms-versioning <https://github.com/django-cms/djangocms-versioning>`_
is installed, undo/redo only operates on content that is editable, i.e. on
draft versions. Once a version has been published, operations recorded on
its draft can no longer be undone or redone; the toolbar buttons are
disabled and the endpoints refuse to modify the published content.

Running Tests
-------------

The test suite uses `pytest <https://docs.pytest.org/>`_ (with
``pytest-django``). You can run tests by executing::

    python -m venv env
    source env/bin/activate
    pip install -r tests/requirements/dj52_cms50.txt -e .
    pytest

Run with djangocms-versioning installed::

    pip install djangocms-versioning
    VERSIONING=1 pytest


.. |pypi| image:: https://badge.fury.io/py/djangocms-history.svg
    :target: http://badge.fury.io/py/djangocms-history
.. |coverage| image:: https://codecov.io/gh/django-cms/djangocms-history/graph/badge.svg
    :target: https://codecov.io/gh/django-cms/djangocms-history

.. |python| image:: https://img.shields.io/pypi/pyversions/djangocms-history
    :alt: PyPI - Python Version
    :target: https://pypi.org/project/djangocms-history/
.. |django| image:: https://img.shields.io/pypi/frameworkversions/django/djangocms-history
    :alt: PyPI - Django Versions from Framework Classifiers
    :target: https://www.djangoproject.com/
.. |djangocms| image:: https://img.shields.io/pypi/frameworkversions/django-cms/djangocms-history
    :alt: PyPI - django CMS Versions from Framework Classifiers
    :target: https://www.django-cms.org/
