MINOR GridField documentation

docs/en/topics/grid-field.md

@@ -2,7 +2,7 @@
 
 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.
 
-# Using GridField
+## Using GridField
 
 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.
 
@@ -19,11 +19,11 @@ This example might come from a Controller designed to manage the members of a gr
 
 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.
 
-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 25 records per page.
+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.
 
-## GridFieldConfig
+## GridFieldConfig: Portable configuration
 
-This grid create 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 4th argument, `$config`, where you can pass a `GridFieldConfig` object.
+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.
 
 This example creates exactly the same kind of grid as the previous example, but it creates the configuration manually:
 
@@ -49,10 +49,12 @@ If we wanted to make a simpler grid without pagination or filtering, we could do
 	$config->addComponent(new GridFieldPaginator(25));
 	$field = new GridField("Members", "Members of this group", $this->group->Members(), $config);
 
-A `GridFieldConfig` is made up of a new of `GridFieldComponent` objects.  `GridFieldComponent` is a family of interfaces.
+A `GridFieldConfig` is made up of a new of `GridFieldComponent` objects, which are described in the next chapter.
 
-## Built-in components
 
+## GridFieldComponent: Modular features
+
+`GridFieldComponent` is a family of interfaces.
 SilverStripe Framework comes with the following components that you can use out of the box.
 
 ### GridFieldDefaultColumns
@@ -91,7 +93,7 @@ You can also specify formatting replacements, to replace column contents with HT
 		'Email' => '<strong>$Email</strong>',
 	));
 	
-**EXPERIMENTAL API WARNING:** We will most likely refactor this so that this configuration methods are called on the component rather than the grid field.  Whoever does this should also update this documentation page. :-)
+**EXPERIMENTAL API WARNING:** We will most likely refactor this so that this configuration methods are called on the component rather than the grid field. 
 
 ### GridFieldSortableHeader
 
@@ -105,7 +107,40 @@ This component will add a header row with a text field filter for each column, l
 
 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.
 
-# Extending GridField with custom components
+### GridFieldAction
+
+TODO Describe component, including GridFieldAction_Edit/GridFieldAction_Delete
+
+### GridFieldRelationAdd
+
+This class is is responsible for adding objects to another object's has_many and many_many relation,
+as defined by the `[api:RelationList]` passed to the GridField constructor.
+Objects can be searched through an input field (partially matching one or more fields).
+Selecting from the results will add the object to the relation.
+Often used alongside `[api:GridFieldRelationDelete]` for detaching existing records from a relatinship.
+For easier setup, have a look at a sample configuration in `[api:GridFieldConfig_RelationEditor]`.
+
+### GridFieldRelationDelete
+
+Allows to detach an item from an existing has_many or many_many relationship.
+Similar to {@link GridFieldAction_Delete}, but allows to distinguish between 
+a "delete" and "detach" action in the UI - and to use both in parallel, if required.
+Requires the GridField to be populated with a `[api:RelationList]` rather than a plain DataList.
+Often used alongside `[api:GridFieldRelationAdd]` to add existing records to the relationship.
+
+### GridFieldPopupForms
+
+TODO Describe component, including how it relates to GridFieldAction_Edit. Point to GridFieldConfig_RelationEditor for easier defaults.
+
+### GridFieldTitle
+
+TODO
+
+### GridFieldExporter
+
+TODO
+
+## Extending GridField with custom components
 
 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`.
 

forms/gridfield/GridFieldConfig.php

@@ -1,7 +1,17 @@
 <?php
 /**
- * Description of GridFieldConfig
- *
+ * Encapsulates a collection of components following the {@link GridFieldComponent} interface.
+ * While the {@link GridField} itself has some configuration in the form of setters,
+ * most of the details are dealt with through components.
+ * 
+ * For example, you would add a {@link GridFieldPaginator} component to enable
+ * pagination on the listed records, and configure it through {@link GridFieldPaginator->setItemsPerPage()}.
+ * 
+ * In order to reduce the amount of custom code required, the framework provides
+ * some default configurations for common use cases:
+ * - {@link GridFieldConfig_Base} (added by default to GridField)
+ * - {@link GridFieldConfig_RecordEditor}
+ * - {@link GridFieldConfig_RelationEditor}
  */
 class GridFieldConfig {
 	
@@ -80,6 +90,10 @@ class GridFieldConfig {
 	}
 }
 
+/**
+ * A simple readonly, paginated view of records,
+ * with sortable and searchable headers.
+ */
 class GridFieldConfig_Base extends GridFieldConfig {
 
 	/**

forms/gridfield/GridFieldRelationAdd.php

@@ -1,9 +1,11 @@
 <?php
 /**
- * A GridFieldRelationAdd is responsible for adding objects to another object's has_many and many_many relation,
- * as defined by the RelationList passed to the GridField constructor.
+ * This class is is responsible for adding objects to another object's has_many and many_many relation,
+ * as defined by the {@link RelationList} passed to the GridField constructor.
  * Objects can be searched through an input field (partially matching one or more fields).
  * Selecting from the results will add the object to the relation.
+ * Often used alongside {@link GridFieldRelationDelete} for detaching existing records from a relatinship.
+ * For easier setup, have a look at a sample configuration in {@link GridFieldConfig_RelationEditor}.
  */
 class GridFieldRelationAdd implements GridField_HTMLProvider, GridField_ActionProvider, GridField_DataManipulator, GridField_URLHandler {
 	

forms/gridfield/GridFieldRelationDelete.php

@@ -3,7 +3,9 @@
  * Allows to detach an item from an existing has_many or many_many relationship.
  * Similar to {@link GridFieldAction_Delete}, but allows to distinguish between 
  * a "delete" and "detach" action in the UI - and to use both in parallel, if required.
- * Requires the GridField to be populated with a RelationList rather than a plain DataList.
+ * Requires the GridField to be populated with a {@link RelationList} rather than a plain {@link DataList}.
+ * Often used alongside {@link GridFieldRelationAdd} to add existing records to the relationship.
+ * For easier setup, have a look at a sample configuration in {@link GridFieldConfig_RelationEditor}.
  */
 class GridFieldRelationDelete implements GridField_ColumnProvider, GridField_ActionProvider {