From 5d057763c80e335688742be5deec6ecb7b704d8a 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 | 34 ++++++++++--------- .../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(+), 19 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 d53c6047d..f5c9d75b0 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. @@ -29,10 +31,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] - **app/src/Page.php** @@ -211,14 +209,12 @@ 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 use SilverStripe\Forms\GridField\GridFieldConfig_RecordViewer; @@ -236,16 +232,22 @@ $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 $config = GridFieldConfig_RecordEditor::create(); @@ -305,8 +307,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 a7b0021df..7d91f6836 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 e0308667a..2211d17e6 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 @@ -71,7 +71,7 @@ class GridFieldCustomAction extends AbstractGridFieldComponent implements GridFi public function getColumnContent($gridField, $record, $columnName) { - if (!$record->canEdit()) { + if (!$record->hasMethod('canEdit') || !$record->canEdit()) { return null; } @@ -222,7 +222,7 @@ class GridFieldCustomAction extends AbstractGridFieldComponent implements GridFi 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 590afc252..e1ff74440 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) @@ -75,6 +76,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