Skip to content
This repository
Browse code

ENHANCEMENT: Updates to the GridField documentation (fixes #7524)

  • Loading branch information...
commit 19772f3c0444f97e1549fd90cd2fd5dac1657f8a 1 parent d24ea5e
Stig Lindqvist authored August 30, 2012 chillu committed September 02, 2012
2  docs/en/reference/modeladmin.md
Source Rendered
@@ -217,6 +217,8 @@ For an introduction how to customize the CMS templates, see our [CMS Architectur
217 217
 
218 218
 ## Related
219 219
 
  220
+* [/topics/grid-field](GridField): The UI component powering ModelAdmin
  221
+* [/tutorials/5-dataobject-relationship-management](Tutorial 5: Dataobject Relationship Management)
220 222
 *  `[api:SearchContext]`
221 223
 * [genericviews Module](http://silverstripe.org/generic-views-module)
222 224
 * [Presentation about ModelAdmin at SupperHappyDevHouse Wellington](http://www.slideshare.net/chillu/modeladmin-in-silverstripe-23)
483  docs/en/topics/grid-field.md
Source Rendered
... ...
@@ -1,404 +1,263 @@
1  
-# Using and extending GridField
  1
+# Gridfield
2 2
 
3  
-The `GridField` is a flexible form field for creating tables of data.  It's new in SilverStripe 3.0 and replaces `ComplexTableField`, `TableListField`, and `TableField`.  It's built as a lean core with a number of components that you plug into it.  By selecting from the components that we provide or writing your own, you can grid a wide variety of grid controls.
  3
+Gridfield is SilverStripe's implementation of data grids. Its main purpose is to display tabular data
  4
+in a format that is easy to view and modify. It's a can be thought of as a HTML table with some tricks.
4 5
 
5  
-## Using GridField
  6
+It's built in a way that provides developers with an extensible way to display tabular data in a 
  7
+table and minimise the amount of code that needs to be written.
6 8
 
7  
-A GridField is created like any other field: you create an instance of the GridField object and add it to the fields of a form. At its simplest, GridField takes 3 arguments: field name, field title, and an `SS_List` of records to display.
  9
+In order to quickly get data-focused UIs up and running,
  10
+you might also be interested in the [/reference/modeladmin](ModelAdmin) class
  11
+which is driven largely by the `GridField` class explained here.
8 12
 
9  
-This example might come from a Controller designed to manage the members of a group:
  13
+## Overview
10 14
 
11  
-	:::php
12  
-	/**
13  
-	 * Form to display all members in a group
14  
-	 */
15  
-	public function MemberForm() {
16  
-		$field = new GridField("Members", "Members of this group", $this->group->Members());
17  
-		return new Form("MemberForm", $this, new FieldList($field), new FieldList());
18  
-	}
19  
-
20  
-Note that the only way to specify the data that is listed in a grid field is with `SS_List` argument.  If you want to customise the data displayed, you can do so by customising this object.
21  
-
22  
-This will create a read-only grid field that will show the columns specified in the Member's `$summary_fields` setting, and will let you sort and/or filter by those columns, as well as show pagination controls with a handful of records per page.
23  
-
24  
-## GridFieldConfig: Portable configuration
25  
-
26  
-The example above a useful default case, but when developing applications you may need to control the behaviour of your grid more precisely than this.  To this end, the `GridField` constructor allows for fourth argument, `$config`, where you can pass a `GridFieldConfig` object.
27  
-
28  
-This example creates exactly the same kind of grid as the previous example, but it creates the configuration manually:
29  
-
30  
-	:::php
31  
-	$config = GridFieldConfig::create();
32  
-	// Provide a header row with filter controls
33  
-	$config->addComponent(new GridFieldFilterHeader());
34  
-	// Provide a default set of columns based on $summary_fields
35  
-	$config->addComponent(new GridFieldDataColumns());
36  
-	// Provide a header row with sort controls
37  
-	$config->addComponent(new GridFieldSortableHeader());
38  
-	// Paginate results to 25 items per page, and show a footer with pagination controls
39  
-	$config->addComponent(new GridFieldPaginator(25));
40  
-	$field = new GridField("Members", "Members of this group", $this->group->Members(), $config);
41  
-
42  
-If we wanted to make a simpler grid without pagination or filtering, we could do so like this:
  15
+The `GridField` is a flexible form field for creating tables of data. It was introduced in 
  16
+SilverStripe 3.0 and replaced the `ComplexTableField`, `TableListField`, and `TableField` from 
  17
+previous versions of SilverStripe.
43 18
 
44  
-	:::php
45  
-	$config = GridFieldConfig::create();
46  
-	// Provide a default set of columns based on $summary_fields
47  
-	$config->addComponent(new GridFieldDataColumns());
48  
-	// Provide a header row with sort controls
49  
-	$config->addComponent(new GridFieldPaginator(25));
50  
-	$field = new GridField("Members", "Members of this group", $this->group->Members(), $config);
51  
-
52  
-A `GridFieldConfig` is made up of a new of `GridFieldComponent` objects, which are described in the next chapter.
53  
-
54  
-
55  
-## GridFieldComponent: Modular features
  19
+Each GridField is built from a number of components. Without any components, a GridField has almost no 
  20
+functionality. The components are responsible for formatting data to be readable and also modifying it.
56 21
 
57  
-`GridFieldComponent` is a family of interfaces.
58  
-SilverStripe Framework comes with the following components that you can use out of the box.
  22
+A gridfield with only the `GridFieldDataColumn` component will display a set of read-only columns 
  23
+taken from your list, without any headers or pagination. Large datasets don't fit to one 
  24
+page, so you could add a `GridFieldPaginator` to paginatate the data. Sorting is supported by adding
  25
+ a `GridFieldSortableHeader` that enables sorting on fields that can be sorted.
59 26
 
60  
-### GridFieldDataColumns
  27
+This document aims to explain the usage of GridFields with code examples.
61 28
 
62  
-This is the one component that, in most cases, you must include.  It provides the default columns, sourcing them from the underlying DataObject's `$summary_fields` if no specific configuration is provided.
  29
+<div class="hint" markdown='1'>
  30
+GridField can only be used with datasets that are of the type `SS_List` such as `DataList`
  31
+ or `ArrayList`
  32
+</div>
63 33
 
64  
-Without GridFieldDataColumns added to a GridField, it would have no columns whatsoever.  Although this isn't particularly useful most of the time, we have allowed for this for two reasons:
  34
+## Creating a base GridField
65 35
 
66  
- * You may have a grid whose fields are generated purely by another non-standard component.
67  
- * It keeps the core of the GridField lean, focused solely on providing APIs to the components.
  36
+A gridfield is often setup from a `Controller` that will output a form to the user. Even if there 
  37
+are no other HTML input fields for gathering data from users, the gridfield itself must have a 
  38
+`Form` to support interactions with it.
68 39
 
69  
-There are a number of methods that can be called on GridField to configure its behaviour.
70  
-
71  
-You can choose which fields you wish to display:
  40
+Here is an example where we display a basic gridfield with the default settings:
72 41
 
73 42
 	:::php
74  
-	$gridField->setDisplayFields(array(
75  
-		'ID' => 'ID',
76  
-		'FirstName' => 'First name',
77  
-		'Surname' => 'Surname',
78  
-		'Email' => 'Email',
79  
-		'LastVisited' => 'Last visited',
80  
-	));
  43
+	class GridController extends Page_Controller {
  44
+		
  45
+		public function index(SS_HTTPRequest $request) {
  46
+			$this->Content = $this->AllPages();
  47
+			return $this->render();
  48
+		}
  49
+		
  50
+		public function AllPages() {
  51
+			$gridField = new GridField('pages', 'All pages', SiteTree::get()); 
  52
+			return new Form($this, "AllPages", new FieldList($gridField), new FieldList());
  53
+		}
  54
+	}
81 55
 
82  
-You can specify formatting operations, for example choosing the format in which a date is displayed:
  56
+__Note:__ This is example code and the gridfield might not be styled nicely depending on the rest of
  57
+ the css included.
83 58
 
84  
-	:::php
85  
-	$gridField->setFieldCasting(array(
86  
-		'LastVisited' => 'Date->Ago',
87  
-	));
  59
+This gridfield will only contain a single column with the `Title` of each page. Gridfield by default
  60
+ uses the `DataObject::$display_fields` for guessing what fields to display.
88 61
 
89  
-You can also specify formatting replacements, to replace column contents with HTML tags:
  62
+Instead of modifying a core `DataObject` we can tell the gridfield which fields to display by 
  63
+setting the display fields on the `GridFieldDataColumns` component.
90 64
 
91 65
 	:::php
92  
-	$gridField->setFieldFormatting(array(
93  
-		'Email' => '<strong>$Email</strong>',
94  
-	));
  66
+	public function AllPages() {
  67
+		$gridField = new GridField('pages', 'All pages', SiteTree::get()); 
  68
+		$dataColumns = $gridField->getConfig()->getComponentByType('GridFieldDataColumns');
  69
+		$dataColumns->setDisplayFields(array(
  70
+			'Title' => 'Title',
  71
+			'URLSegment'=> 'URL',
  72
+			'LastEdited' => 'Changed'
  73
+		));
  74
+		return new Form($this, "AllPages", new FieldList($gridField), new FieldList());
  75
+	}
95 76
 	
96  
-**EXPERIMENTAL API WARNING:** We will most likely refactor this so that this configuration methods are called on the component rather than the grid field. 
  77
+We will now move onto what the `GridFieldConfig`s are and how to use them.
97 78
 
98  
-### GridFieldSortableHeader
  79
+----
99 80
 
100  
-This component will add a header to the grid with sort buttons.  It will detect which columns are sortable and only provide sort controls on those columns.
  81
+## GridFieldConfig
101 82
 
102  
-### GridFieldFilterHeader
  83
+A gridfields's behaviour and look all depends on what config we're giving it. In the above example 
  84
+we did not specify one, so it picked a default config called `GridFieldConfig_Base`.
103 85
 
104  
-This component will add a header row with a text field filter for each column, letting you filter the results with text searches.  It will detect which columns are filterable and only provide filter controls on those columns.
  86
+A config object is a container for `GridFieldComponents` which contain the actual functionality and
  87
+view for the gridfield.
105 88
 
106  
-### GridFieldPaginator
  89
+A config object can be either injected as the fourth argument of the GridField constructor, 
  90
+`$config` or set at a later stage by using a setter:
107 91
 
108  
-This component will limit output to a fixed number of items per page add a footer row with pagination controls. The constructor takes 1 argument: the number of items per page.
109  
-
110  
-### GridFieldDeleteButton
111  
-
112  
-TODO Describe component
113  
-
114  
-### GridFieldEditButton
115  
-
116  
-Adds a edit button to each row of the table. This needs another component to provide an edit interface - see GridFieldDetailForm for use within the CMS.
117  
-
118  
-### GridFieldRelationAdd
  92
+	:::php
  93
+	// On initialisation:
  94
+	$gridField = new GridField('pages', 'All pages', SiteTree::get(), GridFieldConfig_Base::create());
  95
+	// By a setter after initialisation:
  96
+	$gridField = new GridField('pages', 'All pages', SiteTree::get());
  97
+	$gridField->setConfig(GridFieldConfig_Base::create());
119 98
 
120  
-This class is is responsible for adding objects to another object's has_many and many_many relation,
121  
-as defined by the `[api:RelationList]` passed to the GridField constructor.
122  
-Objects can be searched through an input field (partially matching one or more fields).
123  
-Selecting from the results will add the object to the relation.
124  
-Often used alongside `[api:GridFieldRemoveButton]` for detaching existing records from a relatinship.
125  
-For easier setup, have a look at a sample configuration in `[api:GridFieldConfig_RelationEditor]`.
  99
+The framework comes shipped with some base GridFieldConfigs:
126 100
 
127  
-### GridFieldRemoveButton
  101
+### GridFieldConfig_Base
128 102
 
129  
-Allows to detach an item from an existing has_many or many_many relationship.
130  
-Similar to {@link GridFieldDeleteAction}, but allows to distinguish between 
131  
-a "delete" and "detach" action in the UI - and to use both in parallel, if required.
132  
-Requires the GridField to be populated with a `[api:RelationList]` rather than a plain DataList.
133  
-Often used alongside `[api:GridFieldAddExistingAutocompleter]` to add existing records to the relationship.
  103
+A simple read-only and paginated view of records with sortable and searchable headers.
134 104
 
135  
-### GridFieldDetailForm
  105
+	:::php
  106
+	$gridField = new GridField('pages', 'All pages', SiteTree::get(), GridFieldConfig_Base::create());
136 107
 
137  
-Provides add and edit forms for use within the CMS. This allows editing of the linked records. 
138  
-This only provides the actual add/edit forms, GridFieldEditButton is required to provide a button to link to the edit form, 
139  
-and GridFieldToolbarHeader is required to provide an add button.
  108
+The fields displayed are from `DataObject::getSummaryFields()`
140 109
 
141  
-### GridFieldToolbarHeader
  110
+### GridFieldConfig_RecordViewer
142 111
 
143  
-Adds a title bar to the top of the GridField, with optional "New" button. The New button doesn't provide any functionality with this component alone - see GridFieldDetailForm.
  112
+Similar to `GridFieldConfig_Base` with the addition support of:
144 113
 
145  
-### GridFieldExportButton
  114
+ - View read-only details of individual records.
146 115
 
147  
-Adds an "Download as CSV" button. This will save the current List shown in the GridField as CSV. Takes the 
  116
+The fields displayed in the read-only view is from `DataObject::getCMSFields()`
148 117
 
149  
-## Extending GridField with custom components
  118
+	:::php
  119
+	$gridField = new GridField('pages', 'All pages', SiteTree::get(), GridFieldConfig_RecordViewer::create());
150 120
 
151  
-You can create a custom component by building a class that implements one or more of the following interfaces: `GridField_HTMLProvider`, `GridField_ColumnProvider`, `GridField_ActionProvider`, or `GridField_DataManipulator`.
  121
+### GridFieldConfig_RecordEditor
152 122
 
153  
-All of the methods expected by these interfaces take `$gridField` as their first argument.  The gridField related to the component isn't set as a property of the component instance.  This means that you can re-use the same component object across multiple `GridField`s, if that is appropriate.
  123
+Similar to `GridFieldConfig_RecordViewer` with the addition support of:
154 124
 
155  
-It's common for a component to implement several of these interfaces in order to provide the complete implementation of a feature.  For example, `GridFieldSortableHeader` implements the following:
  125
+ - Viewing and changing an individual records data.
  126
+ - Deleting a record
156 127
 
157  
- * `GridField_HTMLProvider`, to generate the header row including the GridField_Action buttons
158  
- * `GridField_ActionProvider`, to define the sortasc and sortdesc actions that add sort column and direction to the state.
159  
- * `GridField_DataManipulator`, to alter the sorting of the data list based on the sort column and direction values in the state.
  128
+	:::php
  129
+	$gridField = new GridField('pages', 'All pages', SiteTree::get(), GridFieldConfig_RecordEditor::create());
160 130
 
161  
- ### GridFieldAddExistingAutocompleter
  131
+The fields displayed in the edit form are from `DataObject::getCMSFields()`
  132
+ 
  133
+### GridFieldConfig_RelationEditor
162 134
 
163  
-A GridFieldAddExistingAutocompleter is responsible for adding objects to another object's `has_many` and `many_many` relation,
164  
-as defined by the `[api:RelationList]` passed to the GridField constructor.
165  
-Objects can be searched through an input field (partially matching one or more fields).
166  
-Selecting from the results will add the object to the relation.
  135
+Similar to `GridFieldConfig_RecordEditor`, but adds features to work on a record's has-many or 
  136
+many-many relationships.
167 137
 
168  
- 	:::php
169  
- 	$group = Group::get()->First();
170  
- 	$config = GridFieldConfig::create()->addComponent(new GridFieldAddExistingAutocompleter(array('FirstName', 'Surname', 'Email'));
171  
- 	$gridField = new GridField('Members', 'Members', $group->Members(), $config);
  138
+The relations can be:
172 139
 
173  
-## Component interfaces
  140
+- Searched for existing records and add a relationship
  141
+- Detach records from the relationship (rather than removing them from the database)
  142
+- Create new related records and automatically add the relationship.
174 143
 
175  
-### GridField_HTMLProvider
  144
+	:::php
  145
+	$gridField = new GridField('pages', 'All pages', SiteTree::get(), GridFieldConfig_RecordEditor::create());
176 146
 
177  
-The core GridField provides the following basic HTML:
  147
+The fields displayed in the edit form are from `DataObject::getCMSFields()`
178 148
 
179  
- * A `<table>`, with an empty `<thead>` and `<tfoot>`
180  
- * A collection of `<tr>`s, based on the grid's data list, each of which will contain a collection or `<td>`s based on the grid's columns.
  149
+## GridFieldComponents
181 150
 
182  
-The `GridField_HTMLProvider` component can provide HTML that goes into the `<thead>` or `<tfoot>`, or that appears before or after the table itself.
  151
+GridFieldComponents the actual workers in a gridfield. They can be responsible for:
183 152
 
184  
-It should define the getHTMLFragments() method, which should return a map.  The map keys are can be 'header', 'footer', 'before', or 'after'.  The map values should be strings containing the HTML content to put into each of these spots.  Only the keys for which you wish to provide content need to be defined.
  153
+ - Output some HTML to be rendered
  154
+ - Manipulate data
  155
+ - Recieve actions
  156
+ - Display links
185 157
 
186  
-For example, this components will add a footer row to the grid field, thanking the user for their patronage.  You can see that we make use of `$gridField->getColumnCount()` to ensure that the single-cell row takes up the full width of the grid.
  158
+Components are added and removed from a config by setters and getters.
187 159
 
188 160
 	:::php
189  
-	class ThankYouForUsingSilverStripe implements GridField_HTMLProvider {
190  
-		public function getHTMLFragments($gridField) {
191  
-			$colSpan = $gridField->getColumnCount();
192  
-			return array(
193  
-				'footer' => '<tr><td colspan="' . $colSpan . '">Thank you for using SilverStripe!</td></tr>',
194  
-			);
195  
-		}
196  
-	}
197  
-	
198  
-If you wish to add CSS or JavaScript for your component, you may also make `Requirements` calls in this method.
199  
-
200  
-### Defining new fragments
201  
-
202  
-Sometimes it is helpful to have one component write HTML into another component.  For example, you might have an action header row at the top of your GridField that several different components may define actions for.
203  
-
204  
-To do this, you can put the following code into one of the HTML fragments returned by an HTML provider.
205  
-
206  
-	$DefineFragment(fragment-name)
207  
-
208  
-Other `GridField_HTMLProvider` components can now write to `fragment-name` just as they would write to footer, etc.  Fragments can be nested.
  161
+	$config = GridFieldConfig::create();
209 162
 
210  
-For example, this component creates a `header-actions` fragment name that can be populated by other components:
  163
+	// Add the base data columns to the gridfield
  164
+	$config->addComponent(new GridFieldDataColumns());
  165
+	$gridField = new GridField('pages', 'All pages', SiteTree::get(), $config);
211 166
 
  167
+It's also possible to insert a component before another component.
  168
+	
212 169
 	:::php
213  
-	class HeaderActionComponent implements GridField_HTMLProvider {
214  
-		public function getHTMLFragments($gridField) {
215  
-			$colSpan = $gridField->getColumnCount();
216  
-			array(
217  
-				"header" => "<tr><td colspan=\"$colspan\">\$DefineFragment(header-actions)</td></tr>"
218  
-			);
219  
-		}
220  
-	}
  170
+	$config->addComponent(new GridFieldFilterHeader(), 'GridFieldDataColumns');
221 171
 	
222  
-This is a simple example of how you might populate that new fragment:
  172
+Adding multiple components in one call:
223 173
 
224 174
 	:::php
225  
-	class AddNewActionComponent implements GridField_HTMLProvider {
226  
-		public function getHTMLFragments($gridField) {
227  
-			$colSpan = $gridField->getColumnCount();
228  
-			array(
229  
-				"header-actions" => "<button>Add new</button>"
230  
-			);
231  
-		}
232  
-	}
233  
-
234  
-If you write to a fragment that isn't defined anywhere, or you create a circular dependency within fragments, an exception will be thrown.
  175
+	$config->addComponents(new GridFieldDataColumns(), new GridFieldToolbarHeader());
235 176
 
236  
-### GridField_ColumnProvider
237  
-
238  
-By default, a grid contains no columns.  All the columns displayed in a grid will need to be added by an appropriate component.
  177
+Removing a component:
239 178
 
240  
-For example, you may create a grid field with several components providing columns:
  179
+	:::php
  180
+	$config->removeComponentsByType('GridFieldToolbarHeader');
241 181
 
242  
- * `GridFieldDataColumns` could provide basic data columns.
243  
- * An editor component could provide a column containing action buttons on the right.
244  
- * A multiselect component clould provide a column showing a checkbox on the left.
  182
+For more information, see the [API for GridFieldConfig](http://api.silverstripe.org/3.0/framework/GridFieldConfig.html).
245 183
 
246  
-In order to provide additional columns, your component must implement `GridField_ColumnProvider`.
  184
+Here is a list of components for generic use:
247 185
 
248  
-First you need to define 2 methods that specify which columns need to be added:
  186
+ - `[api:GridFieldToolbarHeader]`
  187
+ - `[api:GridFieldSortableHeader]`
  188
+ - `[api:GridFieldFilterHeader]`
  189
+ - `[api:GridFieldDataColumns]`
  190
+ - `[api:GridFieldDeleteAction]`
  191
+ - `[api:GridFieldViewButton]`
  192
+ - `[api:GridFieldEditButton]`
  193
+ - `[api:GridFieldPaginator]`
  194
+ - `[api:GridFieldDetailForm]`
249 195
 
250  
- * **`function augmentColumns($gridField, &$columns)`:** Update the `$columns` variable (passed by reference) to include the names of the additional columns that this component provides.  You can insert the values at any point you wish, for example if you need to add a column to the left of the grid, rather than the right.
251  
- * **`function getColumnsHandled($gridField)`:** Return an array of the column names.  This overlaps with the function of `augmentColumns()` but leaves out any information about the order in which the columns are added.
  196
+## Creating a custom GridFieldComponent
252 197
 
253  
-Then you define 3 methods that specify what should be shown in these columns:
  198
+A single component often uses a number of interfaces.
254 199
 
255  
- * **`function getColumnContent($gridField, $record, $columnName)`:** Return the HTML content of this column for the given record.  Like `GridField_HTMLProvider`, you may make `Requirements` calls in this method.
256  
- * **`function getColumnAttributes($gridField, $record, $columnName)`:** Return a map of the HTML attributes to add to this column's `<td>` for this record.  Most commonly, this is used to specify a colspan.
257  
- * **`function getColumnMetadata($gridField, $columnName)`:** Return a map of the metadata about this column.  Right now, only one piece of meta-data is specified, "title".  Other components (such as those responsible for generating headers) may fetch the column meta-data for their own purposes.
  200
+### GridField_HTMLProvider
258 201
 
259  
-### GridField_ActionProvider
  202
+Provides HTML for the header/footer rows in the table or before/after the template.
260 203
 
261  
-Most grid fields worthy of the name are interactive in some way.  Users might able to page between results, sort by different columns, filter the results or delete records.  Where this interaction necessitates an action on the server side, the following generally happens:
  204
+Examples:
262 205
 
263  
- * The user triggers an action.
264  
- * That action updates the state, database, or something else.
265  
- * The GridField is re-rendered with that new state.
  206
+ - A header html provider displays a header before the table
  207
+ - A pagination html provider displays pagination controls under the table
  208
+ - A filter html fields displays filter fields on top of the table
  209
+ - A summary html field displays sums of a field at the bottom of the table
  210
+ 
  211
+### GridField_ColumnProvider
266 212
 
267  
-These actions can be provided by components that implement the `GridField_ActionProvider` interface.
  213
+Add a new column to the table display body, or modify existing columns. Used once per record/row.
268 214
 
269  
-An action is defined by two things: an action name, and zero or more named arguments.  There is no built-in notion of a record-specific or column-specific action, but you may choose to define an argument such as ColumnName or RecordID in order to implement these.
  215
+Examples:
270 216
 
271  
-To provide your actions, define the following two functions:
  217
+ - A data columns provider that displays data from the list in rows and columns.
  218
+ - A delete button column provider that adds a delete button at the end of the row
272 219
 
273  
- * **`function getActions($gridField)`:** Return a list of actions that this component provides.  There is no namespacing on these actions, so you need to ensure that they don't conflict with other components.
274  
- * **`function handleAction(GridField $gridField, $actionName, $arguments, $data)`:** Handle the action defined by `$actionName` and `$arguments`.  `$data` will contain the full data from the form, if you need to access that.
  220
+### GridField_ActionProvider
275 221
 
276  
-To call your actions, you need to create `GridField_FormAction` elsewhere in your component.  Read more about them below.
  222
+Action providers runs actions, some examples are:
277 223
 
278  
-**EXPERIMENTAL API WARNING:** handleAction implementations often contain a big switch statement and this interface might be amended on, such that each action is defined in a separate method.  If we do this, it will be done before 3.0 stable so that we can lock down the API, but early adopters should be aware of this potential for change!
  224
+ - A delete action provider that deletes a DataObject.
  225
+ - An export action provider that will export the current list to a CSV file.
279 226
 
280 227
 ### GridField_DataManipulator
281 228
 
282  
-A `GridField_DataManipulator` component can modify the data list.  For example, a paginating component can apply a limit, or a sorting component can apply a sort.  Generally, the data manipulator will make use of to `GridState` variables to decide how to modify the data list (see GridState below).
283  
-
284  
- * **`getManipulatedData(GridField $gridField, SS_List $dataList)`:** Given this grid's data list, return an updated list to be used with this grid.
285  
-
286  
-### GridField_URLHandler
287  
-
288  
-Sometimes an action isn't enough: you need to provide additional support URLs for the grid.  These URLs may return user-visible content, for example a pop-up form for editing a record's details, or they may be support URLs for front-end functionality, for example a URL that will return JSON-formatted data for a javascript grid control.
289  
-
290  
-To build these components, you should implement the `GridField_URLHandler` interface.  It only specifies one method: `getURLHandlers($gridField)`.  This method should return an array similar to the `RequestHandler::$url_handlers` static.  The action handlers should also be defined on the component; they will be passed `$gridField` and `$request`.
  229
+Modifies the data list. In general, the data manipulator will make use of `GridState` variables
  230
+to decide how to modify the data list.
291 231
 
292  
-Here is an example in full.  The actual implementation of the view and edit forms isn't included.
  232
+Examples:
293 233
 
294  
-	:::php
295  
-	/**
296  
-	 * Provides view and edit forms at GridField-specific URLs.  These can be placed into pop-ups by an appropriate front-end.
297  
-	 * 
298  
-	 * The URLs provided will be off the following form:
299  
-	 *  - <FormURL>/field/<GridFieldName>/item/<RecordID>
300  
-	 *  - <FormURL>/field/<GridFieldName>/item/<RecordID>/edit
301  
-	 */
302  
-	class GridFieldDetailForm implements GridField_URLHandler {
303  
-		public function getURLHandlers($gridField) {
304  
-			return array(
305  
-				'item/$ID' => 'handleItem',
306  
-			);
307  
-		}
  234
+ - A paginating data manipulator can apply a limit to a list (show only 20 records)
  235
+ - A sorting data manipulator can sort the Title in a descending order.
308 236
 
309  
-		public function handleItem($gridField, $request) {
310  
-			$record = $gridField->getList()->byId($request->param("ID"));
311  
-			return new GridFieldDetailForm_ItemRequest($gridField, $this, $record);
312  
-		}
313  
-	}
  237
+### GridField_URLHandler
314 238
 
315  
-	class GridFieldDetailForm_ItemRequest extends RequestHandler {
316  
-		protected $gridField;
317  
-		protected $component;
318  
-		protected $record;
  239
+Sometimes an action isn't enough, we need to provide additional support URLs for the grid. It 
  240
+has a list of URL's that it can handle and the GridField passes request on to URLHandlers on matches.
319 241
 
320  
-		public function __construct($gridField, $component, $record) {
321  
-			$this->gridField = $gridField;
322  
-			$this->component = $gridField;
323  
-			$this->record = $record;
324  
-			parent::__construct();
325  
-		}
  242
+Examples:
326 243
 
327  
-		public function index() {
328  
-			echo "view form for record #" . $record->ID;
329  
-		}
  244
+ - A pop-up form for editing a record's details.
  245
+ - JSON formatted data used for javascript control of the gridfield.
330 246
 
331  
-		public function edit() {
332  
-			echo "edit form for record #" . $record->ID;
333  
-		}
334  
-	}
  247
+## GridField_FormAction
335 248
 
336  
-## Other tools
  249
+This object is used for creating actions buttons, for example a delete button. When a user clicks on
  250
+a FormAction, the gridfield finds a `GridField_ActionProvider` that listens on that action. 
  251
+`GridFieldDeleteAction` have a pretty basic implementation of how to use a Form action.
337 252
 
338 253
 ### GridState
339 254
 
340  
-Each `GridField` object has a key-store available handled by the `GridState` class.  You can call `$gridField->State` to get access to this key-store.  You may reference any key name you like, and do so recursively to any depth you like:
341  
-
342  
-	:::php
343  
-	$gridField->State->Foo->Bar->Something = "hello";
344  
-
345  
-Because there is no schema for the grid state, its good practice to keep your state within a namespace, by first accessing a state key that has the same name as your component class.  For example, this is how the `GridFieldSortableHeader` component manages its sort state.
346  
-
347  
-	:::php
348  
-	$state = $gridField->State->GridFieldSortableHeader;
349  
-	$state->SortColumn = $arguments['SortColumn'];
350  
-	$state->SortDirection = 'asc';
351  
-	
352  
-	...
353  
-	
354  
-	$state = $gridField->State->GridFieldSortableHeader;
355  
-	if ($state->SortColumn == "") {
356  
-		return $dataList;
357  
-	} else {
358  
-		return $dataList->sort($state->SortColumn, $state->SortDirection)
359  
-	}
360  
-
361  
-When checking for empty values in the state, you should compare the state value to the empty string.  This is because state values always return a `GridState_Data` object, and comparing to an empty string will call its `__toString()` method.
362  
-
363  
-	:::php
364  
-	// Good
365  
-	if ($state->SortColumn == "") { ... }
366  
-	// Bad
367  
-	if (!$state->SortColumn) { ... }
368  
-	
369  
-**NOTE:** Under the hood, `GridState` is a subclass of hidden field that provides a `getData()` method that returns a `GridState_Data` object.  `$gridField->getState()` returns that `GridState_Data` object.
370  
-
371  
-### GridField_Action
372  
-
373  
-The `GridField_Action` class is a subclass of `FormAction` that will provide a button designed to trigger a grid field action.  This is how you can link user-interface controls to the actions defined in `GridField_ActionProvider` components.
374  
-
375  
-To create the action button, instantiate the object with the following arguments to your constructor:
376  
-
377  
- * grid field
378  
- * button name
379  
- * button label
380  
- * action name
381  
- * action arguments (an array of named arguments)
382  
-
383  
-For example, this could be used to create a sort button:
384  
-
385  
-	:::php
386  
-	$field = new GridField_Action(
387  
-		$gridField, 'SetOrder'.$columnField, $title, 
388  
-		"sortasc", array('SortColumn' => $columnField));
389  
-
390  
-Once you have created your button, you need to render it somewhere.  You can include the `GridField_Action` object in a template that is being rendered, or you can call its `Field()` method to generate the HTML content.
391  
-
392  
-	:::php
393  
-	$output .= $field->Field();
394  
-	
395  
-Most likely, you will do this in `GridField_HTMLProvider::getHTMLFragments()` or `GridField_ColumnProvider::getColumnContent()`.
  255
+Gridstate is a class that is used to contain the current state and actions on the gridfield. It's 
  256
+transfered between page requests by being inserted as a hidden field in the form.
396 257
 
397  
-### GridField Helper Methods
  258
+A GridFieldComponent sets and gets data from the GridState.
398 259
 
399  
-The GridField class provides a number of methods that are useful for components.  See [the API documentation](api:GridField) for the full list, but here are a few:
  260
+## Related
400 261
 
401  
- * **`getList()`:** Returns the data list for this grid, without the state modifications applied.
402  
- * **`getState()`:** Also called as `$gridField->State`, returns the `GridState_Data` object storing the current state.
403  
- * **`getColumnMetadata($column)`:** Return the metadata of the given column.
404  
- * **`getColumnCount()`:** Returns the number of columns
  262
+ * [/reference/modeladmin](ModelAdmin: A UI driven by GridField)
  263
+ * [/tutorials/5-dataobject-relationship-management](Tutorial 5: Dataobject Relationship Management)

0 notes on commit 19772f3

Please sign in to comment.
Something went wrong with that request. Please try again.