From 1f29cda0752ea30af5fd3c01f3ae95b03ce1b731 Mon Sep 17 00:00:00 2001 From: Guy Sartorelli Date: Mon, 27 Nov 2023 15:36:04 +1300 Subject: [PATCH] DOC Document using GridField with arbitrary data --- .../03_Forms/Field_types/04_GridField.md | 32 +++++++++++-------- .../How_Tos/03_Create_a_GridFieldComponent.md | 2 +- .../04_Create_a_GridField_ActionProvider.md | 4 +-- en/04_Changelogs/5.2.0.md | 11 +++++++ 4 files changed, 32 insertions(+), 17 deletions(-) diff --git a/en/02_Developer_Guides/03_Forms/Field_types/04_GridField.md b/en/02_Developer_Guides/03_Forms/Field_types/04_GridField.md index c11a38ca6..73fccf69f 100644 --- a/en/02_Developer_Guides/03_Forms/Field_types/04_GridField.md +++ b/en/02_Developer_Guides/03_Forms/Field_types/04_GridField.md @@ -9,6 +9,8 @@ icon: table [GridField](api:SilverStripe\Forms\GridField\GridField) is Silverstripe CMS's implementation of data grids. The main purpose of this field type is to display tabular data in a format that is easy to view and modify. It can be thought of as a HTML table with some tricks. +Usually `GridField` is used with `DataObject` records - but it can be used with data that isn't represented by `DataObject` records as well. See [using `GridField` with arbitrary data](/developer_guides/forms/using_gridfield_with_arbitrary_data/) for more information. + [info] `GridField` powers the automated data UI of [ModelAdmin](api:SilverStripe\Admin\ModelAdmin). For more information about `ModelAdmin` see the [Customizing the CMS](/developer_guides/customising_the_admin_interface) guide. @@ -30,10 +32,6 @@ a `GridField` has almost no functionality. The `GridFieldConfig` instance and th responsible for all the user interactions including formatting data to be readable, modifying data and performing any actions such as deleting records. -[warning] -Some `GridField` components expect the list to be an instance of `DataList` and won't work with `ArrayList`. -[/warning] - ```php // app/src/PageType/MyPage.php namespace App\PageType; @@ -223,11 +221,10 @@ Similar to `GridFieldConfig_Base` with the addition support of the ability to vi a read-only view of the data record. [info] -The data row show must be a `DataObject` subclass. The fields displayed in the read-only view come from -`DataObject::getCMSFields()`. +Each record in the list must have an `ID` field, and the value of that field must be a positive integer. -The `DataObject` subclass displayed must define a `canView()` method that returns a boolean on whether the user can view -this record. +If the class representing your data has a `getCMSFields()` method, the return value of that method will be used for the fields displayed in the read-only view. +Otherwise, you'll need to pass in a [`FieldList`](api:SilverStripe\Forms\FieldList) to [`GridFieldDetailForm::setFields()`](api:SilverStripe\Forms\GridField\GridFieldDetailForm::setFields()). [/info] ```php @@ -246,13 +243,20 @@ $gridField->setConfig($config); Similar to `GridFieldConfig_RecordViewer` with the addition support to edit or delete each of the records. [info] -The data row show must be a `DataObject` subclass. The fields displayed in the edit view come from -`DataObject::getCMSFields()`. +Each record in the list must have an `ID` field, and the value of that field must be a positive integer. + +If the class representing your data has a `getCMSFields()` method, the return value of that method will be used for the fields displayed in the read-only view. +Otherwise, you'll need to pass in a [`FieldList`](api:SilverStripe\Forms\FieldList) to [`GridFieldDetailForm::setFields()`](api:SilverStripe\Forms\GridField\GridFieldDetailForm::setFields()). [/info] +[warning] +The class representing your data *must* implement [`DataObjectInterface`](api:SilverStripe\ORM\DataObjectInterface) so that your records can be edited. + +See [using `GridField` with arbitrary data](/developer_guides/forms/using_gridfield_with_arbitrary_data/) for more information. +[/warning] + [alert] -Permission control for editing and deleting the record uses the `canEdit()` and `canDelete()` methods on the -`DataObject` object. +Permission control for editing and deleting the record uses the `canEdit()` and `canDelete()` methods on the class that represents your data. [/alert] ```php @@ -319,8 +323,8 @@ $gridField->setConfig($config); ## `GridFieldDetailForm` -The `GridFieldDetailForm` component drives the record viewing and editing form. By default it takes its fields from the -[`DataObject->getCMSFields()`](api:SilverStripe\ORM\DataObject::getCMSFields()) method but can be customised to accept different fields via the +The `GridFieldDetailForm` component drives the record viewing and editing form. By default it takes its fields from the `getCMSFields()` method +(e.g. [`DataObject->getCMSFields()`](api:SilverStripe\ORM\DataObject::getCMSFields())) method but can be customised to accept different fields via the [GridFieldDetailForm::setFields()](api:SilverStripe\Forms\GridField\GridFieldDetailForm::setFields()) method. ```php diff --git a/en/02_Developer_Guides/03_Forms/How_Tos/03_Create_a_GridFieldComponent.md b/en/02_Developer_Guides/03_Forms/How_Tos/03_Create_a_GridFieldComponent.md index 3f9fd057f..1b28f0dde 100644 --- a/en/02_Developer_Guides/03_Forms/How_Tos/03_Create_a_GridFieldComponent.md +++ b/en/02_Developer_Guides/03_Forms/How_Tos/03_Create_a_GridFieldComponent.md @@ -37,7 +37,7 @@ Action providers run actions. Action providers often also implement `GridField_A Examples: -- A delete action provider that deletes a DataObject. +- A delete action provider that deletes a record. - An export action provider that will export the current list to a CSV file. See [Basic GridField custom action boilerplate](./create_a_gridfield_actionprovider#custom-action-boilerplate) for an example of implementing this component. diff --git a/en/02_Developer_Guides/03_Forms/How_Tos/04_Create_a_GridField_ActionProvider.md b/en/02_Developer_Guides/03_Forms/How_Tos/04_Create_a_GridField_ActionProvider.md index 550ca60ef..84f9bba6c 100644 --- a/en/02_Developer_Guides/03_Forms/How_Tos/04_Create_a_GridField_ActionProvider.md +++ b/en/02_Developer_Guides/03_Forms/How_Tos/04_Create_a_GridField_ActionProvider.md @@ -74,7 +74,7 @@ class GridFieldCustomAction extends AbstractGridFieldComponent implements public function getColumnContent($gridField, $record, $columnName) { - if (!$record->canEdit()) { + if (!$record->hasMethod('canEdit') || !$record->canEdit()) { return null; } @@ -230,7 +230,7 @@ class GridFieldCustomAction extends AbstractGridFieldComponent implements private function getCustomAction($gridField, $record) { - if (!$record->canEdit()) { + if (!$record->hasMethod('canEdit') || !$record->canEdit()) { return; } diff --git a/en/04_Changelogs/5.2.0.md b/en/04_Changelogs/5.2.0.md index 9c9662daf..e61755490 100644 --- a/en/04_Changelogs/5.2.0.md +++ b/en/04_Changelogs/5.2.0.md @@ -8,6 +8,7 @@ title: 5.2.0 (unreleased) - [Features and enhancements](#features-and-enhancements) - [New ORM features](#new-orm-features) + - [GridField components now work with arbitrary data](#gridfield-arbitrary-data) - [ErrorPage allowed codes configuration](#errorpage-allowed-codes-configuration) - [Create random passwords for new users](#create-random-passwords-for-new-users) - [Buttons to select all files and deselect all files](#bulk-action-buttons) @@ -77,6 +78,16 @@ $query->selectField('"my custom title" AS "Title"'); $query->setAllowCollidingFieldStatements(true); ``` +### GridField components now work with arbitrary data {#gridfield-arbitrary-data} + +It has historically been difficult to use a `GridField` to display data that isn't represented by `DataObject` records - and even more difficult to edit that data. + +We have removed several barriers to using the `GridField` to display arbitrary data, and improved error messaging when specific information cannot be dynamically identified, such as which columns to display and what form fields to use when viewing or editing data. + +This applies to all `GridFieldComponent` classes in `silverstripe/framework` except for [`GridFieldAddExistingAutocompleter`](api:SilverStripe\Forms\GridField\GridFieldAddExistingAutocompleter) and [`GridFieldLevelup`](api:SilverStripe\Forms\GridField\GridFieldLevelup), which both explicitly require the model class for the associated `GridField` to be a subclass of `DataObject`. + +See [using `GridField` with arbitrary data](/developer_guides/forms/using_gridfield_with_arbitrary_data/) for more information. + ### ErrorPage allowed codes configuration By default, all available error codes are present in the dropdown in the CMS. This can be overwhelming and there are a few (looking at you, 418) that can