From b8d0ae575b39a23d750f1b06b4b4520517818db2 Mon Sep 17 00:00:00 2001 From: Guy Sartorelli Date: Thu, 15 Aug 2024 16:08:08 +1200 Subject: [PATCH] DOC Document standardised CMSEditLink method --- .../00_Model/13_Managing_Records.md | 6 ++- .../14_Files/07_File_Usage.md | 4 +- .../01_ModelAdmin.md | 2 +- .../04_Preview.md | 44 +++++++------------ en/08_Changelogs/6.0.0.md | 1 + 5 files changed, 23 insertions(+), 34 deletions(-) diff --git a/en/02_Developer_Guides/00_Model/13_Managing_Records.md b/en/02_Developer_Guides/00_Model/13_Managing_Records.md index 8fff6378c..26fde73f3 100644 --- a/en/02_Developer_Guides/00_Model/13_Managing_Records.md +++ b/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] diff --git a/en/02_Developer_Guides/14_Files/07_File_Usage.md b/en/02_Developer_Guides/14_Files/07_File_Usage.md index 304ab0125..917523da9 100644 --- a/en/02_Developer_Guides/14_Files/07_File_Usage.md +++ b/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) { diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/01_ModelAdmin.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/01_ModelAdmin.md index f9e5b2230..630bcb53f 100644 --- a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/01_ModelAdmin.md +++ b/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 diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_Preview.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_Preview.md index 631230965..d2cd785dc 100644 --- a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/04_Preview.md +++ b/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,14 @@ 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](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 `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 +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'; @@ -246,7 +239,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 +256,7 @@ class Product extends DataObject implements CMSPreviewable { // ... - public function CMSEditLink() + public function getCMSEditLink(): ?string { $admin = MyAdmin::singleton(); return $admin->getCMSEditLinkForManagedDataObject($this); @@ -430,7 +423,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 `` element). When a page loads, @@ -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 `getCMSEditLink()` method doesn't matter so much for this implementation, so you can let +it return the default value of `null`. #### The page template diff --git a/en/08_Changelogs/6.0.0.md b/en/08_Changelogs/6.0.0.md index 188e2526c..fdb76247a 100644 --- a/en/08_Changelogs/6.0.0.md +++ b/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::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. ## Dependency changes