Skip to content

Commit

Permalink
DOC Replace Extension subclasses
Browse files Browse the repository at this point in the history
  • Loading branch information
emteknetnz committed Aug 29, 2024
1 parent ced3de0 commit 334a9af
Show file tree
Hide file tree
Showing 14 changed files with 45 additions and 46 deletions.
2 changes: 1 addition & 1 deletion en/02_Developer_Guides/00_Model/07_Permissions.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,7 +128,7 @@ class PermissionsExtension extends Extension
}
```

See [Extensions and DataExtensions](/developer_guides/extending/extensions/) for more information about extensions.
See [Extensions](/developer_guides/extending/extensions/) for more information about extensions.

## API documentation

Expand Down
6 changes: 3 additions & 3 deletions en/02_Developer_Guides/00_Model/10_Versioning.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ summary: Add versioning to your database content through the Versioned extension
Database content in Silverstripe CMS can be "staged" before its publication, as well as track all changes through the
lifetime of a database record.

Versioning in Silverstripe CMS is handled through the [`Versioned`](api:SilverStripe\Versioned\Versioned) extension class. As an [`DataExtension`](api:SilverStripe/ORM/DataExtension) it is possible to be applied to any [`DataObject`](api:SilverStripe\ORM\DataObject) subclass. The extension class will automatically update read and write operations performed via the ORM because it implements the [`augmentSQL()`](api:SilverStripe/ORM/DataExtension::augmentSql()) extension hook method.
Versioning in Silverstripe CMS is handled through the [`Versioned`](api:SilverStripe\Versioned\Versioned) extension class. As an [`Extension`](api:SilverStripe\Core\Extension) it is possible to be applied to any [`DataObject`](api:SilverStripe\ORM\DataObject) subclass. The extension class will automatically update read and write operations performed via the ORM because it implements the `augmentSQL` extension hooks defined in [`DataQuery::getFinalisedQuery()`](api:SilverStripe\ORM\DataQuery::getFinalisedQuery()).

The `Versioned` extension is applied to pages in the CMS (the [`SiteTree`](api:SilverStripe\CMS\Model\SiteTree) class) - along with some other core `DataObject` models such as files - by default. Draft content edited in the CMS can be different
from published content shown to your website visitors.
Expand Down Expand Up @@ -327,10 +327,10 @@ E.g.
```php
namespace App\Extension;

use SilverStripe\ORM\DataExtension;
use SilverStripe\Core\Extension;
use SilverStripe\Security\Permission;

