Skip to content

Commit

Permalink
DOC Document renamed classes (#584)
Browse files Browse the repository at this point in the history
  • Loading branch information
GuySartorelli committed Sep 23, 2024
1 parent e87ed52 commit 9ec893b
Show file tree
Hide file tree
Showing 21 changed files with 122 additions and 90 deletions.
2 changes: 1 addition & 1 deletion en/02_Developer_Guides/00_Model/01_Data_Model_and_ORM.md
Original file line number Diff line number Diff line change
Expand Up @@ -262,7 +262,7 @@ if ($players->exists()) {
> [!TIP]
> While you could use `if ($players->Count() > 0)` for this condition, the `exists()` method uses an `EXISTS` SQL query, which is more performant.
See the [Lists](lists) documentation for more information on dealing with [SS_List](api:SilverStripe\ORM\SS_List) instances.
See the [Lists](lists) documentation for more information on dealing with [SS_List](api:SilverStripe\Model\List\SS_List) instances.

## Sorting

Expand Down
20 changes: 10 additions & 10 deletions en/02_Developer_Guides/00_Model/03_Lists.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,15 @@ icon: list

# Managing lists

Whenever using the ORM to fetch records or navigate relationships you will receive an [SS_List](api:SilverStripe\ORM\SS_List) instance commonly as
Whenever using the ORM to fetch records or navigate relationships you will receive an [SS_List](api:SilverStripe\Model\List\SS_List) instance commonly as
either [DataList](api:SilverStripe\ORM\DataList) or [RelationList](api:SilverStripe\ORM\RelationList). This object gives you the ability to iterate over each of the results or
modify.

There's a lot more information about filtering and sorting lists in the [Introduction to the Data Model and ORM](/developer_guides/model/data_model_and_orm/) section.

## Iterating over the list

[`SS_List`](api:SilverStripe\ORM\SS_List) extends the [`IteratorAggregate`](https://www.php.net/manual/en/class.iteratoraggregate.php) interface, allowing you to loop over the instance.
[`SS_List`](api:SilverStripe\Model\List\SS_List) extends the [`IteratorAggregate`](https://www.php.net/manual/en/class.iteratoraggregate.php) interface, allowing you to loop over the instance.

```php
use SilverStripe\Security\Member;
Expand All @@ -37,7 +37,7 @@ Or in the template engine:

## Finding an item by value

You can use the [`find()`](api:SilverStripe\ORM\SS_List::find()) method to get a single item based on the value of one of its properties.
You can use the [`find()`](api:SilverStripe\Model\List\SS_List::find()) method to get a single item based on the value of one of its properties.

```php
$members = Member::get();
Expand All @@ -48,7 +48,7 @@ echo $members->find('ID', 4)->FirstName;

## Maps

A map is like an array, where the indexes contain data as well as the values. You can build a map from any list by calling the [`map()](api:SilverStripe\ORM\SS_List::map()) method.
A map is like an array, where the indexes contain data as well as the values. You can build a map from any list by calling the [`map()](api:SilverStripe\Model\List\SS_List::map()) method.

```php
$members = Member::get()->map('ID', 'FirstName');
Expand All @@ -58,15 +58,15 @@ foreach ($members as $id => $firstName) {
}
```

This functionality is provided by the [`Map`](api:SilverStripe\ORM\Map) class, which can be used to build a map from any `SS_List`. You can instantiate a new `Map` object using the `new` keyword as well.
This functionality is provided by the [`Map`](api:SilverStripe\Model\List\Map) class, which can be used to build a map from any `SS_List`. You can instantiate a new `Map` object using the `new` keyword as well.

```php
$membersMap = new Map(Member::get(), 'ID', 'FirstName');
```

## Column

You can get all of the values for a single property by calling the [`column()`](api:SilverStripe\ORM\SS_List::column()) method.
You can get all of the values for a single property by calling the [`column()`](api:SilverStripe\Model\List\SS_List::column()) method.

```php
// returns [
Expand Down Expand Up @@ -121,7 +121,7 @@ There are some limitations:

## ArrayList

[`ArrayList`](api:SilverStripe\ORM\ArrayList) exists to wrap a standard PHP array in the same API as a database backed list.
[`ArrayList`](api:SilverStripe\Model\List\ArrayList) exists to wrap a standard PHP array in the same API as a database backed list.

```php
$sam = Member::get()->byId(5);
Expand All @@ -137,8 +137,8 @@ $numItems = $list->Count();

## API documentation

- [SS_List](api:SilverStripe\ORM\SS_List)
- [SS_List](api:SilverStripe\Model\List\SS_List)
- [RelationList](api:SilverStripe\ORM\RelationList)
- [DataList](api:SilverStripe\ORM\DataList)
- [ArrayList](api:SilverStripe\ORM\ArrayList)
- [Map](api:SilverStripe\ORM\Map)
- [ArrayList](api:SilverStripe\Model\List\ArrayList)
- [Map](api:SilverStripe\Model\List\Map)
6 changes: 3 additions & 3 deletions en/02_Developer_Guides/00_Model/04_Data_Types_and_Casting.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,11 +185,11 @@ DBField::create_field('Date', '1982-01-01')->TimeDiff();

## Casting

Most objects in Silverstripe CMS extend from [ViewableData](api:SilverStripe\View\ViewableData), which means they know how to present themselves in a view
Most objects in Silverstripe CMS extend from [ModelData](api:SilverStripe\Model\ModelData), which means they know how to present themselves in a view
context. Rather than manually returning objects from your custom functions. You can use the `$casting` configuration property. This casting only happens when you get the values in a template, so calling the method in your PHP code will always return the raw value.

> [!TIP]
> While these examples are using `DataObject` subclasses, you can use the `$casting` configuration property on *any* `ViewableData` subclass.
> While these examples are using `DataObject` subclasses, you can use the `$casting` configuration property on *any* `ModelData` subclass.
```php
namespace App\Model;
Expand Down Expand Up @@ -237,7 +237,7 @@ $name = $player->getName()->LimitCharacters(2);
<% end_with %>
```

You can get the casted `DBField` instance of these properties by calling the [`obj()`](api:SilverStripe\View\ViewableData::obj()) method:
You can get the casted `DBField` instance of these properties by calling the [`obj()`](api:SilverStripe\Model\ModelData::obj()) method:

```php
$player = Player::get()->byId(1);
Expand Down
4 changes: 2 additions & 2 deletions en/02_Developer_Guides/00_Model/06_SearchFilters.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ icon: search

# `SearchFilter` modifiers

The `filter()`, `exclude()`, and other related methods on [`DataList`](api:SilverStripe\ORM\DataList), [`ArrayList`](api:SilverStripe\ORM\ArrayList), and [`EagerLoadedList`](api:SilverStripe\ORM\EagerLoadedList) specify exact matches by default. However, when calling these methods, there are a number of suffixes that
The `filter()`, `exclude()`, and other related methods on [`DataList`](api:SilverStripe\ORM\DataList), [`ArrayList`](api:SilverStripe\Model\List\ArrayList), and [`EagerLoadedList`](api:SilverStripe\ORM\EagerLoadedList) specify exact matches by default. However, when calling these methods, there are a number of suffixes that
you can put on field names to change this behavior. These are represented as `SearchFilter` subclasses and include:

- [`ExactMatchFilter`](api:SilverStripe\ORM\Filters\ExactMatchFilter)
Expand Down Expand Up @@ -58,7 +58,7 @@ Developers can define their own [SearchFilter](api:SilverStripe\ORM\Filters\Sear
> Though note that for backwards compatibility reasons, `ArrayList` is explicitly case sensitive by default. To change that, you must set `ArrayList.default_case_sensitive` to false.
>
> ```yml
> SilverStripe\ORM\ArrayList:
> SilverStripe\Model\List\ArrayList:
> default_case_sensitive: false
> ```
Expand Down
10 changes: 5 additions & 5 deletions en/02_Developer_Guides/00_Model/09_Validation.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,14 @@ icon: check-square

## Validation using `symfony/validator` constraints {#symfony-validator}

The [`ConstraintValidator`](api:SilverStripe\Core\Validation\ConstraintValidator) class provides an abstraction around [`symfony/validator`](https://symfony.com/doc/current/components/validator.html), so you can easily validate values against symfony's validation constraints and get a [`ValidationResult`](api:SilverStripe\ORM\ValidationResult) object with the result.
The [`ConstraintValidator`](api:SilverStripe\Core\Validation\ConstraintValidator) class provides an abstraction around [`symfony/validator`](https://symfony.com/doc/current/components/validator.html), so you can easily validate values against symfony's validation constraints and get a [`ValidationResult`](api:SilverStripe\Core\Validation\ValidationResult) object with the result.

```php
use SilverStripe\Core\Validation\ConstraintValidator;

/**
* @var \Symfony\Component\Validator\Constraint $constraint
* @var \SilverStripe\ORM\ValidationResult $result
* @var \SilverStripe\Core\Validation\ValidationResult $result
*/
$result = ConstraintValidator::validate($valueToValidate, $constraint);
```
Expand Down Expand Up @@ -44,12 +44,12 @@ called any time the `write()` method is called, before the `onBeforeWrite()` ext
By default, there is no validation - objects are always valid! However, you can override this method in your `DataObject`
sub-classes to specify custom validation, or use the `updateValidate()` extension hook through an [Extension](api:SilverStripe\Core\Extension).

Invalid objects won't be able to be written - a [`ValidationException`](api:SilverStripe\ORM\ValidationException) will be thrown and no write will occur.
Invalid objects won't be able to be written - a [`ValidationException`](api:SilverStripe\Core\Validation\ValidationException) will be thrown and no write will occur.

Ideally you should call `validate()` in your own application to test that an object is valid before attempting a
write, and respond appropriately if it isn't.

The return value of `validate()` is a [`ValidationResult`](api:SilverStripe\ORM\ValidationResult) object.
The return value of `validate()` is a [`ValidationResult`](api:SilverStripe\Core\Validation\ValidationResult) object.

```php
namespace App\Model;
Expand Down Expand Up @@ -85,4 +85,4 @@ class MyObject extends DataObject
## API documentation

- [DataObject](api:SilverStripe\ORM\DataObject)
- [ValidationResult](api:SilverStripe\ORM\ValidationResult);
- [ValidationResult](api:SilverStripe\Core\Validation\ValidationResult);
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,14 @@ summary: Learn how to split the results of a query into subgroups

# Grouping lists of records

The [SS_List](api:SilverStripe\ORM\SS_List) class is designed to return a flat list of records.
The [SS_List](api:SilverStripe\Model\List\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](/developer_guides/templates/how_tos/pagination) is one way to solve this problem,
by splitting up the list into multiple pages.

In this howto, we present an alternative to pagination:
grouping a list by various criteria, through the [`GroupedList`](api:SilverStripe\ORM\GroupedList) class.
This class is a [`ListDecorator`](api:SilverStripe\ORM\ListDecorator), which means it wraps around a list,
grouping a list by various criteria, through the [`GroupedList`](api:SilverStripe\Model\List\GroupedList) class.
This class is a [`ListDecorator`](api:SilverStripe\Model\List\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
Expand All @@ -21,7 +21,7 @@ Similarly, the `GroupedBy()` method builds on this and returns the same data in

## Grouping sets by first letter

This example deals with breaking up a [`SS_List`](api:SilverStripe\ORM\SS_List) into sub-headings by the first letter.
This example deals with breaking up a [`SS_List`](api:SilverStripe\Model\List\SS_List) into sub-headings by the first letter.

Let's say you have a set of Module objects, each representing a Silverstripe CMS module, and you want to output a list of
these in alphabetical order, with each letter as a heading; something like the following list:
Expand Down Expand Up @@ -71,7 +71,7 @@ namespace App\PageType;

use App\Model\Module;
use Page;
use SilverStripe\ORM\GroupedList;
use SilverStripe\Model\List\GroupedList;

class ModulePage extends Page
{
Expand Down Expand Up @@ -111,7 +111,7 @@ In this case, the `getTitleFirstLetter()` method defined earlier is used to brea
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 [GroupedList::GroupedBy()](api:SilverStripe\ORM\GroupedList::GroupedBy()) call.
and pass that to the [GroupedList::GroupedBy()](api:SilverStripe\Model\List\GroupedList::GroupedBy()) call.

We're reusing our example `Module` object,
but grouping by its built-in `Created` property instead,
Expand Down Expand Up @@ -144,7 +144,7 @@ namespace App\PageType;

use App\Model\Module;
use Page;
use SilverStripe\ORM\GroupedList;
use SilverStripe\Model\List\GroupedList;

class ModulePage extends Page
{
Expand All @@ -159,7 +159,7 @@ class ModulePage extends Page
}
```

The final step is to render this into the template using the [GroupedList::GroupedBy()](api:SilverStripe\ORM\GroupedList::GroupedBy()) method.
The final step is to render this into the template using the [GroupedList::GroupedBy()](api:SilverStripe\Model\List\GroupedList::GroupedBy()) method.

```ss
<%-- Modules list grouped by the Month Posted --%>
Expand Down
6 changes: 3 additions & 3 deletions en/02_Developer_Guides/01_Templates/01_Syntax.md
Original file line number Diff line number Diff line change
Expand Up @@ -271,7 +271,7 @@ include.
## Looping over lists

The `<% loop %>` tag is used to iterate or loop over a collection of items such as a native PHP array, a [DataList](api:SilverStripe\ORM\DataList), or an [ArrayList](api:SilverStripe\ORM\ArrayList)
The `<% loop %>` tag is used to iterate or loop over a collection of items such as a native PHP array, a [DataList](api:SilverStripe\ORM\DataList), or an [ArrayList](api:SilverStripe\Model\List\ArrayList)
collection.

```ss
Expand Down Expand Up @@ -307,7 +307,7 @@ This can be particularly useful when you have collections within collections.

### Altering the list

`<% loop %>` statements often iterate over [`SS_List`](api:SilverStripe\ORM\SS_List) instances. As the template has access to the list object,
`<% loop %>` statements often iterate over [`SS_List`](api:SilverStripe\Model\List\SS_List) instances. As the template has access to the list object,
templates can call its methods.

Sorting the list by a given field.
Expand Down Expand Up @@ -564,7 +564,7 @@ refer directly to properties and methods of the [`Member`](api:SilverStripe\Secu

### `fortemplate()` and `$Me` {#fortemplate}

If you reference some `ViewableData` object directly in a template, the `forTemplate()` method on that object will be called.
If you reference some `ModelData` object directly in a template, the `forTemplate()` method on that object will be called.
This can be used to provide a default template for an object.

```php
Expand Down
4 changes: 2 additions & 2 deletions en/02_Developer_Guides/01_Templates/02_Common_Variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -427,5 +427,5 @@ Placing it just below `$Content` is a good default.

- [ContentController](api:SilverStripe\CMS\Controllers\ContentController): The main controller responsible for handling pages.
- [Controller](api:SilverStripe\Control\Controller): Generic controller (not specific to pages.)
- [DataObject](api:SilverStripe\ORM\DataObject): Underlying model class for page objects.
- [ViewableData](api:SilverStripe\View\ViewableData): Underlying object class for pretty much anything displayable.
- [DataObject](api:SilverStripe\ORM\DataObject): Underlying model class for models which store their data in the database.
- [ModelData](api:SilverStripe\Model\ModelData): Underlying object class for pretty much anything which contains data.
16 changes: 8 additions & 8 deletions en/02_Developer_Guides/01_Templates/04_Rendering_Templates.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ icon: code

# Rendering data to a template

Templates do nothing on their own. Rather, they are used to generate markup - most typically they are used to generate HTML markup, using variables from some `ViewableData` object.
Templates do nothing on their own. Rather, they are used to generate markup - most typically they are used to generate HTML markup, using variables from some `ModelData` object.
All of the `<% if %>`, `<% loop %>` and other variables are methods or parameters that are called on the current object in
scope (see [scope](syntax#scope) in the syntax section).

Expand All @@ -17,13 +17,13 @@ The following will render the given data into a template. Given the template:
<strong>$Name</strong> is the $Role on our team.
```

Our application code can render into that view using the [`renderWith()`](api:SilverStripe\View\ViewableData) method provided by `ViewableData`. Call this method on any instance of `ViewableData` or its subclasses, passing in a template name or an array of templates to render.
Our application code can render into that view using the [`renderWith()`](api:SilverStripe\Model\ModelData) method provided by `ModelData`. Call this method on any instance of `ModelData` or its subclasses, passing in a template name or an array of templates to render.

```php
namespace App\Model;

use SilverStripe\Model\ArrayData;
use SilverStripe\ORM\DataObject;
use SilverStripe\View\ArrayData;

class MyModel extends DataObject
{
Expand Down Expand Up @@ -96,7 +96,7 @@ This will look for a global `templates/Coach_Message.ss` template, and if it doe
See [template types and locations](template_inheritance/#template-types-and-locations) for more information.
> [!NOTE]
> Most classes in Silverstripe CMS you want in your template extend `ViewableData` and allow you to call `renderWith`. This
> Most classes in Silverstripe CMS you want in your template extend `ModelData` and allow you to call `renderWith`. This
> includes [Controller](api:SilverStripe\Control\Controller), [FormField](api:SilverStripe\Forms\FormField) and [DataObject](api:SilverStripe\ORM\DataObject) instances.
>
> ```php
Expand Down Expand Up @@ -157,16 +157,16 @@ class MyPageController extends PageController
## Rendering arbitrary data in templates
Any data you want to render into the template that does not extend `ViewableData` should be wrapped in an object that
Any data you want to render into the template that does not extend `ModelData` should be wrapped in an object that
does, such as `ArrayData` or `ArrayList`.
```php
namespace App\PageType;
use PageController;
use SilverStripe\Control\Director;
use SilverStripe\ORM\ArrayList;
use SilverStripe\View\ArrayData;
use SilverStripe\Model\ArrayData;
use SilverStripe\Model\List\ArrayList;
class MyPageController extends PageController
{
Expand Down Expand Up @@ -195,4 +195,4 @@ class MyPageController extends PageController
```
> [!WARNING]
> A common mistake is trying to loop over an array directly in a template - this won't work. You'll need to wrap the array in some `ViewableData` instance as mentioned above.
> A common mistake is trying to loop over an array directly in a template - this won't work. You'll need to wrap the array in some `ModelData` instance as mentioned above.
Loading

0 comments on commit 9ec893b

Please sign in to comment.