Versions:

GridField

GridField is SilverStripe's implementation of data grids. The main purpose of the FormField is to display tabular data in a format that is easy to view and modify. It can be thought of as a HTML table with some tricks.

$field = new GridField($name, $title, $list);

GridField can only be used with $list data sets that are of the type SS_List such as DataList or ArrayList.

GridField powers the automated data UI of ModelAdmin. For more information about ModelAdmin see the Customizing the CMS guide.

Each GridField is built from a number of components grouped into the GridFieldConfig. Without any components, a GridField has almost no functionality. The GridFieldConfig instance and the attached GridFieldComponent are responsible for all the user interactions including formatting data to be readable, modifying data and performing any actions such as deleting records.

mysite/code/Page.php

<?php

class Page extends SiteTree {

    public function getCMSFields() {
        $fields = parent::getCMSFields();

        $fields->addFieldToTab('Root.Pages', 
            new GridField('Pages', 'All pages', SiteTree::get())
        ); 

        return $fields;
    }
}

This will display a bare bones GridField instance under Pages tab in the CMS. As we have not specified the GridField configuration, the default configuration is an instance of GridFieldConfig_Base which provides:

The configuration of those GridFieldComponent instances and the addition or subtraction of components is done through the getConfig() method on GridField.

mysite/code/Page.php

<?php

class Page extends SiteTree {

    public function getCMSFields() {
        $fields = parent::getCMSFields();

        $fields->addFieldToTab('Root.Pages', 
            $grid = GridField('Pages', 'All pages', SiteTree::get())
        );

        // GridField configuration
        $config = $grid->getConfig();

        //
        // Modification of existing components can be done by fetching that component.
        // Consult the API documentation for each component to determine the configuration
        // you can do.
        //
        $dataColumns = $config->getComponentByType('GridFieldDataColumns');

        $dataColumns->setDisplayFields(array(
            'Title' => 'Title',
            'Link'=> 'URL',
            'LastEdited' => 'Changed'
        ));

        return $fields;
    }
}

With the GridFieldConfig instance, we can modify the behavior of the GridField.

// `GridFieldConfig::create()` will create an empty configuration (no components).
$config = GridFieldConfig::create();

// add a component
$config->addComponent(new GridFieldDataColumns());

// Update the GridField with our custom configuration
$gridField->setConfig($config);

GridFieldConfig provides a number of methods to make setting the configuration easier. We can insert a component before another component by passing the second parameter.

$config->addComponent(new GridFieldFilterHeader(), 'GridFieldDataColumns');

We can add multiple components in one call.

$config->addComponents(
    new GridFieldDataColumns(), 
    new GridFieldToolbarHeader()
);

Or, remove a component.

$config->removeComponentsByType('GridFieldDeleteAction');

Fetch a component to modify it later on.

$component = $config->getComponentByType('GridFieldFilterHeader')

Here is a list of components for use bundled with the core framework. Many more components are provided by third-party modules and extensions.

Bundled GridFieldConfig

As a shortcut, GridFieldConfig subclasses can define a list of GridFieldComponent objects to use. This saves developers manually adding each component.

GridFieldConfig_Base

A simple read-only and paginated view of records with sortable and searchable headers.

$config = GridFieldConfig_Base::create();

$gridField->setConfig($config);

// Is the same as adding the following components..
// .. new GridFieldToolbarHeader()
// .. new GridFieldSortableHeader()
// .. new GridFieldFilterHeader()
// .. new GridFieldDataColumns()
// .. new GridFieldPageCount('toolbar-header-right')
// .. new GridFieldPaginator($itemsPerPage)

GridFieldConfig_RecordViewer

Similar to GridFieldConfig_Base with the addition support of the ability to view a GridFieldDetailForm containing a read-only view of the data record.

The data row show must be a DataObject subclass. The fields displayed in the read-only view come from DataObject::getCMSFields().

The DataObject class displayed must define a canView() method that returns a boolean on whether the user can view this record.

$config = GridFieldConfig_RecordViewer::create();

$gridField->setConfig($config);

// Same as GridFieldConfig_Base with the addition of
// .. new GridFieldViewButton(),
// .. new GridFieldDetailForm()

GridFieldConfig_RecordEditor

Similar to GridFieldConfig_RecordViewer with the addition support to edit or delete each of the records.

The data row show must be a DataObject subclass. The fields displayed in the edit view come from DataObject::getCMSFields().

Permission control for editing and deleting the record uses the canEdit() and canDelete() methods on the DataObject object.

$config = GridFieldConfig_RecordEditor::create();

$gridField->setConfig($config);

// Same as GridFieldConfig_RecordViewer with the addition of
// .. new GridFieldAddNewButton(),
// .. new GridFieldEditButton(),
// .. new GridFieldDeleteAction()

GridFieldConfig_RelationEditor

