From 7a9ef16a0cc9afb696d1462fcef224eaf1724d82 Mon Sep 17 00:00:00 2001 From: Will Rossiter Date: Thu, 19 Sep 2013 23:38:09 +1200 Subject: [PATCH] Add how to for custom GridField row actions. --- docs/en/howto/gridfield-rowaction.md | 140 +++++++++++++++++++++++++++ docs/en/howto/index.md | 1 + docs/en/reference/grid-field.md | 1 + 3 files changed, 142 insertions(+) create mode 100644 docs/en/howto/gridfield-rowaction.md diff --git a/docs/en/howto/gridfield-rowaction.md b/docs/en/howto/gridfield-rowaction.md new file mode 100644 index 000000000..ba7e450a9 --- /dev/null +++ b/docs/en/howto/gridfield-rowaction.md @@ -0,0 +1,140 @@ +# How to add a custom action to a GridField row + +In a [GridField](/reference/grid-field) instance each table row can have a +number of actions located the end of the row such as edit or delete actions. +Each action is represented as a instance of a specific class +(e.g [api:GridFieldEditButton]) which has been added to the `GridFieldConfig` +for that `GridField` + +As a developer, you can create your own custom actions to be located alongside +the built in buttons. + +For example let's create a custom action on the GridField to allow the user to +perform custom operations on a row. + +## Basic GridFieldCustomAction boilerplate + +A basic outline of our new `GridFieldCustomAction.php` will look like something +below: + + :::php + 'col-buttons'); + } + + + public function getColumnMetadata($gridField, $columnName) { + if($columnName == 'Actions') { + return array('title' => ''); + } + } + + public function getColumnsHandled($gridField) { + return array('Actions'); + } + + public function getColumnContent($gridField, $record, $columnName) { + if(!$record->canEdit()) return; + + $field = GridField_FormAction::create( + $gridField, + 'CustomAction'.$record->ID, + 'Do Action', + "docustomaction", + array('RecordID' => $record->ID) + ); + + + return $field->Field(); + } + + public function getActions($gridField) { + return array('docustomaction'); + } + + public function handleAction(GridField $gridField, $actionName, $arguments, $data) { + if($actionName == 'docustomaction') { + // perform your action here + + // output a success message to the user + Controller::curr()->getResponse()->setStatusCode( + 200, + 'Do Custom Action Done.' + ); + } + } + } + +## Add the GridFieldCustomAction to the current `GridFieldConfig` + +While we're working on the code, to add this new action to the `GridField`, add +a new instance of the class to the [api:GridFieldConfig] object. The `GridField` +[Reference](/reference/grid-field) documentation has more information about +manipulating the `GridFieldConfig` instance if required. + + :::php + $config = GridFieldConfig::create(); + $config->addComponent(new GridFieldCustomAction()); + + $gridField = new GridField('Teams', 'Teams', $this->Teams(), $config); + +Now let's go back and dive through the `GridFieldCustomAction` class in more +detail. + +First thing to note is that our new class implements two interfaces, +[api:GridField_ColumnProvider] and [api:GridField_ActionProvider]. + +Each interface allows our class to define particular behaviors and is a core +concept of the modular `GridFieldConfig` system. + +The `GridField_ColumnProvider` implementation tells SilverStripe that this class +will provide the `GridField` with an additional column of information. By +implementing this interface we're required to define several methods to explain +where we want the column to exist and how we need it to be formatted. This is +done via the following methods: + + * `augmentColumns` + * `getColumnAttributes` + * `getColumnMetadata` + * `getColumnsHandled` + * `getColumnContent` + +In this example, we simply add the new column to the existing `Actions` column +located at the end of the table. Our `getColumnContent` implementation produces +a custom button for the user to click on the page. + +The second interface we add is `GridField_ActionProvider`. This interface is +used as we're providing a custom action for the user to take (`docustomaction`). +This action is triggered when a user clicks on the button defined in +`getColumnContent`. As with the `GridField_ColumnProvider` interface, by adding +this interface we have to define two methods to describe the behavior of the +action: + + * `getActions` returns an array of all the custom actions we want this class to + handle (i.e `docustomaction`) . + * `handleAction` method which will contain the logic for performing the + specific action (e.g publishing the row to a thirdparty service). + +Inside `handleAction` we have access to the current GridField and GridField row +through the `$arguments`. If your column provides more than one action (e.g two +links) both actions will be handled through the one `handleAction` method. The +called method is available as a parameter. + +To finish off our basic example, the `handleAction` method simply returns a +message to the user interface indicating a successful message. + +## Related + + * [GridField Reference](/reference/grid-field) + * [ModelAdmin: A UI driven by GridField](/reference/modeladmin) + * [Tutorial 5: Dataobject Relationship Management](/tutorials/5-dataobject-relationship-management) diff --git a/docs/en/howto/index.md b/docs/en/howto/index.md index 206be54aa..119625b61 100644 --- a/docs/en/howto/index.md +++ b/docs/en/howto/index.md @@ -19,3 +19,4 @@ the language and functions which are used in the guides. * [How to create a navigation menu](navigation-menu). Create primary navigation for your website. * [Paginating A List](pagination). Add pagination for an SS_List object. * [How to make a simple contact form](simple-contact-form). +* [How to add a custom action to a GridField row](gridfield-rowaction) \ No newline at end of file diff --git a/docs/en/reference/grid-field.md b/docs/en/reference/grid-field.md index d21f443a4..e8910786f 100644 --- a/docs/en/reference/grid-field.md +++ b/docs/en/reference/grid-field.md @@ -333,3 +333,4 @@ records, use the `DataObject->can...()` methods * [ModelAdmin: A UI driven by GridField](/reference/modeladmin) * [Tutorial 5: Dataobject Relationship Management](/tutorials/5-dataobject-relationship-management) + * [How to add a custom action to a GridField row](/howto/gridfield-rowaction)