diff --git a/docs/en/changelogs/3.0.0.md b/docs/en/changelogs/3.0.0.md index c87047078..b0f824e33 100644 --- a/docs/en/changelogs/3.0.0.md +++ b/docs/en/changelogs/3.0.0.md @@ -193,6 +193,15 @@ The abstract `RelationList` class and its implementations `ManyManyList` and `Ha are replacing the `ComponentSet` API, which is only relevant if you have instanciated these manually. Relations are retrieved through the same way (e.g. `$myMember->Groups()`). +### New ORM: DataObjectSet->groupBy() changed to GroupedList decorator + + :::php + $members = Member::get(); + // before + $grouped = $members->groupBy('Surname'); + // after + $grouped = GroupedList::create($members)->groupBy('Surname'); + ### Aggregate changes for partial caching in templates ### `DataObject::Aggregate()` and `DataObject::RelationshipAggregate()` are now deprecated. To replace your deprecated aggregate calls diff --git a/docs/en/howto/csv-import.md b/docs/en/howto/csv-import.md index a0aa50ba4..5c8253397 100644 --- a/docs/en/howto/csv-import.md +++ b/docs/en/howto/csv-import.md @@ -184,9 +184,7 @@ Sample implementation of a custom loader. Assumes a CSV-file in a certain format $obj->LastName = $parts[1]; } public static function getTeamByTitle(&$obj, $val, $record) { - $SQL_val = Convert::raw2sql($val); - return DataObject::get_one( - 'FootballTeam', "Title = '{$SQL_val}'" + return FootballTeam::get()->filter('Title', $val)->First(); ); } } diff --git a/docs/en/howto/extend-cms-interface.md b/docs/en/howto/extend-cms-interface.md index 51a3bf8ed..775d94205 100644 --- a/docs/en/howto/extend-cms-interface.md +++ b/docs/en/howto/extend-cms-interface.md @@ -115,7 +115,7 @@ Add the following code to a new file `zzz_admin/code/BookmarkedLeftAndMainExtens where('"IsBookmarked" = 1'); + return Page::get()->filter("IsBookmarked", 1); } } diff --git a/docs/en/howto/grouping-dataobjectsets.md b/docs/en/howto/grouping-dataobjectsets.md index 4be1c31eb..4c9498bed 100644 --- a/docs/en/howto/grouping-dataobjectsets.md +++ b/docs/en/howto/grouping-dataobjectsets.md @@ -1,15 +1,22 @@ -# Grouping Data Object Sets +# Grouping lists of records -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:SS_List] class is designed to return a flat list of records. +These lists can get quite long, and hard to present on a single list. +[Pagination](/howto/pagination) is one way to solve this problem, +by splitting up the list into multiple pages. -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. +In this howto, we present an alternative to pagination: +Grouping a list by various criteria, through the `[api:GroupedList]` class. +This class is a `[api:SS_ListDecorator]`, which means it wraps around a list, +adding new functionality. + +It provides a `groupBy()` method, which takes a field name, and breaks up the managed list +into a number of arrays, where each array contains only objects with the same value of that field. +Similarly, the `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. +This example deals with breaking up a [api:SS_List] 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: @@ -23,31 +30,27 @@ these in alphabetical order, with each letter as a heading; something like the f * 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 +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)' + 'Title' => 'Text' ); - // ... - /** * 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. +The next step is to create a method or variable that will contain/return all the objects, +sorted by title. For this example this will be a method on the `Page` class. :::php class Page extends SiteTree { @@ -56,23 +59,22 @@ this example this will be a method on the Page class. /** * Returns all modules, sorted by their title. - * - * @return DataObjectSet + * @return GroupedList */ - public function getModules() { - return DataObject::get('Module', null, '"Title"'); + public function getGroupedModules() { + return GroupedList::create(Module::get()->sort('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. +The final step is to render this into a template. The `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 + <%-- Modules list grouped by TitleFirstLetter --%>

Modules

- <% control Modules.GroupedBy(TitleFirstLetter) %> + <% control GroupedModules.GroupedBy(TitleFirstLetter) %>

$TitleFirstLetter