Similar to GridFieldConfig_RecordEditor, but adds features to work on a record's has-many or many-many relationships. As such, it expects the list used with the GridField to be a instance of RelationList.

$config = GridFieldConfig_RelationEditor::create();

$gridField->setConfig($config);

This configuration adds the ability to searched for existing records and add a relationship (GridFieldAddExistingAutocompleter).

Records created or deleted through the GridFieldConfig_RelationEditor automatically update the relationship in the database.

GridFieldDetailForm

The GridFieldDetailForm component drives the record viewing and editing form. It takes its' fields from DataObject->getCMSFields() method but can be customized to accept different fields via the GridFieldDetailForm->setFields method.

$form = $gridField->getConfig()->getComponentByType('GridFieldDetailForm');
$form->setFields(new FieldList(
    new TextField('Title')
));

many_many_extraFields

The component also has the ability to load and save data stored on join tables when two records are related via a "many_many" relationship, as defined through DataObject::$many_many_extraFields. While loading and saving works transparently, you need to add the necessary fields manually, they're not included in the getCMSFields() scaffolding.

These extra fields act like usual form fields, but need to be "namespaced" in order for the GridField logic to detect them as fields for relation extra data, and to avoid clashes with the other form fields.

The namespace notation is ManyMany[<extradata-field-name>], so for example ManyMany[MyExtraField].

<?php

class Team extends DataObject {

    private static $db = array(
        'Name' => 'Text'
    );

    public static $many_many = array(
        'Players' => 'Player'
    );
}

class Player extends DataObject {

    private static $db = array(
        'Name' => 'Text'
    );

    public static $many_many = array(
        'Teams' => 'Team'
    );

    public static $many_many_extraFields = array(
        'Teams' => array(
            'Position' => 'Text'
        )
    );

    public function getCMSFields() {
        $fields = parent::getCMSFields();

        if($this->ID) {
            $teamFields = singleton('Team')->getCMSFields();
            $teamFields->addFieldToTab(
                'Root.Main',
                // The "ManyMany[<extradata-name>]" convention
                new TextField('ManyMany[Position]', 'Current Position')
            );

            $config = GridFieldConfig_RelationEditor::create();
            $config->getComponentByType('GridFieldDetailForm')->setFields($teamFields);

            $gridField = new GridField('Teams', 'Teams', $this->Teams(), $config);
            $fields->findOrMakeTab('Root.Teams')->replaceField('Teams', $gridField);
        }

        return $fields;
    }
}

Flexible Area Assignment through Fragments

GridField layouts can contain many components other than the table itself, for example a search bar to find existing relations, a button to add those, and buttons to export and print the current data. The GridField has certain defined areas called fragments where these components can be placed.

The goal is for multiple components to share the same space, for example a header row. The built-in components:

  • header/footer: Renders in a <thead>/<tfoot>, should contain table markup
  • before/after: Renders before/after the actual <table>
  • buttons-before-left/buttons-before-right/buttons-after-left/buttons-after-right: Renders in a shared row before the table. Requires GridFieldButtonRow.

These built-ins can be used by passing the fragment names into the constructor of various components. Note that some GridFieldConfig classes will already have rows added to them. The following example will add a print button at the bottom right of the table.

$config->addComponent(new GridFieldButtonRow('after'));
$config->addComponent(new GridFieldPrintButton('buttons-after-right'));

Creating your own Fragments

Fragments are designated areas within a GridField which can be shared between component templates. You can define your own fragments by using a `\$DefineFragment' placeholder in your components' template. This example will simply create an area rendered before the table wrapped in a simple <div>.

<?php

class MyAreaComponent implements GridField_HTMLProvider {

    public function getHTMLFragments( $gridField) {
        return array(
            'before' => '<div class="my-area">$DefineFragment(my-area)</div>'
        );
    }
}

Please note that in templates, you'll need to escape the dollar sign on \$DefineFragment. These are specially processed placeholders as opposed to native template syntax.

Now you can add other components into this area by returning them as an array from your GridFieldComponent->getHTMLFragments()&version=3.1&module=framework) implementation:

<?php

class MyShareLinkComponent implements GridField_HTMLProvider {

    public function getHTMLFragments( $gridField) {        
        return array(
            'my-area' => '<a href>...</a>'
        );
    }
}

Your new area can also be used by existing components, e.g. the GridFieldPrintButton

new GridFieldPrintButton('my-component-area');

Creating a Custom GridFieldComponent

Customizing a GridField is easy, applications and modules can provide their own GridFieldComponent instances to add functionality. See How to Create a GridFieldComponent.

Creating a Custom GridField_ActionProvider

GridField_ActionProvider provides row level actions such as deleting a record. See How to Create a GridField_ActionProvider.

Saving the GridField State

GridState is a class that is used to contain the current state and actions on the GridField. It's transfered between page requests by being inserted as a hidden field in the form.

The GridState_Component sets and gets data from the GridState.

API Documentation