Permalink
Browse files

MINOR GridField documentation

  • Loading branch information...
chillu committed Mar 5, 2012
1 parent 10a85f4 commit 6798d4070999065490374b7b859ff2239d62831f
@@ -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`.
@@ -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 @@ public function getComponentByType($type) {
}
}
+/**
+ * A simple readonly, paginated view of records,
+ * with sortable and searchable headers.
+ */
class GridFieldConfig_Base extends GridFieldConfig {
/**
@@ -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 {
@@ -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 {

0 comments on commit 6798d40

Please sign in to comment.