DOC Document new SingleRecordAdmin class

en/02_Developer_Guides/15_Customising_the_Admin_Interface/01_ModelAdmin.md

@@ -1,11 +1,11 @@
 ---
-title: ModelAdmin
-summary: Create admin UI's for managing your data records.
+title: Managing Multiple Records
+summary: Create admin UI's for managing multiple records at once with ModelAdmin
 ---
 
-# ModelAdmin
+# Managing multiple records
 
-[ModelAdmin](api:SilverStripe\Admin\ModelAdmin) provides a simple way to utilize the Silverstripe CMS UI with your own data models. It can create
+[ModelAdmin](api:SilverStripe\Admin\ModelAdmin) provides a simple way to manage multiple records at once with your own data models. It can create
 searchables list and edit views of [DataObject](api:SilverStripe\ORM\DataObject) subclasses, and even provides import and export of your data.
 
 It uses the framework's knowledge about the model to provide sensible defaults, allowing you to get started in a couple

en/02_Developer_Guides/15_Customising_the_Admin_Interface/03_SingleRecordAdmin.md

@@ -0,0 +1,63 @@
+---
+title: Single-record Admin Sections
+summary: Create admin UI's for managing a single record with SingleRecordAdmin
+---
+
+# Single-record admin sections
+
+The [`SingleRecordAdmin`](api:SilverStripe\Admin\SingleRecordAdmin) class lets you create an admin section which presents an edit form for a single record. Unlike [`ModelAdmin`](api:SilverStripe\Admin\ModelAdmin), there's no UI mechanism in a `SingleRecordAdmin` to swap what record you're editing.
+
+The main use cases for using `SingleRecordAdmin` are for a settings section (where a single record holds all the settings needed for that section), or editing a record that is unique for each signed-in user (such as that user's profile).
+
+```php
+namespace App\Admin;
+
+use App\Model\MySettingsModel;
+use SilverStripe\Admin\SingleRecordAdmin;
+
+class MySettingsAdmin extends SingleRecordAdmin
+{
+    private static $url_segment = 'my-settings';
+
+    private static $menu_title = 'My Settings';
+
+    private static $model_class = MySettingsModel::class;
+}
+```
+
+This admin section will fetch a record of the `MySettingsModel` class using the [`get_one()`](api:SilverStripe\ORM\DataObject::get_one()) method.
+
+If you don't want the admin section to fetch your record in this way, you can set the [`only_one_record`](api:SilverStripe\Admin\SingleRecordAdmin->only_one_record) configuration property to false. In this case you must provide another way for the admin section to know which record to edit. This could be in the form of a separate action on the controller (e.g. `edit/$ID`), or by calling [`setCurrentPageID()`](api:SilverStripe\Admin\LeftAndMain::setCurrentPageID()) in the [`init()`](api:SilverStripe\Admin\LeftAndMain::init()) method of the controller.
+
+If there's no record to edit, by default it will create one for you. To disable that behaviour, set the [`allow_new_record`](api:SilverStripe\Admin\SingleRecordAdmin->allow_new_record) configuration property to false.
+
+> [!NOTE]
+> If you need more complex behaviour to fetch your record, for example you use the `silverstripe/subsites` or `tractorcow/silverstripe-fluent` module, you could either override the [`getSingleRecord()`](api:SilverStripe\Admin\SingleRecordAdmin::getSingleRecord()) method, or you could create [an extension](/developer_guides/extending/extensions/) that implements the `augmentSQL()` extension hook.
+>
+> The latter option is the most flexible, as it affects all high-level ORM queries for your model which ensures consistency when fetching the record from other areas of your code.
+
+For records that hold settings, it's common to provide a static method to get the current settings record. Below is a basic example.
+
+```php
+namespace App\Model;
+
+use SilverStripe\ORM\DataObject;
+
+class MySettingsModel extends DataObject
+{
+    // ...
+
+    /**
+     * Get the current settings record
+     */
+    public static function currentRecord(): MySettingsModel
+    {
+        $record = MySettingsModel::get_one();
+        if (!$record) {
+            $record = SiteConfig::create();
+            $record->write(skipValidation: true);
+        }
+        return $record;
+    }
+}
+```

en/08_Changelogs/6.0.0.md

@@ -484,6 +484,15 @@ As a result of this change, to following classes are now direct subclasses of `A
 - [`SudoModeController`](api:SilverStripe\Admin\SudoModeController) - used to be a subclass of `LeftAndMain`.
 - [`CMSExternalLinksController`](api:SilverStripe\ExternalLinks\Controllers\CMSExternalLinksController) - used to be a direct subclass of [`Controller`](api:SilverStripe\Control\Controller).
 
+#### New `SingleRecordAdmin` class and changes to `SiteConfig` {#leftandmain-singlerecordadmin}
+
+A new [`SingleRecordAdmin`](api:SilverStripe\Admin\SingleRecordAdmin) class has been created which makes it easier to create an admin section for editing a single record.
+
+This is the new super class for [`SiteConfigLeftAndMain`](api:SilverStripe\SiteConfig\SiteConfigLeftAndMain) and [`CMSProfileController`](api:SilverStripe\Admin\CMSProfileController). Some of the CSS selectors that had been added to the edit forms in those classes are no longer avaialable - if you were using CSS selectors in those admin sections, you may need to change the way you're handling that.
+
+As part of this change, we have removed the `updateCurrentSiteConfig` extension hook on [`SiteConfig`](api:SilverStripe\SiteConfig\SiteConfig) and updated the `canDelete()` permissions on `SiteConfig` to explicitly return `false` by default, even for administrators.
+The `getCMSActions()` method of `SiteConfig` also no longer returns the save action, as that is handled by the controller which instantiates the edit form. Other actions added through `getCMSActions()` (e.g. if you added them through an extension) will still be included.
+
 ### Changes to password validation {#password-validation}
 
 #### `PasswordValidator` changes