diff --git a/en/02_Developer_Guides/00_Model/13_Managing_Records.md b/en/02_Developer_Guides/00_Model/13_Managing_Records.md new file mode 100644 index 000000000..b71fd0e6d --- /dev/null +++ b/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] 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 ca9dc41ed..43a050349 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 @@ -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. diff --git a/en/04_Changelogs/4.12.0.md b/en/04_Changelogs/4.12.0.md index c250c58f1..ae6cf248e 100644 --- a/en/04_Changelogs/4.12.0.md +++ b/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.