DOC Document changes to CMSMain and LeftAndMain (#650)

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.
 

en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_CMS_Architecture.md

@@ -449,7 +449,7 @@ class MyAdmin extends LeftAndMain
 ```ss
 <%-- MyRecordInfo.ss --%>
 <div data-pjax-fragment="MyRecordInfo">
-    Current Record: $currentPage.Title
+    Current Record: $currentRecord.Title
 </div>
 ```
 

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:
             <ins class="jstree-checkbox">&nbsp;</ins>
             <ins class="jstree-icon">&nbsp;</ins>
             <span class="text">
-                <span class="jstree-pageicon"></span>
+                <span class="jstree-recordicon"></span>
                 <span class="item" title="Deleted">New Page</span>
                 <span class="badge deletedonlive">Deleted</span>
             </span>
@@ -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';
 
     // ...
 }

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}