From c02224a508783c1a6fa48ba33a9946659f443f1d Mon Sep 17 00:00:00 2001 From: Guy Sartorelli Date: Fri, 25 Oct 2024 13:36:38 +1300 Subject: [PATCH] DOC Document new SingleRecordAdmin class --- .../01_ModelAdmin.md | 8 +-- .../03_SingleRecordAdmin.md | 63 +++++++++++++++++++ ...Architecture.md => 04_CMS_Architecture.md} | 0 .../{03_CMS_Layout.md => 05_CMS_Layout.md} | 0 .../{04_Preview.md => 06_Preview.md} | 0 .../{05_Typography.md => 08_Typography.md} | 0 ...opment.md => 10_Javascript_Development.md} | 0 ...jQuery_Entwine.md => 11_jQuery_Entwine.md} | 0 ...S_and_Redux.md => 12_ReactJS_and_Redux.md} | 0 en/08_Changelogs/6.0.0.md | 9 +++ 10 files changed, 76 insertions(+), 4 deletions(-) create mode 100644 en/02_Developer_Guides/15_Customising_the_Admin_Interface/03_SingleRecordAdmin.md rename en/02_Developer_Guides/15_Customising_the_Admin_Interface/{02_CMS_Architecture.md => 04_CMS_Architecture.md} (100%) rename en/02_Developer_Guides/15_Customising_the_Admin_Interface/{03_CMS_Layout.md => 05_CMS_Layout.md} (100%) rename en/02_Developer_Guides/15_Customising_the_Admin_Interface/{04_Preview.md => 06_Preview.md} (100%) rename en/02_Developer_Guides/15_Customising_the_Admin_Interface/{05_Typography.md => 08_Typography.md} (100%) rename en/02_Developer_Guides/15_Customising_the_Admin_Interface/{06_Javascript_Development.md => 10_Javascript_Development.md} (100%) rename en/02_Developer_Guides/15_Customising_the_Admin_Interface/{07_jQuery_Entwine.md => 11_jQuery_Entwine.md} (100%) rename en/02_Developer_Guides/15_Customising_the_Admin_Interface/{08_ReactJS_and_Redux.md => 12_ReactJS_and_Redux.md} (100%) diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/01_ModelAdmin.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/01_ModelAdmin.md index 2b657fcda..aebdf6f3a 100644 --- a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/01_ModelAdmin.md +++ b/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 diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/03_SingleRecordAdmin.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/03_SingleRecordAdmin.md new file mode 100644 index 000000000..81ef8836e --- /dev/null +++ b/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; + } +} +``` diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/02_CMS_Architecture.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_CMS_Architecture.md similarity index 100% rename from en/02_Developer_Guides/15_Customising_the_Admin_Interface/02_CMS_Architecture.md rename to en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_CMS_Architecture.md diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/03_CMS_Layout.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/05_CMS_Layout.md similarity index 100% rename from en/02_Developer_Guides/15_Customising_the_Admin_Interface/03_CMS_Layout.md rename to en/02_Developer_Guides/15_Customising_the_Admin_Interface/05_CMS_Layout.md diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_Preview.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/06_Preview.md similarity index 100% rename from en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_Preview.md rename to en/02_Developer_Guides/15_Customising_the_Admin_Interface/06_Preview.md diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/05_Typography.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/08_Typography.md similarity index 100% rename from en/02_Developer_Guides/15_Customising_the_Admin_Interface/05_Typography.md rename to en/02_Developer_Guides/15_Customising_the_Admin_Interface/08_Typography.md diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/06_Javascript_Development.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/10_Javascript_Development.md similarity index 100% rename from en/02_Developer_Guides/15_Customising_the_Admin_Interface/06_Javascript_Development.md rename to en/02_Developer_Guides/15_Customising_the_Admin_Interface/10_Javascript_Development.md diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/07_jQuery_Entwine.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/11_jQuery_Entwine.md similarity index 100% rename from en/02_Developer_Guides/15_Customising_the_Admin_Interface/07_jQuery_Entwine.md rename to en/02_Developer_Guides/15_Customising_the_Admin_Interface/11_jQuery_Entwine.md diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/08_ReactJS_and_Redux.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/12_ReactJS_and_Redux.md similarity index 100% rename from en/02_Developer_Guides/15_Customising_the_Admin_Interface/08_ReactJS_and_Redux.md rename to en/02_Developer_Guides/15_Customising_the_Admin_Interface/12_ReactJS_and_Redux.md diff --git a/en/08_Changelogs/6.0.0.md b/en/08_Changelogs/6.0.0.md index 84ddfcb81..d6bc446ab 100644 --- a/en/08_Changelogs/6.0.0.md +++ b/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