diff --git a/docs/en/howto/customize-cms-pages-list.md b/docs/en/howto/customize-cms-pages-list.md new file mode 100644 index 000000000..0f5eaec1c --- /dev/null +++ b/docs/en/howto/customize-cms-pages-list.md @@ -0,0 +1,68 @@ +# Howto: Customize the Pages List in the CMS + +The pages "list" view in the CMS is a powerful alternative to visualizing +your site's content, and can be better suited than a tree for large flat +hierarchies. A good example would be a collection of news articles, +all contained under a "holder" page type, a quite common pattern in SilverStripe. + +The "list" view allows you to paginate through a large number of records, +as well as sort and filter them in a way that would be hard to achieve in a tree structure. +But sometimes the default behaviour isn't powerful enough, and you want a more +specific list view for certain page types, for example to sort the list by +a different criteria, or add more columns to filter on. The resulting +form is mainly based around a `[GridField](/reference/grid-field)` instance, +which in turn includes all children in a `[DataList](/topics/datamodel)`. +You can use these two classes as a starting point for your customizations. + +Here's a brief example on how to add sorting and a new column for a +hypothetical `NewsPageHolder` type, which contains `NewsPage` children. + + :::php + // mysite/code/NewsPageHolder.php + class NewsPageHolder extends Page { + static $allowed_children = array('NewsPage'); + } + + // mysite/code/NewsPage.php + class NewsPage extends Page { + static $has_one = array( + 'Author' => 'Member', + ); + } + +We'll now add an `Extension` subclass to `LeftAndMain`, which is the main CMS controller. +This allows us to intercept the list building logic, and alter the `GridField` +before its rendered. In this case, we limit our logic to the desired page type, +although it's just as easy to implement changes which apply to all page types, +or across page types with common characteristics. + + :::php + // mysite/code/NewsPageHolderCMSMainExtension.php + class NewsPageHolderCMSMainExtension extends Extension { + function updateListView($listView) { + $parentId = $listView->getController()->getRequest()->requestVar('ParentID'); + $parent = ($parentId) ? Page::get()->byId($parentId) : new Page(); + + // Only apply logic for this page type + if($parent && $parent instanceof NewsPageHolder) { + $gridField = $listView->Fields()->dataFieldByName('Page'); + if($gridField) { + // Sort by created + $list = $gridField->getList(); + $gridField->setList($list->sort('Created', 'DESC')); + // Add author to columns + $cols = $gridField->getConfig()->getComponentByType('GridFieldDataColumns'); + if($cols) { + $fields = $cols->getDisplayFields($gridField); + $fields['Author.Title'] = 'Author'; + $cols->setDisplayFields($fields); + } + } + } + } + } + + // mysite/_config/config.yml + LeftAndMain: + extensions: + - NewsPageHolderCMSMainExtension \ No newline at end of file diff --git a/docs/en/howto/index.md b/docs/en/howto/index.md index 9eff60df6..b07122c1a 100644 --- a/docs/en/howto/index.md +++ b/docs/en/howto/index.md @@ -6,6 +6,7 @@ on tasks and goals rather than going into deep details. You will find it useful to read the introduction [tutorials](/tutorials) before tackling these How-Tos so you can understand some of the language and functions which are used in the guides. +* [Howto: Customize the Pages List in the CMS](customize-cms-pages-list) * [Import CSV Data](csv-import). Build a simple CSV importer using either [api:ModelAdmin] or a custom controller * [Dynamic Default Fields](dynamic-default-fields). Pre populate a [api:DataObject] with data. * [Grouping Lists](grouping-dataobjectsets). Group results in a [api:SS_List] to create sub sections.