silverstripe-framework/docs/en/howto/grouping-dataobjectsets.md

Grouping Data Object Sets

The [api:DataObjectSet] class has a number of methods useful for grouping objects by fields. Together with sorting this can be used to break up long lists of data into more manageable sub-sections.

The [api:DataObjectSet->groupBy()] method takes a field name as the single argument, and breaks the set up into a number of arrays, where each array contains only objects with the same value of that field. The [api:DataObjectSet->GroupedBy()] method builds on this and returns the same data in a template-friendly format.

Grouping Sets By First Letter

This example deals with breaking up a [api:DataObjectSet] into sub-headings by the first letter.

Let's say you have a set of Module objects, each representing a SilverStripe module, and you want to output a list of these in alphabetical order, with each letter as a heading; something like the following list:

*	B
	* Blog
*	C
	* CMS Workflow
	* Custom Translations
*	D
	* Database Plumber
	* ...

The first step is to set up the basic data model, along with a method that returns the first letter of the title. This will be used both for grouping and for the title in the template.

:::php
class Module extends DataObject {

	public static $db = array(
		'Title' => 'Varchar(255)'
	);

	// ...

	/**
	 * Returns the first letter of the module title, used for grouping.
	 *
	 * @return string
	 */
	public function getTitleFirstLetter() {
		return $this->Title[0];
	}

}

The next step is to create a method or variable that will contain/return all the Module objects, sorted by title. For this example this will be a method on the Page class.

:::php
class Page extends SiteTree {

	// ...

	/**
	 * Returns all modules, sorted by their title.
	 *
	 * @return DataObjectSet
	 */
	public function getModules() {
		return DataObject::get('Module', null, '"Title"');
	}

}

The final step is to render this into a template. The [api:DataObjectSet->GroupedBy()] method breaks up the set into a number of sets, grouped by the field that is passed as the parameter. In this case, the getTitleFirstLetter method defined earlier is used to break them up.

:::ss
// Modules list grouped by TitleFirstLetter
<h2>Modules</h2>
<% control Modules.GroupedBy(TitleFirstLetter) %>
	<h3>$TitleFirstLetter</h3>
	<ul>
		<% control Children %>
			<li>$Title</li>
		<% end_control %>
	</ul>
<% end_control %>

Grouping Sets By Month

Grouping a set by month is a very similar process. The only difference would be to sort the records by month name, and then create a method on the DataObject that returns the month name, and pass that to the [api:DataObjectSet->GroupedBy()] call.

Again, the first step is to create a method on the class in question that will be displayed in a list. For this example, a [api:DataObject] called NewsItem will be used. This will have a method which returns the month it was posted in:

:::php
class NewsItem extends DataObject {

	public static $db = array(
		'Title' => 'Varchar(255)',
		'Date'  => 'Date'
	);

	// ...

	/**
	 * Returns the month name this news item was posted in.
	 *
	 * @return string
	 */
	public function getMonthPosted() {
		return date('F', strtotime($this->Date));
	}

}

The next step is to create a method that will return all the News records that exist, sorted by month name from January to December. This can be accomplshed by sorting by the Date field:

:::php
class Page extends SiteTree {

	/**
	 * Returns all news items, sorted by the month they were posted
	 *
	 * @return DataObjectSet
	 */
	public function getNewsItems() {
		return DataObject::get('NewsItem', null, '"Date"');
	}

}

The final step is the render this into the template using the [api:DataObjectSet->GroupedBy()] method.

:::ss
// Modules list grouped by the Month Posted
<h2>Modules</h2>
<% control NewsItems.GroupedBy(MonthPosted) %>
	<h3>$MonthPosted</h3>
	<ul>
		<% control Children %>
			<li>$Title ($Date.Nice)</li>
		<% end_control %>
	</ul>
<% end_control %>