Merge pull request #2430 from wilr/gridfieldactions

Add how to for custom GridField row actions.

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
+	<?php
+
+	class GridFieldCustomAction implements GridField_ColumnProvider, GridField_ActionProvider {
+
+		public function augmentColumns($gridField, &$columns) {
+			if(!in_array('Actions', $columns)) {
+				$columns[] = 'Actions';
+			}
+		}
+
+		public function getColumnAttributes($gridField, $record, $columnName) {
+			return array('class' => '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)

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)

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)