DOC Document new CMSEditLink trait

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

@@ -0,0 +1,88 @@
+---
+title: Managing Records
+summary: Manage your DataObject records
+icon: list-alt
+---
+
+# Managing Records
+
+Most records in Silverstripe CMS are managed [in a GridField](../forms/field_types/gridfield) - whether in the [GridField](api:SilverStripe\Forms\GridField\GridField)
+of some other record or directly [in a ModelAdmin](../customising_the_admin_interface/modeladmin/). The notable exceptions to this are
+[SiteConfig](api:SilverStripe\SiteConfig\SiteConfig) and [SiteTree](api:SilverStripe\CMS\Model\SiteTree).
+
+## Getting an edit link
+
+To get a link for editing a record, other than some exceptions like `SiteTree`, you have historically had to generate the link mostly
+from scratch with mostly hardcoded paths. This was especially tedious with nested `GridField` setups.
+
+As of Silverstripe CMS 4.12.0 there is a new [CMSEditLink](api:SilverStripe\Admin\CMSEditLink) trait 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
+`ModelAdmin`).
+
+When using this trait, your model must also declare its `canonical_edit_owner` as a
+[configuration property](../configuration/configuration/#configuration-properties). The value must either be the class name of the
+`ModelAdmin` that directly manages the record, or the `has_one` or `belongs_to` relation for the record that this model is edited
+on.
+
+If the `canonical_edit_owner` is a `has_one` or `belongs_to` relation, the class on the other end of the relation _must_ have
+a reciprocal `has_many` relation as documented in [Relations](./relations#has-many). For best results, use dot notation on the
+`has_many` relation. It must also implement a [getEditLinkForDataObject()](api:SilverStripe\Admin\CMSEditLink::getEditLinkForDataObject())
+method. The easiest way to do that is for it to use the `CMSEditLink` trait as well.
+
+** app/src/Model/MyModel.php **
+```php
+namespace MyProject\Model;
+
+use SilverStripe\Admin\CMSEditLink;
+use SilverStripe\ORM\DataObject;
+
+class MyModel extends DataObject
+{
+    use CMSEditLink;
+
+    private static string $canonical_edit_owner = 'Parent';
+
+    private static $has_one = [
+        'Parent' => MyParentModel::class,
+    ];
+}
+```
+
+** app/src/Model/MyParentModel.php **
+```php
+namespace MyProject\Model;
+
+use MyProject\Admin\MyModelAdmin;
+use SilverStripe\Admin\CMSEditLink;
+use SilverStripe\ORM\DataObject;
+
+class MyParentModel extends DataObject
+{
+    use CMSEditLink;
+
+    private static string $canonical_edit_owner = MyModelAdmin::class;
+
+    private static $has_many = [
+        'Children' => MyModel::class,
+    ];
+}
+```
+
+[hint]
+If the `canonical_edit_owner` is in some vendor dependency that you don't control, you can always implement a `getEditLinkForDataObject()`
+method in an [`Extension` applied to the class](../extending/extensions).
+[/hint]
+
+With the above code examples, you can call `CMSEditLink()` 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
+one of the methods in the [CMSPreviewable](api:SilverStripe\ORM\CMSPreviewable) interface.
+
+[info]
+`SiteTree` already implements `CMSEditLink`, which means any `canonical_edit_owner` pointing to a `has_one` or
+`belongs_to` relation of a `SiteTree` will work, assuming the page has a `GridField` for its reciprocal `has_many`
+relation with a `GridFieldDetailForm` in it.
+[/info]

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

@@ -62,6 +62,12 @@ string, as it won't be used. You can choose to return a valid edit link, but bec
 complexity of the way these links are generated it would be difficult to do so in a general,
 reusable way.
 
+[hint]
+As of Silverstripe CMS 4.12.0, you can
+[use the CMSEditLink trait](/developer_guides/model/data_model_and_orm/managing_records#getting-an-edit-link)
+to implement this method for you.
+[/hint]
+
 #### getMimeType
 In ~90% of cases will be 'text/html', but note it is also possible to display (for example)
 an inline PDF document in the preview panel.

en/04_Changelogs/4.12.0.md

@@ -106,6 +106,12 @@ SilverStripe\Assets\File:
     - MyFileExtension
 ```
 
+### New `CMSEditLink` trait
+
+The silverstripe/admin module has a new [CMSEditLink](api:SilverStripe\Admin\CMSEditLink) trait which makes it trivial to generate an edit link for any `DataObject` even in nested `GridField` setups. This is useful, for example, when [making a previewable `DataObject`](/developer_guides/customising_the_admin_interface/preview/) or as links in reminder emails for stale content.
+
+See [managing records](/developer_guides/model/data_model_and_orm/managing_records/) for a detailed explanation of this trait.
+
 ### Other new features {#other-features}
 
 - `extra_fields` data for a [ManyManyList](api:SilverStripe\ORM\ManyManyList) can now be set easily with the ORM - simply call the [setExtraData()](api:SilverStripe\ORM\ManyManyList::setExtraData()) method. See [the `many_many` documentation](/developer_guides/model/relations#many_many) for more details.