From 334a9af199ca74f4a785f55da74583628c4474f5 Mon Sep 17 00:00:00 2001 From: Steve Boyd Date: Thu, 29 Aug 2024 12:17:16 +1200 Subject: [PATCH] DOC Replace Extension subclasses --- .../00_Model/07_Permissions.md | 2 +- .../00_Model/10_Versioning.md | 6 ++--- .../01_Templates/10_Unique_Keys.md | 2 +- .../05_Extending/01_Extensions.md | 27 +++++++++---------- .../How_Tos/03_Track_member_logins.md | 4 +-- .../09_Security/00_Member.md | 8 +++--- .../14_Files/01_File_Management.md | 4 +-- .../How_Tos/Customise_CMS_Menu.md | 6 ++--- .../How_Tos/Customise_CMS_Tree.md | 2 +- .../How_Tos/Extend_CMS_Interface.md | 20 +++++++------- .../03_Managing_Sessions.md | 6 ++--- .../05_plugins/03_writing_a_complex_plugin.md | 2 +- en/08_Changelogs/6.0.0.md | 1 + .../01_PHP_Coding_Conventions.md | 1 - 14 files changed, 45 insertions(+), 46 deletions(-) diff --git a/en/02_Developer_Guides/00_Model/07_Permissions.md b/en/02_Developer_Guides/00_Model/07_Permissions.md index 6ebdc8075..1c9876838 100644 --- a/en/02_Developer_Guides/00_Model/07_Permissions.md +++ b/en/02_Developer_Guides/00_Model/07_Permissions.md @@ -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 diff --git a/en/02_Developer_Guides/00_Model/10_Versioning.md b/en/02_Developer_Guides/00_Model/10_Versioning.md index 9a83e69b9..eda3509d2 100644 --- a/en/02_Developer_Guides/00_Model/10_Versioning.md +++ b/en/02_Developer_Guides/00_Model/10_Versioning.md @@ -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. @@ -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) { diff --git a/en/02_Developer_Guides/01_Templates/10_Unique_Keys.md b/en/02_Developer_Guides/01_Templates/10_Unique_Keys.md index 376a7c08f..cb25246f3 100644 --- a/en/02_Developer_Guides/01_Templates/10_Unique_Keys.md +++ b/en/02_Developer_Guides/01_Templates/10_Unique_Keys.md @@ -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 diff --git a/en/02_Developer_Guides/05_Extending/01_Extensions.md b/en/02_Developer_Guides/05_Extending/01_Extensions.md index 904c217e0..8e989ef11 100644 --- a/en/02_Developer_Guides/05_Extending/01_Extensions.md +++ b/en/02_Developer_Guides/05_Extending/01_Extensions.md @@ -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` @@ -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', @@ -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) { @@ -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', @@ -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) { @@ -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', @@ -451,4 +451,3 @@ class CustomisedSomeExtension extends SomeExtension ## API documentation - [Extension](api:SilverStripe\Core\Extension) -- [DataExtension](api:SilverStripe\ORM\DataExtension) diff --git a/en/02_Developer_Guides/05_Extending/How_Tos/03_Track_member_logins.md b/en/02_Developer_Guides/05_Extending/How_Tos/03_Track_member_logins.md index 4b6c802d7..dcc55b9ea 100644 --- a/en/02_Developer_Guides/05_Extending/How_Tos/03_Track_member_logins.md +++ b/en/02_Developer_Guides/05_Extending/How_Tos/03_Track_member_logins.md @@ -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', diff --git a/en/02_Developer_Guides/09_Security/00_Member.md b/en/02_Developer_Guides/09_Security/00_Member.md index b609908f3..69ae9f796 100644 --- a/en/02_Developer_Guides/09_Security/00_Member.md +++ b/en/02_Developer_Guides/09_Security/00_Member.md @@ -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. @@ -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 = [ diff --git a/en/02_Developer_Guides/14_Files/01_File_Management.md b/en/02_Developer_Guides/14_Files/01_File_Management.md index 125f9cf4f..0f1bc4b5e 100644 --- a/en/02_Developer_Guides/14_Files/01_File_Management.md +++ b/en/02_Developer_Guides/14_Files/01_File_Management.md @@ -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', diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Menu.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Menu.md index 679ab59a4..93dd3e93f 100644 --- a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Menu.md +++ b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Menu.md @@ -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 { // ... diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Tree.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Tree.md index d2d67733c..474f4f9ae 100644 --- a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Tree.md +++ b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Tree.md @@ -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()`. diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Extend_CMS_Interface.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Extend_CMS_Interface.md index 9704e2a32..d5667f501 100644 --- a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Extend_CMS_Interface.md +++ b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Extend_CMS_Interface.md @@ -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', @@ -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 { // ... @@ -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() { @@ -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', diff --git a/en/02_Developer_Guides/18_Cookies_And_Sessions/03_Managing_Sessions.md b/en/02_Developer_Guides/18_Cookies_And_Sessions/03_Managing_Sessions.md index 1f88913fe..8e69b32b0 100644 --- a/en/02_Developer_Guides/18_Cookies_And_Sessions/03_Managing_Sessions.md +++ b/en/02_Developer_Guides/18_Cookies_And_Sessions/03_Managing_Sessions.md @@ -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 diff --git a/en/02_Developer_Guides/19_GraphQL/05_plugins/03_writing_a_complex_plugin.md b/en/02_Developer_Guides/19_GraphQL/05_plugins/03_writing_a_complex_plugin.md index f81f38992..750d76fcc 100644 --- a/en/02_Developer_Guides/19_GraphQL/05_plugins/03_writing_a_complex_plugin.md +++ b/en/02_Developer_Guides/19_GraphQL/05_plugins/03_writing_a_complex_plugin.md @@ -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. diff --git a/en/08_Changelogs/6.0.0.md b/en/08_Changelogs/6.0.0.md index e45de85f7..fb7acb6a5 100644 --- a/en/08_Changelogs/6.0.0.md +++ b/en/08_Changelogs/6.0.0.md @@ -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} diff --git a/en/10_Contributing/05_Coding_Conventions/01_PHP_Coding_Conventions.md b/en/10_Contributing/05_Coding_Conventions/01_PHP_Coding_Conventions.md index c513985d0..4be4d808b 100644 --- a/en/10_Contributing/05_Coding_Conventions/01_PHP_Coding_Conventions.md +++ b/en/10_Contributing/05_Coding_Conventions/01_PHP_Coding_Conventions.md @@ -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: