Allow making category group required for channel; Allow restricting category selection to single category per group

docs/control-panel/channels.md

@@ -61,6 +61,15 @@ A channel can have any combination of fields and field groups assigned to it. Yo
 
 This tab allows you to create and assign category groups to your channel. A channel may have multiple category groups assigned, and groups can be created on the fly on this tab.
 
+![Channel Preferences - Categories settings](_images/cp-channel-categories-tab.png)
+
+For each category group assigned to a channel, the following per-group settings are available:
+
+| Setting         | Default | Description                                                                                 |
+| --------------- | ------- | ------------------------------------------------------------------------------------------- |
+| Allow multiple? | Yes     | When turned on, multiple categories from the group can be selected for an entry                |
+| Required?       | No      | When turned on, selecting at least one category from the group is required to save an entry |
+
 ---
 
 ### Statuses tab

docs/control-panel/create.md

@@ -68,9 +68,13 @@ You may _optionally_ specify a date on which comments for this entry will no lon
 
 ## Categories Tab
 
-You may assign your entries to one ore more categories. To select more than one category you will typically hold down the CTRL (or CMD) key while choosing the individual category names.
+You may assign one or multiple (depending on [channel preference](control-panel/channels.md#categories-tab)) categories to your entry from the [category groups](control-panel/categories.md) associated with the channel.
 
-Clicking the Edit Categories link will permit you to add, edit, or delete categories that appear in the list.
+Each associated category group will be rendered as a separate set of checkboxes. If multiple selections are not allowed they will render as a set of radio buttons. Selecting a category from a group can also be set as required for the channel.
+
+Additionally, a "Manage Categories" toggle is provided which allows the user to add, edit or reorder categories within the group.
+
+![Publish Form - Categories](_images/cp-entry-categories-tab.png)
 
 ## Options Tab
 

docs/development/models/category-group-settings.md

@@ -0,0 +1,59 @@
+---
+lang: php
+---
+
+<!--
+    This source file is part of the open source project
+    ExpressionEngine User Guide (https://github.com/ExpressionEngine/ExpressionEngine-User-Guide)
+
+    @link      https://expressionengine.com/
+    @copyright Copyright (c) 2003-2023, Packet Tide, LLC (https://packettide.com)
+    @license   https://expressionengine.com/license Licensed under Apache License, Version 2.0
+-->
+
+# Category Group Settings Model
+
+**class `ExpressionEngine\Model\CategoryGroupSettings`**
+
+[TOC]
+
+## Properties
+
+| Name                         | Validation   | Type       | Description  |
+| ---------------------------- |------------- | ---------- | -----------  |
+| `category_group_settings_id` |              |            | the primary key |
+| `site_id`                    |              |            | the site id |
+| `group_id`                   | required     |            | the category group id |
+| `channel_id`                 | required     |            | the channel id |
+| `cat_required`               |              | boolString | whether or not having a category in this group is required for this channel |
+| `cat_allow_multiple`         |              | boolString | whether or not having multiple selections is allowed in this category group for this channel |
+
+## Relationships
+
+### `Site`
+
+The MSM Site for which the Category Group belongs to.
+
+### `Channel`
+
+Channel for which these settings are defined
+
+### `CategoryGroup`
+
+Category Group for which these settings are defined
+
+
+## Methods
+
+- `getAllCustomFields()`
+- `createCategoryField()`
+- `getContentType()`
+- `getCategoryTree()`
+- `getFieldMetadata()`
+- `populateCategories()`
+- `buildCategoryOptionsTree()`
+- `buildCategoryList($categories, $sort_column)`
+
+## Events
+
+- `afterDelete`

docs/development/models/category-group.md

@@ -7,7 +7,7 @@ lang: php
     ExpressionEngine User Guide (https://github.com/ExpressionEngine/ExpressionEngine-User-Guide)
 
     @link      https://expressionengine.com/
-    @copyright Copyright (c) 2003-2022, Packet Tide, LLC (https://packettide.com)
+    @copyright Copyright (c) 2003-2023, Packet Tide, LLC (https://packettide.com)
     @license   https://expressionengine.com/license Licensed under Apache License, Version 2.0
 -->
 
@@ -32,8 +32,29 @@ lang: php
 
 ## Relationships
 
-- `CategoryField`
-- `Category`
+### `Site`
+
+The MSM Site which the Category Group belongs to.
+
+### `CategoryGroupSettings`
+
+Per-channel settings for this Category Group.
+
+### `CategoryFields`
+
+Custom fields associated with this Category Group
+
+### `Categories`
+
+Collection of categories that have been created in this group
+
+### `Channels`
+
+Channels that this Category Group has been assigned to
+
+### `UploadDestinations`
+
+File upload directories that this Category Group has been assigned to
 
 ## Methods
 

docs/development/models/working-with-models.md

@@ -26,8 +26,10 @@ These are the most commonly used models in ExpressionEngine. For a full list, se
 - [Addon Fieldtype Model](development/models/addon-fieldtype.md)
 - [Addon Module Model](development/models/addon-module.md)
 - [Addon Plugin Model](development/models/addon-plugin.md)
-- [Category Field](development/models/category-field.md)
 - [Category Group](development/models/category-group.md)
+- [Category Group Settings](development/models/category-group-settings.md)
+- [Category](development/models/category.md)
+- [Category Field](development/models/category-field.md)
 - [Channel Entry Model](development/models/channel-entry.md)
 - [Channel Field Group Model](development/models/channel-field-group.md)
 - [Channel Field Model](development/models/channel-field.md)

docs/toc_sections/_advanced_usage_toc.yml

@@ -416,6 +416,8 @@
           href: development/models/category-field.md
         - name: Category Group Model
           href: development/models/category-group.md
+        - name: Category Group Settings Model
+          href: development/models/category-group-settings.md
         - name: Channel Entry Model
           href: development/models/channel-entry.md
         - name: Channel Field Group Model