Add documentation about divisions

torchbox · Jan 10, 2025 · 7154f5d · 7154f5d
1 parent c7116a0
commit 7154f5d
Show file tree

Hide file tree

Showing 2 changed files with 27 additions and 2 deletions.
diff --git a/docs/custom-features/divisions.md b/docs/custom-features/divisions.md
@@ -0,0 +1,24 @@
+# Divisions
+
+The site's target audience can be grouped into divisions; e.g. the charity division, the public sector division, and the Wagtail division. All content going forward can be associated to one of these divisions.
+
+The idea is that if you're a charity organisation, you can find content that's specific and relevant for you because the relevant content will all be in one place.
+
+This feature allows content to be associated to a specific `DivisionPage`, which allows us to display the same theme, logo and navigation for any content related to a division.
+
+## Options
+
+The available options are dependent on the `DivisionPage`s that have been created.
+
+## Division configuration
+
+The `tbx.core.utils.models.DivisionMixin` provides a mechanism for associating a specific division with a page. It offers the following functionality:
+
+- `division` field: Adds a ForeignKey field to associate a specific division with a page.
+- `get_division`: A method that determines the appropriate division to associate to a page. It first checks if the page has a `division` specified. If not, it traverses the page's ancestors to find the first page that either has a `division` specified or is a `DivisionPage`, defaulting to `None`.
+
+---
+
+???+ note
+
+    Please ensure that the Editors' guide is updated accordingly whenever any changes are made to this feature. A private link, for Torchbox employees only, can be found at https://intranet.torchbox.com/torchbox-com-project-docs.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -81,10 +81,11 @@ nav:
       - front-end/incident-form.md
   - 'Navigation': 'navigation.md'
   - 'Custom features':
+      - 'Contact': 'custom-features/contact.md'
+      - 'Division': 'custom-features/divisions.md'
       - 'Migration-friendly StreamFields': 'custom-features/migration-friendly-streamfields.md'
-      - 'Theme': 'custom-features/theme.md'
       - 'Modes': 'custom-features/modes.md'
-      - 'Contact': 'custom-features/contact.md'
+      - 'Theme': 'custom-features/theme.md'
   - 'Continuous integration': 'continuous-integration.md'
   - 'Anonymised data': 'anonymised-data.md'
   - 'Data import': 'data-import.md'