8000 Update 16-grouper-admin.rst by vasekch · Pull Request #24 · django-cms/docs · GitHub
[go: up one dir, main page]
Skip to content

Update 16-grouper-admin.rst #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 27, 2023
Merged

Update 16-grouper-admin.rst #24

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Update 16-grouper-admin.rst 
rephrased intro text
added imports to examples
  • Loading branch information
@vasekch
vasekch authored Apr 27, 2023
commit d17e51a028b3a0a9dbbf3626d96a43467d4a4750
27 changes: 17 additions & 10 deletions docs/how_to/16-grouper-admin.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expa 8000 nd Up @@ -6,21 +6,23 @@
How to crate an admin class for a grouper model
###############################################

***********************
What is a grouper model
***********************
************************
What is a grouper model?
************************

django CMS uses the grouper content model structure for pages:
It's an reusable abstract structural pattern, that is in django CMS used to separate language independent and and language specific content.

* The :class:`~cms.models.pagemodel.Page` is the grouper model and defines a unit (page) which can have more than one content object (page titles in different languages, for example).
django CMS defines grouper-content structure for Page-PageContent as follows:

* The :class:`~cms.models.contentmodels.PageContent` is the corresponding content model which contains page content that can be different for its grouping field ``language``. It also includes the placeholders for the frontend editor.
* The :class:`~cms.models.pagemodel.Page` is the grouper model which represents base unit, that can have multiple content objects attached

This mechanism ensures that content that is common for all pages of a languages, such as position in the page tree, or rights, are collected at the grouper model while all language-specific content is collected in the content model.
* The :class:`~cms.models.contentmodels.PageContent` is the content model which represents page content that can be different for its grouping field - ``language`` in our case. It also includes the placeholders for the frontend editor.

This mechanism ensures that language-independent properties of a page, such as position in the page tree or permissions, are collected at the grouper model while language-specific content is collected in the content model.

.. note::

Also this data structure is relevant for django CMS Versioning since it versions the content objects and not the grouper objects.
This pattern is relevant for django CMS Versioning since it versions the content objects and not the grouper objects.

To this end, if you want to create models that should be versionable like the :class:`~cms.models.contentmodels.PageContent` of a :class:`~cms.models.pagemodel.Page` objects you need to define a grouper and a content model.

Expand All @@ -42,6 +44,8 @@ To create a model admin class for a grouper model put the following code in your

.. code-block:: python

from cms.admin.utils import GrouperModelAdmin

class MyGrouperAdmin(GrouperModelAdmin):
# Declare content model
content_model = MyContent
Expand Down Expand Up @@ -82,6 +86,8 @@ This is an example (taken from django CMS alias) on how a grouper admin might lo

.. code-block:: python

from cms.admin.utils import GrouperModelAdmin

@admin.register(Alias)
class AliasAdmin(GrouperModelAdmin):
list_display = ['content__name', 'category', 'admin_list_actions']
Expand Down Expand Up @@ -146,8 +152,9 @@ Providing the required context
To provide the required context for your additional grouping model, you will have to implement two methods in your grouper model admin.

.. code-block:: python
from cms.admin.utils import GrouperModelAdmin

class MyGrouperModelAdmin(GrouperModelAdmin):
class MyGrouperAdmin(GrouperModelAdmin):
model = MyModel
extra_grouping_fields = ("region", )

Expand All @@ -170,4 +177,4 @@ To provide the required context for your additional grouping model, you will hav
}


Consider that the context will require a set of values your additional grouping field can take. In the region example this might be ``all_regions = {"americas": _("Americas"), "europe": _("Europe"), ...}``.
Consider that the context will require a set of values your additional grouping field can take. In the region example this might be ``all_regions = {"americas": _("Americas"), "europe": _("Europe"), ...}``.
0