DOC Document standardised CMSEditLink method (#557)

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::getCMSEditLink()`](api:SilverStripe\ORM\DataObject::getCMSEditLink()) 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
@@ -73,11 +75,11 @@ class MyParentModel extends DataObject
 > If the `cms_edit_owner` is in some vendor dependency that you don't control, you can always apply `CMSEditLinkExtension`
 > and the `cms_edit_owner` via YAML.
 
-With the above code examples, you can call `CMSEditLink()` on any instance of `MyModel` or `MyParentModel` and it will produce
+With the above code examples, you can call `getCMSEditLink()` on any instance of `MyModel` or `MyParentModel` and it will produce
 an appropriate edit link for that record (assuming the relations are set up). This can be used, for example, in email reminders
 to update content, or as a link (available to admins) on the front-end to go straight to the edit form for the record.
 
-It is also useful when [making a previewable `DataObject`](../customising_the_admin_interface/preview/), as `CMSEditLink()` is
+It is also useful when [making a previewable `DataObject`](../customising_the_admin_interface/preview/), as `getCMSEditLink()` is
 one of the methods in the [CMSPreviewable](api:SilverStripe\ORM\CMSPreviewable) interface.
 
 > [!NOTE]

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

@@ -59,8 +59,8 @@ 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 CMS frontend will fallback to using the Ancestor `CMSEditLink()` for when a user clicks on a row on
+    // - The DataObject may not return a value from the `getCMSEditLink()` method, though the ancestor DataObject does.
+    //   The CMS frontend will fallback to using the Ancestor `getCMSEditLink()` 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 `getCMSEditLink()` 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

@@ -36,7 +36,7 @@ For a DataObject to be previewed using the preview panel there are a few prerequ
 
 ### `CMSPreviewable`
 
-The `CMSPreviewable` interface has three methods: `PreviewLink`, `CMSEditLink`, and
+The `CMSPreviewable` interface has three methods: `PreviewLink`, `getCMSEditLink`, and
 `getMimeType`.
 
 #### `PreviewLink`
@@ -47,13 +47,13 @@ item in the context of where it sits on the page using an anchor. You can also p
 some route specific for previewing this object, for example an action on the ModelAdmin
 that is used to manage the object.
 
-#### `CMSEditLink`
+#### `getCMSEditLink`
 
 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
-this will likely not apply, but as this method is mandatory and public we may as well
-set it up correctly.
+acting like a page 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 +63,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 `getCMSEditLink()` 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 `getCMSEditLink()`
+> method directly at all.
 >
 > ```php
 > namespace App\Model;
@@ -83,15 +84,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 +189,6 @@ class Product extends DataObject implements CMSPreviewable
         return $link;
     }
 
-    public function CMSEditLink()
-    {
-        return null;
-    }
-
     public function getMimeType()
     {
         return 'text/html';
@@ -246,7 +238,7 @@ class Product extends DataObject implements CMSPreviewable
 }
 ```
 
-The `CMSEditLink()` method is also very easy to implement, because the edit link used by
+The `getCMSEditLink()` method is also very easy to implement, because the edit link used by
 `ModelAdmin` is predictable.
 
 If you aren't using [CMSEditLinkExtension](/developer_guides/model/managing_records#getting-an-edit-link),
@@ -263,7 +255,7 @@ class Product extends DataObject implements CMSPreviewable
 {
     // ...
 
-    public function CMSEditLink()
+    public function getCMSEditLink(): ?string
     {
         $admin = MyAdmin::singleton();
         return $admin->getCMSEditLinkForManagedDataObject($this);
@@ -430,7 +422,7 @@ it in the context of the page it belongs to.
 
 For this example we will assume the `Product` class is `Versioned`.
 
-As discussed above, the `CMSEditLink` method is used to load the correct edit form
+As discussed above, the `getCMSEditLink` method is used to load the correct edit form
 in the CMS when you click on a link within the preview panel. This uses the
 `x-page-id` and `x-cms-edit-link` meta tags in the head of the page (assuming your
 page template calls `$MetaTags` in the `<head>` element). When a page loads,
@@ -523,11 +515,6 @@ class Product extends DataObject implements CMSPreviewable
         return $link;
     }
 
-    public function CMSEditLink()
-    {
-        return null;
-    }
-
     public function getMimeType()
     {
         return 'text/html';
@@ -592,10 +579,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 `getCMSEditLink()` 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,8 @@ 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::getCMSEditLink()`](api:SilverStripe\ORM\DataObject::getCMSEditLink()) 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.
+- The `CMSEditLink()` method on many `DataObject` subclasses has been renamed to `getCMSEditLink()`.
 
 ## Dependency changes