DOC Document standardised CMSEditLink method

en/02_Developer_Guides/00_Model/13_Managing_Records.md

@@ -12,6 +12,8 @@ of some other record or directly [in a ModelAdmin](../customising_the_admin_inte
 
 ## Getting an edit link
 
+The [`DataObject::CMSEditLink()`](api:SilverStripe\ORM\DataObject::CMSEditLink()) method will give you the edit link if there is one, but by default it just returns `null`.
+
 There is a [CMSEditLinkExtension](api:SilverStripe\Admin\CMSEditLinkExtension) specifically
 for the purpose of generating links to the edit forms of records. It operates on the assumption that your record is being edited in
 a [GridFieldDetailForm](../forms/field_types/gridfield#gridfielddetailform) in some `GridField` (be it on another record or in a

en/02_Developer_Guides/14_Files/07_File_Usage.md

@@ -59,7 +59,7 @@ class UsedOnTableExtension extends Extension
     // DataObject the File is used on.  This is useful for two reasons:
     // - It gives context more context, for instance if File is used on a Content block, it can be used to show the
     //   Page that Content Block is used on
-    // - The DataObject may not have a `CMSEditLink()` implementation, though the ancestor DataObject does.
+    // - The DataObject may not return a value from the `CMSEditLink()` method, though the ancestor DataObject does.
     //   The CMS frontend will fallback to using the Ancestor `CMSEditLink()` for when a user clicks on a row on
     //   the used on table
     protected function updateUsageAncestorDataObjects(array &$ancestorDataObjects, DataObject $dataObject)

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

@@ -167,7 +167,7 @@ $tabLink = $admin->getLinkForModelTab('product-category');
 > [getModelTabForModelClass()](api:SilverStripe\Admin\ModelAdmin::getModelTabForModelClass()) method
 > for your `ModelAdmin` subclass.
 
-You can also use the new [CMSEditLinkExtension](api:SilverStripe\Admin\CMSEditLinkExtension) to provide a `CMSEditLink()` method on the record - see [Managing Records](../model/managing_records#getting-an-edit-link).
+You can also use the new [CMSEditLinkExtension](api:SilverStripe\Admin\CMSEditLinkExtension) to update the value of the `CMSEditLink()` method on the record - see [Managing Records](../model/managing_records#getting-an-edit-link).
 
 ## Permissions
 

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

@@ -52,8 +52,9 @@ that is used to manage the object.
 This method exists so that when a user clicks on a link in the preview panel, the CMS
 edit form for the page the link leads to can be loaded. Unless your `DataObject` is
 [acting like a page](https://www.silverstripe.org/learn/lessons/v4/controller-actions-dataobjects-as-pages-1)
-this will likely not apply, but as this method is mandatory and public we may as well
-set it up correctly.
+this will likely not apply.
+
+You can leave the default implementation from `DataObject` which returns `null` if you want.
 
 If your object belongs to [a custom ModelAdmin](./modeladmin), the edit URL for the
 object is predictable enough to construct and return from this method as you'll see below.
@@ -63,9 +64,10 @@ nesting `GridField`s. For the below examples it is assumed you aren't using nest
 will handle those situations for you if you use it.
 
 > [!TIP]
-> The easiest way to implement `CMSEditLink()` is by
+> The easiest way to get a correct return value for `CMSEditLink()` is by
 > [using CMSEditLinkExtension](/developer_guides/model/managing_records#getting-an-edit-link).
-> But for completeness, the other examples below show alternative implementations.
+> That extension implements `updateCMSLink()` so you don't have to touch the `CMSEditLink()`
+> method directly at all.
 >
 > ```php
 > namespace App\Model;
@@ -83,15 +85,11 @@ will handle those situations for you if you use it.
 >         CMSEditLinkExtension::class,
 >     ];
 >
->     public function CMSEditLink()
->     {
->         // Get the value returned by the extension
->         return $this->extend('CMSEditLink')[0];
->     }
->
 >     // ...
 > }
 > ```
+>
+> For completeness, the other examples below show alternative implementations.
 
 #### `GetMimeType`
 
@@ -192,11 +190,6 @@ class Product extends DataObject implements CMSPreviewable
         return $link;
     }
 
-    public function CMSEditLink()
-    {
-        return null;
-    }
-
     public function getMimeType()
     {
         return 'text/html';
@@ -263,7 +256,7 @@ class Product extends DataObject implements CMSPreviewable
 {
     // ...
 
-    public function CMSEditLink()
+    public function CMSEditLink(): ?string
     {
         $admin = MyAdmin::singleton();
         return $admin->getCMSEditLinkForManagedDataObject($this);
@@ -523,11 +516,6 @@ class Product extends DataObject implements CMSPreviewable
         return $link;
     }
 
-    public function CMSEditLink()
-    {
-        return null;
-    }
-
     public function getMimeType()
     {
         return 'text/html';
@@ -592,10 +580,8 @@ class Product extends DataObject implements CMSPreviewable
 }
 ```
 
-The CMSEditLink doesn't matter so much for this implementation. It is required
-by the `CMSPreviewable` interface so some implementation must be provided, but
-you can safely return `null` or an empty string with no repercussions in this
-situation.
+The `CMSEditLink()` method doesn't matter so much for this implementation, so you can let
+it return the default value of `null`.
 
 #### The page template
 

en/08_Changelogs/6.0.0.md

@@ -185,6 +185,7 @@ SilverStripe\UserForms\Model\UserDefinedForm:
 
 - Native indexed PHP arrays can now be passed into templates and iterated over with `<% loop $MyArray %>`. Under the hood they are wrapped in [`ArrayList`](api:SilverStripe\View\ViewableData), so you can get the count using `$Count` and use `<% if $ArrayList %>` as a shortcut for `<% if $ArrayList.Count %>`. Other functionality from `ArrayList` such as filtering and sorting cannot be used on arrays since they don't have keys to filter or sort against.
 - Modules no longer need to have a root level `_config.php` or `_config` directory to be recognised as a Silverstripe CMS module. They will now be recognised as a module if they have a `composer.json` file with a `type` of `silverstripe-vendormodule` or `silverstripe-theme`.
+- A new [`DataObject::CMSEditLink()`](api:SilverStripe\ORM\DataObject::CMSEditLink()) method has been added, which returns `null` by default. This provides more consistency for that method which has previously been inconsistently applied to various subclasses of `DataObject`. See [managing records](/developer_guides/model/managing_records/#getting-an-edit-link) for more details about providing sane values for this method in your own subclasses.
 
 ## Dependency changes