class MyObjectExtension extends DataExtension
class MyObjectExtension extends Extension
{
protected function canViewNonLive($member = null)
{
Expand Down
2 changes: 1 addition & 1 deletion en/02_Developer_Guides/01_Templates/10_Unique_Keys.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Some cases where this is used in supported modules already are:
- versions - an object in different version stages needs to have different unique keys for each stage
- locales - an object in different locales needs to have different unique keys for each locale

See [Extensions and DataExtensions](/developer_guides/extending/extensions) for more information about implementing and applying extensions.
See [Extensions](/developer_guides/extending/extensions) for more information about implementing and applying extensions.

### Custom service

Expand Down
27 changes: 13 additions & 14 deletions en/02_Developer_Guides/05_Extending/01_Extensions.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,17 @@
---
title: Extensions
summary: Extensions and DataExtensions let you modify and augment objects transparently.
summary: Extensions let you modify and augment objects transparently.
icon: code
---

# `Extension` and `DataExtension`
# `Extension`

An [Extension](api:SilverStripe\Core\Extension) allows for adding additional functionality to a class or modifying existing functionality
without the hassle of creating a subclass. Developers can add Extensions to any PHP class that has the [Extensible](api:SilverStripe\Core\Extensible)
trait applied within core, modules or even their own code to make it more reusable.

Extensions are defined as subclasses of the [`Extension`](api:SilverStripe\Core\Extension) class.
Typically, subclasses of the [`DataExtension`](api:SilverStripe\ORM\DataExtension) class are used for extending a [`DataObject`](api:SilverStripe\ORM\DataObject) subclass.
Typically, subclasses of the [`Extension`](api:SilverStripe\Core\Extension) class are used for extending a [`DataObject`](api:SilverStripe\ORM\DataObject) subclass.

> [!NOTE]
> For performance reasons a few classes are excluded from receiving extensions, including `ViewableData`
Expand All @@ -21,9 +21,9 @@ Typically, subclasses of the [`DataExtension`](api:SilverStripe\ORM\DataExtensio
// app/src/Extension/MyMemberExtension.php
namespace App\Extension;

use SilverStripe\ORM\DataExtension;
use SilverStripe\Core\Extension;

class MyMemberExtension extends DataExtension
class MyMemberExtension extends Extension
{
private static $db = [
'DateOfBirth' => 'DBDatetime',
Expand Down Expand Up @@ -78,9 +78,9 @@ In your [`Extension`](api:SilverStripe\Core\Extension) class you can only refer
// app/src/Extension/MyMemberExtension.php
namespace App\Extension;
use SilverStripe\ORM\DataExtension;
use SilverStripe\Core\Extension;
class MyMemberExtension extends DataExtension
class MyMemberExtension extends Extension
{
public function updateFoo($foo)
{
Expand Down Expand Up @@ -174,9 +174,9 @@ Because `$db`, `$has_one`, etc are ultimately just configuration properties, the
namespace App\Extension;
use SilverStripe\Assets\Image;
use SilverStripe\ORM\DataExtension;
use SilverStripe\Core\Extension;
class MyMemberExtension extends DataExtension
class MyMemberExtension extends Extension
{
private static $db = [
'Position' => 'Varchar',
Expand Down Expand Up @@ -252,9 +252,9 @@ validator by defining the `updateValidator` method.
// app/src/Extension/MyMemberExtension.php
namespace App\Extension;
use SilverStripe\ORM\DataExtension;
use SilverStripe\Core\Extension;
class MyMemberExtension extends DataExtension
class MyMemberExtension extends Extension
{
protected function updateValidator($validator)
{
Expand All @@ -274,11 +274,11 @@ extension. The `CMS` provides a `updateCMSFields` Extension Hook to tie into.
namespace App\Extension;
use SilverStripe\AssetAdmin\Forms\UploadField;
use SilverStripe\Core\Extension;
use SilverStripe\Forms\FieldList;
use SilverStripe\Forms\TextField;
use SilverStripe\ORM\DataExtension;
class MyMemberExtension extends DataExtension
class MyMemberExtension extends Extension
{
private static $db = [
'Position' => 'Varchar',
Expand Down Expand Up @@ -451,4 +451,3 @@ class CustomisedSomeExtension extends SomeExtension
## API documentation

- [Extension](api:SilverStripe\Core\Extension)
- [DataExtension](api:SilverStripe\ORM\DataExtension)
Original file line number Diff line number Diff line change
Expand Up @@ -17,15 +17,15 @@ explicitly logging in or by invoking the "remember me" functionality.
```php
namespace App\Extension;

use SilverStripe\Core\Extension;
use SilverStripe\Forms\FieldList;
use SilverStripe\Forms\ReadonlyField;
use SilverStripe\ORM\DB;
use SilverStripe\ORM\DataExtension;
use SilverStripe\ORM\DataObject;
use SilverStripe\Security\Member;
use SilverStripe\Security\Security;

class MyMemberExtension extends DataExtension
class MyMemberExtension extends Extension
{
private static $db = [
'LastVisited' => 'Datetime',
Expand Down
8 changes: 4 additions & 4 deletions en/02_Developer_Guides/09_Security/00_Member.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ if ($member) {
## Subclassing

> [!WARNING]
> This is the least desirable way of extending the [Member](api:SilverStripe\Security\Member) class. It's better to use [DataExtension](api:SilverStripe\ORM\DataExtension)
> This is the least desirable way of extending the [Member](api:SilverStripe\Security\Member) class. It's better to use [Extension](api:SilverStripe\Core\Extension)
> (see below).
You can define subclasses of [Member](api:SilverStripe\Security\Member) to add extra fields or functionality to the built-in membership system.
Expand Down Expand Up @@ -109,18 +109,18 @@ SilverStripe\Security\Member:
- App\Extension\MyMemberExtension
```

A role extension is simply a subclass of [`DataExtension`](api:SilverStripe\ORM\DataExtension) that is designed to be used to add behaviour to [`Member`](api:SilverStripe\Security\Member).
A role extension is simply a subclass of [`Extension`](api:SilverStripe\Core\Extension) that is designed to be used to add behaviour to [`Member`](api:SilverStripe\Security\Member).
The roles affect the entire class - all members will get the additional behaviour. However, if you want to restrict
things, you should add appropriate [`Permission::checkMember()`](api:SilverStripe\Security\Permission::checkMember()) calls to the role's methods.

```php
namespace App\Extension;
use SilverStripe\Core\Extension;
use SilverStripe\Form\FieldList;
use SilverStripe\ORM\DataExtension;
use SilverStripe\Security\Permission;
class MyMemberExtension extends DataExtension
class MyMemberExtension extends Extension
{
// define additional properties
private static $db = [
Expand Down
4 changes: 2 additions & 2 deletions en/02_Developer_Guides/14_Files/01_File_Management.md
Original file line number Diff line number Diff line change
Expand Up @@ -159,9 +159,9 @@ SilverStripe\AssetAdmin\Forms\FileFormFactory:
// app/src/Extension/MyFileExtension.php
namespace App\Extension;
use SilverStripe\ORM\DataExtension;
use SilverStripe\Core\Extension;
class MyFileExtension extends DataExtension
class MyFileExtension extends Extension
{
private static $db = [
'Description' => 'Text',
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -73,16 +73,16 @@ On top of your administration windows, the menu can also have external links
(e.g. to external reference). In this example, we're going to add a link to
Google to the menu.

First, we need to define a [LeftAndMainExtension](api:SilverStripe\Admin\LeftAndMainExtension) which will contain our
First, we need to define an [Extension](api:SilverStripe\Core\Extension) which will contain our
button configuration.

```php
namespace App\Admin;

use SilverStripe\Admin\CMSMenu;
use SilverStripe\Admin\LeftAndMainExtension;
use SilverStripe\Core\Extension;

class CustomLeftAndMain extends LeftAndMainExtension
class CustomLeftAndMain extends Extension
{
// ...

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ Each flag has a unique identifier, which is also used as a CSS class for easier

Developers can easily add a new flag, delete or alter an existing flag on how it is looked
or changing the flag label. The customization of these lozenges could be done either through
inherited subclass or [DataExtension](api:SilverStripe\ORM\DataExtension). It is just really about how we change the return
inherited subclass or [Extension](api:SilverStripe\Core\Extension). It is just really about how we change the return
value of function `SiteTree->getTreeTitle()` by two easily extendable methods
`SiteTree->getStatusClass()` and `SiteTree->getStatusFlags()`.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -88,16 +88,16 @@ Then run `composer vendor-expose`. This command will publish all the `css` files
## Create a "bookmark" flag on pages

Now we'll define which pages are actually bookmarked, a flag that is stored in
the database. For this we need to decorate the page record with a
`DataExtension`. Create a new file called `app/src/BookmarkedPageExtension.php`
the database. For this we need to decorate the page record with an
`Extension`. Create a new file called `app/src/BookmarkedPageExtension.php`
and insert the following code.

```php
namespace App\Extension;
use SilverStripe\ORM\DataExtension;
use SilverStripe\Core\Extension;
class BookmarkedPageExtension extends DataExtension
class BookmarkedPageExtension extends Extension
{
private static array $db = [
'IsBookmarked' => 'Boolean',
Expand All @@ -116,10 +116,10 @@ If you need to update those form fields, you can implement the `updateCMSFields(
```php
namespace App\Extension;
use SilverStripe\Core\Extension;
use SilverStripe\Forms\FieldList;
use SilverStripe\ORM\DataExtension;
class BookmarkedPageExtension extends DataExtension
class BookmarkedPageExtension extends Extension
{
// ...
Expand Down Expand Up @@ -153,9 +153,9 @@ Add the following code to a new file `app/src/BookmarkedLeftAndMainExtension.php
```php
namespace App\Extension;
use SilverStripe\Admin\LeftAndMainExtension;
use SilverStripe\Core\Extension;
class BookmarkedPagesLeftAndMainExtension extends LeftAndMainExtension
class BookmarkedPagesLeftAndMainExtension extends Extension
{
public function getBookmarkedPages()
{
Expand Down Expand Up @@ -264,9 +264,9 @@ applicable controller actions to it:
```php
namespace App\Extension;
use SilverStripe\Admin\LeftAndMainExtension;
use SilverStripe\Core\Extension;
class CustomActionsExtension extends LeftAndMainExtension
class CustomActionsExtension extends Extension
{
private static $allowed_actions = [
'sampleAction',
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -77,16 +77,16 @@ will need to log back in to perform further actions.

#### Creating an extension for `LoginSession`

The first step is to create a [`DataExtension`](api:SilverStripe\ORM\DataExtension) that grant some users the ability to hooks into [`LoginSession`](api:SilverStripe\SessionManager\Models\LoginSession)'s `canView()` and `canDelete()` methods. This example aligns the permissions on the [`LoginSession`](api:SilverStripe\SessionManager\Models\LoginSession) to the permission on the Member who owns the [`LoginSession`](api:SilverStripe\SessionManager\Models\LoginSession).
The first step is to create an [`Extension`](api:SilverStripe\Core\Extension) that grant some users the ability to hooks into [`LoginSession`](api:SilverStripe\SessionManager\Models\LoginSession)'s `canView()` and `canDelete()` methods. This example aligns the permissions on the [`LoginSession`](api:SilverStripe\SessionManager\Models\LoginSession) to the permission on the Member who owns the [`LoginSession`](api:SilverStripe\SessionManager\Models\LoginSession).

Alternatively, you could call [`Permission::check()`](api:SilverStripe\Security\Permission::check()) to validate if the member has a predefined CMS permission. If you need even more granular permissions, you can implement a [`PermissionProvider`](/developer_guides/security/permissions/#permissionprovider) to define your own custom permissions.

```php
namespace My\App;

use SilverStripe\ORM\DataExtension;
use SilverStripe\Core\Extension;

class LoginSessionExtension extends DataExtension
class LoginSessionExtension extends Extension
{
/**
* @param Member $member
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ summary: In this tutorial, we'll create a plugin that affects models, queries, a
## Writing a complex plugin

For this example, we'll imagine that a lot of our DataObjects are geocoded, and this is ostensibly some kind of
`DataExtension` that adds lat/lon information to the `DataObject`, and maybe allows you to ask how close it is to
`Extension` that adds lat/lon information to the `DataObject`, and maybe allows you to ask how close it is to
a given lat/lon pair.

We want any queries using these DataObjects to be able to search within a radius of a given lat/lon.
Expand Down
1 change: 1 addition & 0 deletions en/08_Changelogs/6.0.0.md
Original file line number Diff line number Diff line change
Expand Up @@ -338,6 +338,7 @@ Injector::inst()->load([
- [`DataObject::write()`](api:SilverStripe\ORM\DataObject::write()) has a new boolean `$skipValidation` parameter. This can be useful for scenarios where you want to automatically create a new record with no data initially without restricting how developers can set up their validation rules.
- [`FieldList`](api:SilverStripe\Forms\FieldList) is now strongly typed. Methods that previously allowed any iterable variables to be passed, namely [`FieldList::addFieldsToTab()`](api:SilverStripe\Forms\FieldList::addFieldsToTab()) and [`FieldList::removeFieldsFromTab()`](api:SilverStripe\Forms\FieldList::removeFieldsFromTab()), now require an array to be passed instead.
- [`BaseElement::getDescription()`](api:DNADesign\Elemental\Models\BaseElement::getDescription()) has been removed. If you had implemented this method in your custom elemental blocks, either set the [`description`](api:DNADesign\Elemental\Models\BaseElement->description) configuration property or override the [`getTypeNice()`](api:DNADesign\Elemental\Models\BaseElement::getTypeNice()) method.
- [`DataExtension`](api:SilverStripe\ORM\DataExtension), [`SiteTreeExtension`](api:SilverStripe\CMS\Model\SiteTreeExtension), and [`LeftAndMainExtension`](api:SilverStripe\Admin\LeftAndMainExtension) have been removed. If you subclass any of these classes, you must now subclass [`Extension`](api:SilverStripe\Core\Extension) instead.

### Full list of removed and changed API (by module, alphabetically) {#api-removed-and-changed}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,6 @@ Use an appropriate suffix or prefix for classnames when making a subclass or imp
## Extensions and traits

- Use the [`Extension`](api:SilverStripe\Core\Extension) class for extending classes, including `DataObject` subclasses.
- Do not use the `DataExtension` class, it will be deprecated in a future release.

Use a trait instead of an [`Extension`](api:SilverStripe\Core\Extension) when the composable functionality:

Expand Down

0 comments on commit 334a9af

Please sign in to comment.