From b901a16c378a343f422b5440327fb9367ffa2ee3 Mon Sep 17 00:00:00 2001 From: Guy Sartorelli <36352093+GuySartorelli@users.noreply.github.com> Date: Thu, 12 Dec 2024 17:30:11 +1300 Subject: [PATCH] DOC Document changes to CMSMain and LeftAndMain (#650) --- .../03_SingleRecordAdmin.md | 2 +- .../04_CMS_Architecture.md | 2 +- .../How_Tos/Customise_CMS_Tree.md | 10 ++--- en/08_Changelogs/6.0.0.md | 39 +++++++++++++++++-- 4 files changed, 42 insertions(+), 11 deletions(-) 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 index ad189a31..3c41574f 100644 --- 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 @@ -27,7 +27,7 @@ class MySettingsAdmin extends SingleRecordAdmin 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 [`restrict_to_single_record`](api:SilverStripe\Admin\SingleRecordAdmin->restrict_to_single_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 you don't want the admin section to fetch your record in this way, you can set the [`restrict_to_single_record`](api:SilverStripe\Admin\SingleRecordAdmin->restrict_to_single_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 [`setCurrentRecordID()`](api:SilverStripe\Admin\LeftAndMain::setCurrentRecordID()) 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. diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_CMS_Architecture.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_CMS_Architecture.md index 030c2418..42982382 100644 --- a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_CMS_Architecture.md +++ b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_CMS_Architecture.md @@ -449,7 +449,7 @@ class MyAdmin extends LeftAndMain ```ss <%-- MyRecordInfo.ss --%>
- Current Record: $currentPage.Title + Current Record: $currentRecord.Title
``` diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Tree.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Tree.md index 9e83d556..b327a34f 100644 --- a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Tree.md +++ b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Tree.md @@ -13,10 +13,10 @@ by the [jstree](https://jstree.com) library. It is configured through `client/src/legacy/LeftAndMain.Tree.js` in the `silverstripe/admin` module, as well as some HTML5 metadata generated on its container (see the `data-hints` attribute). -The tree is rendered through [LeftAndMain::getSiteTreeFor()](api:SilverStripe\Admin\LeftAndMain::getSiteTreeFor()), +The tree is rendered through [`CMSMain::getTreeFor()`](api:SilverStripe\CMS\Controllers\CMSMain::getTreeFor()), which recursively collects all nodes based on various filtering criteria. -The node strictly just has to implement the [Hierarchy](api:SilverStripe\ORM\Hierarchy\Hierarchy) extension, -but in the CMS usually is a [SiteTree](api:SilverStripe\CMS\Model\SiteTree) object. +The node strictly just has to implement the [`Hierarchy`](api:SilverStripe\ORM\Hierarchy\Hierarchy) extension, +but in the CMS usually is a [`SiteTree`](api:SilverStripe\CMS\Model\SiteTree) object. ## Add status flags to tree nodes @@ -36,7 +36,7 @@ code like this:     - + New Page Deleted @@ -65,7 +65,7 @@ use Page; class HomePage extends Page { - private static $icon_class = 'font-icon-p-home'; + private static $cms_icon_class = 'font-icon-p-home'; // ... } diff --git a/en/08_Changelogs/6.0.0.md b/en/08_Changelogs/6.0.0.md index 88cf1a61..03f46aae 100644 --- a/en/08_Changelogs/6.0.0.md +++ b/en/08_Changelogs/6.0.0.md @@ -694,26 +694,46 @@ As a result of these changes, the following classes have had their class hierarc |[`SubsiteXHRController`](api:SilverStripe\Subsites\Controller\SubsiteXHRController)|`LeftAndMain`|`AdminController`| |[`CMSExternalLinksController`](api:SilverStripe\ExternalLinks\Controllers\CMSExternalLinksController)|`Controller`|`AdminController`| -The `tree_class` configuration property on `LeftAndMain` and its subclasses has be renamed to [`model_class`](api:SilverStripe\Admin\LeftAndMain->model_class). This is used in methods like [`getRecord()`](api:SilverStripe\Admin\LeftAndMain::getRecord()) to get a record of the correct class. +The `tree_class` configuration property on `LeftAndMain` and its subclasses has be renamed to [`model_class`](api:SilverStripe\Admin\LeftAndMain->model_class), and a new [`getModelClass()`](api:SilverStripe\Admin\LeftAndMain::getModelClass()) method has been implemented to return it. This is used in methods like [`getRecord()`](api:SilverStripe\Admin\LeftAndMain::getRecord()) to get a record of the correct class. -#### Effects of this refactor in other classes +The `getModelClass()` method is the same method used in `ModelAdmin` to get the class for the currently accessed tab. This parity means you can predictably call `getModelClass()` on any initialised subclass of `LeftAndMain` and get an appropriate base class to work with. + +Some localisation keys have changed as a result of the refactor, so if you are using the localisation API to update localised text in a `LeftAndMain` controller, you may need to update the key for your customisation. + +#### Changes to`CMSMain` {#cmsmain-refactor} + +[`CMSMain`](api:SilverStripe\CMS\Controllers\CMSMain) is a subclass of `LeftAndMain` which provides the main way of managing page content in the CMS. It had a lot of hardcoded references to [`SiteTree`](api:SilverStripe\CMS\Model\SiteTree) and `Page`, despite most of its functionality being compatible with any class that uses the [`Hierarchy`](api:SilverStripe\ORM\Hierarchy\Hierarchy) extension. + +The hardcoded references have been removed, along with other assumptions that the model class for `CMSMain` was always a `SiteTree`. This opens up the way for a future enhancement to introduce a new generalised version of `CMSMain` that works with any model using the `Hierarchy` extension, which could be implemented in projects similar to how `ModelAdmin` is used. + +As a result of this, a lot of references to "page" have been removed from both API and UI elements. A full list of API changes can be found [at the bottom of the changelog](#api-removed-and-changed). + +#### Effects of these refactors in other classes Some classes outside of the `LeftAndMain` class hierarchy have also been affected by the refactoring: +- The `SiteTree.need_permission` configuration property has been removed. This wasn't used in permission checks anyway, so these permissions would have had to be separately checked in `canCreate()` to have the intended effect. If you were using this configuration property, implement a change to `canCreate()` in your `Page` class instead. - The `SiteTree.description` configuration property has been renamed to [`class_description`](api:SilverStripe\ORM\DataObject->class_description). This configuration has been added to `DataObject` along with the corresponding [`classDescription()`](api:SilverStripe\ORM\DataObject::classDescription()) and [`i18n_classDescription()`](api:SilverStripe\ORM\DataObject::i18n_classDescription()) methods. +- The [`BaseElement::getTypeNice()`](api:DNADesign\Elemental\Models\BaseElement::::getTypeNice()) method now calls `i18n_classDescription()` to get the text it will display. - The [`Hierarchy`](api:SilverStripe\ORM\Hierarchy\Hierarchy) extension now has a bunch of configuration and methods which used to be exclusive to `SiteTree`. #### 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 available - if you were using CSS selectors in those admin sections, you may need to change the way you're handling that. +This is the new super class for [`SiteConfigLeftAndMain`](api:SilverStripe\SiteConfig\SiteConfigLeftAndMain) and [`CMSProfileController`](api:SilverStripe\Admin\CMSProfileController). 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 some CSS selectors {#leftandmain-selectors} + +The `jstree-pageicon` CSS class is now `jstree-recordicon`, and the `page-icon` CSS class is now `record-icon`. + +Some of the CSS selectors that had been added to the edit forms in [`SiteConfigLeftAndMain`](api:SilverStripe\SiteConfig\SiteConfigLeftAndMain) and [`CMSProfileController`](api:SilverStripe\Admin\CMSProfileController) are no longer available - if you were using CSS selectors in those admin sections, you may need to change the way you're handling that. + ### Changes to password validation {#password-validation} #### `PasswordValidator` changes @@ -960,7 +980,18 @@ In order to better align the codebase in Silverstripe CMS with best practices, t |[`DataObject`](api:SilverStripe\ORM\DataObject)|`requireDefaultRecords`|`onRequireDefaultRecords`| |[`DataObject`](api:SilverStripe\ORM\DataObject)|`validate`|`updateValidate`| -If you have implemented any of those methods in an [`Extension`](api:SilverStripe\Core\Extension) subclass, you will need to rename it for it to continue working. +The following were additionally changed to match the renamed methods which invoke them: + +|Class that defined the hook|Old name|New name| +|---|---|---| +|[`CMSMain`](api:SilverStripe\CMS\Controllers\CMSMain)|`updateLinkPageAdd`|`updateLinkRecordAdd`| +|[`CMSMain`](api:SilverStripe\CMS\Controllers\CMSMain)|`updateSiteTreeAsUL`|`updateTreeAsUL`| +|[`CMSMain`](api:SilverStripe\CMS\Controllers\CMSMain)|`updateSiteTreeHints`|`updateTreeHints`| +|[`CMSMain`](api:SilverStripe\CMS\Controllers\CMSMain)|`updateCurrentPageID`|`updateCurrentRecordID`| + +The `updateCurrentRecordID` extension hook method is now invoked from [`LeftAndMain`](api:SilverStripe\Admin\LeftAndMain), which is a superclass of `CMSMain`. + +If you have implemented any of those methods in an [`Extension`](api:SilverStripe\Core\Extension) subclass, you will need to rename them for them to continue working. ### Strict typing for `Factory` implementations {#factory-strict-typing}