DOC Document new CMSEditLinkExtension

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

@@ -0,0 +1,91 @@
+---
+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 [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
+`ModelAdmin`).
+
+When using this extension, 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` relation for the record that this model is edited on.
+
+If the `canonical_edit_owner` is a `has_one` 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 [getEditLinkForManagedDataObject()](api:SilverStripe\Admin\CMSEditLinkExtension::getEditLinkForManagedDataObject())
+method. The easiest way to do that is for it to have `CMSEditLinkExtension` applied as well.
+
+** app/src/Model/MyModel.php **
+```php
+namespace MyProject\Model;
+
+use SilverStripe\Admin\CMSEditLinkExtension;
+use SilverStripe\ORM\DataObject;
+
+class MyModel extends DataObject
+{
+    private static string $canonical_edit_owner = 'Parent';
+
+    private static $has_one = [
+        'Parent' => MyParentModel::class,
+    ];
+
+    private static $extensions = [
+        CMSEditLinkExtension::class,
+    ];
+}
+```
+
+** app/src/Model/MyParentModel.php **
+```php
+namespace MyProject\Model;
+
+use MyProject\Admin\MyModelAdmin;
+use SilverStripe\Admin\CMSEditLinkExtension;
+use SilverStripe\ORM\DataObject;
+
+class MyParentModel extends DataObject
+{
+    private static string $canonical_edit_owner = MyModelAdmin::class;
+
+    private static $has_many = [
+        'Children' => MyModel::class,
+    ];
+
+    private static $extensions = [
+        CMSEditLinkExtension::class,
+    ];
+}
+```
+
+[hint]
+If the `canonical_edit_owner` is in some vendor dependency that you don't control, you can always apply `CMSEditLinkExtension`
+and the `canonical_edit_owner` via yaml.
+[/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 has `CMSEditLinkExtension` applied, which means any `canonical_edit_owner` pointing to a `has_one` 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,36 @@ 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 CMSEditLinkExtension](/developer_guides/model/data_model_and_orm/managing_records#getting-an-edit-link).
+
+```php
+namespace MyProject\Model;
+
+use MyProject\Admin\MyModelAdmin;
+use SilverStripe\Admin\CMSEditLinkExtension;
+use SilverStripe\ORM\CMSPreviewable;
+use SilverStripe\ORM\DataObject;
+
+class MyParentModel extends DataObject implements CMSPreviewable
+{
+    private static string $canonical_edit_owner = MyModelAdmin::class;
+
+    private static $extensions = [
+        CMSEditLinkExtension::class,
+    ];
+
+    public function CMSEditLink()
+    {
+        // Get the value returned by the extension
+        return $this->extend('CMSEditLink')[0];
+    }
+}
+```
+
+[/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

@@ -116,6 +116,13 @@ SilverStripe\Assets\File:
 - [getLinkForModelTab()](api:SilverStripe\Admin\ModelAdmin::getLinkForModelTab()) similar to `getLinkForModelClass()`, except you pass in a specific model tab you want a link to. This is useful if your `ModelAdmin` has multiple tabs for managing a single class.
 - [isManagedModel](api:SilverStripe\Admin\ModelAdmin::isManagedModel()) returns `true` if the class or model tab passed in is managed by this `ModelAdmin`.
 EditForm
+
+### New `CMSEditLinkExtension`
+
+The silverstripe/admin module has a new [CMSEditLinkExtension](api:SilverStripe\Admin\CMSEditLinkExtension) 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 extension.
+
 ### 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.