diff --git a/en/02_Developer_Guides/02_Controllers/07_CMS_JSON_APIs.md b/en/02_Developer_Guides/02_Controllers/07_CMS_JSON_APIs.md index de3880d0..b3a65b7d 100644 --- a/en/02_Developer_Guides/02_Controllers/07_CMS_JSON_APIs.md +++ b/en/02_Developer_Guides/02_Controllers/07_CMS_JSON_APIs.md @@ -7,7 +7,7 @@ summary: Creating standardised JSON APIs for authenticated users in the CMS. This document contains a standard set of conventions to be used when creating JSON APIs in the CMS that are used in conjunction with AJAX requests from authenticated CMS users. -To view an example of a controller that follows these standards see [`LinkFieldController`](https://github.com/silverstripe/silverstripe-linkfield/blob/4/src/Controllers/LinkFieldController.php). +To view an example of a controller that follows these standards see [`LinkFieldController`](api:SilverStripe\LinkField\Controllers\LinkFieldController). ## Making the controller "REST-like" and its relation with `FormSchema` @@ -34,14 +34,14 @@ Use the [`required_permission_codes`](api:SilverStripe\Admin\AdminController->re See [user permissions](/developer_guides/security/permissions/) for more information about declaring permissions. -If you need form schema functionality, you will need to create a subclass of [`LeftAndMain`](api:SilverStripe\Admin\LeftAndMain) instead. All of the above still applies, but by default a menu item will be created for your new controller. To remove it from the CMS menu, set the [`ignore_menuitem`](api:SilverStripe\Admin\LeftAndMain->ignore_menuitem) configuration property to true for your class, i.e `private static $ignore_menuitem = true;`. +If you need form schema functionality, you will need to create a subclass of [`FormSchemaController`](api:SilverStripe\Admin\FormSchemaController) instead. ## Handling requests with `$url_handlers` Utilise the [`url_handlers`](api:SilverStripe\Control\Controller->url_handlers) configuration property to get the following benefits: - Ensure the HTTP request method aligns with the intended use for each method, for instance, restricting it to GET or POST. -- If subclassing `LeftAndMain`, avoid potential conflicts with existing methods on the superclass, such as [`LeftAndMain::sort()`](api:SilverStripe\Admin\LeftAndMain::sort()), by structuring the endpoint URL segment as `sort` and associating it with a method like `MySomethingController::apiSort()`. +- If you're using form schema logic in a subclass of `LeftAndMain`, avoid potential conflicts with existing methods on the superclass, such as [`LeftAndMain::sort()`](api:SilverStripe\Admin\LeftAndMain::sort()), by structuring the endpoint URL segment as `sort` and associating it with a method like `MySomethingController::apiSort()`. Use the request param `$ItemID` if you need a record ID into a URL so that you have an endpoint for a specific record. Use `$ItemID` because it's consistent with the request param used in Form Schema requests. For example, to use `$ItemID` in a GET request to view a single record: diff --git a/en/08_Changelogs/6.0.0.md b/en/08_Changelogs/6.0.0.md index 79679750..acdd6cab 100644 --- a/en/08_Changelogs/6.0.0.md +++ b/en/08_Changelogs/6.0.0.md @@ -205,7 +205,7 @@ The way these are displayed in the new `sake tasks` list doesn't suit long names For example, you used to navigate to `/dev/tasks/` or use `sake dev/tasks/`. Now you will need to navigate to `/dev/tasks/` or use `sake tasks:`. -|class|old name|new name| +|Class|Old name|New name| |---|---|---| |[`ContentReviewEmails`](api:SilverStripe\ContentReview\Tasks\ContentReviewEmails)|`SilverStripe-ContentReview-Tasks-ContentReviewEmails`|`content-review-emails`| |[`DeleteAllJobsTask`](api:Symbiote\QueuedJobs\Tasks\DeleteAllJobsTask)|`Symbiote-QueuedJobs-Tasks-DeleteAllJobsTask`|`delete-queued-jobs`| @@ -580,7 +580,7 @@ Some API which used to be on `SSViewer` is now on `SSTemplateEngine`, and some h Along with those API changes, the following classes and interfaces were moved into the new module: -|old class|new class| +|Old class|New class| |---|---| |`SilverStripe\View\SSViewer_BasicIteratorSupport`|[`SilverStripe\TemplateEngine\BasicIteratorSupport`](api:SilverStripe\TemplateEngine\BasicIteratorSupport)| |`SilverStripe\View\SSTemplateParseException`|[`SilverStripe\TemplateEngine\Exception\SSTemplateParseException`](api:SilverStripe\TemplateEngine\Exception\SSTemplateParseException)| @@ -606,14 +606,25 @@ See the [full list of removed and changed API](#api-removed-and-changed) to see ### Changes to `LeftAndMain` and its subclasses {#leftandmain-refactor} -[`LeftAndMain`](api:SilverStripe\Admin\LeftAndMain) has historically been the superclass for all controllers routed in `/admin/*` (i.e. all controllers used in the CMS). That class includes a lot of boilerplate functionality for setting up a menu, edit form, etc which a lot of controllers don't need. +[`LeftAndMain`](api:SilverStripe\Admin\LeftAndMain) has historically been the superclass for all controllers routed in `/admin/*` (i.e. all controllers used in the CMS). It's also the superclass for admin-routed controllers which manage modal forms. That class includes a lot of boilerplate functionality for setting up a menu, edit form, etc which a lot of controllers don't need. A new [`AdminController`](api:SilverStripe\Admin\AdminController) has been created which provides the `/admin/*` routing functionality and permission checks that `LeftAndMain` used to be responsible for. If you have a controller which needs to be routed through `/admin/*` with the relevant CMS permission checks, but which does *not* need a menu item on the left or an edit form, you should update that class to be a subclass of `AdminController` instead. -As a result of this change, to following classes are now direct subclasses of `AdminController`: +The new [`FormSchemaController`](api:SilverStripe\Admin\FormSchemaController) class (which is a subclass of `AdminController`) now owns the logic required for injecting and managing forms inside modals. -- [`SudoModeController`](api:SilverStripe\Admin\SudoModeController) - used to be a subclass of `LeftAndMain`. -- [`CMSExternalLinksController`](api:SilverStripe\ExternalLinks\Controllers\CMSExternalLinksController) - used to be a direct subclass of [`Controller`](api:SilverStripe\Control\Controller). +As a result of these changes, the following classes have had their class hierarchy updated: + +|Class|Old superclass|New superclass| +|---|---|---| +|[`LeftAndMain`](api:SilverStripe\Admin\LeftAndMain)|[`Controller`](api:SilverStripe\Control\Controller)|`FormSchemaController`| +|[`SudoModeController`](api:SilverStripe\Admin\SudoModeController)|`LeftAndMain`|`AdminController`| +|[`ElementalAreaController`](api:DNADesign\Elemental\Controllers\ElementalAreaController)|[`CMSMain`](api:SilverStripe\CMS\Controllers\CMSMain)|`FormSchemaController`| +|[`HistoryViewerController`](api:SilverStripe\VersionedAdmin\Controllers\HistoryViewerController)|`LeftAndMain`|`FormSchemaController`| +|[`UserDefinedFormAdmin`](api:SilverStripe\UserForms\Control\UserDefinedFormAdmin)|`LeftAndMain`|`FormSchemaController`| +|[`AdminRegistrationController`](api:SilverStripe\MFA\Controller\AdminRegistrationController)|`LeftAndMain`|`AdminController`| +|[`LinkFieldController`](api:SilverStripe\LinkField\Controllers\LinkFieldController)|`LeftAndMain`|`FormSchemaController`| +|[`SubsiteXHRController`](api:SilverStripe\Subsites\Controller\SubsiteXHRController)|`LeftAndMain`|`AdminController`| +|[`CMSExternalLinksController`](api:SilverStripe\ExternalLinks\Controllers\CMSExternalLinksController)|`Controller`|`AdminController`| The `tree_class` configuration property on `LeftAndMain` and its subclasses has be renamed to [`model_class`](api:SilverStripe\Admin\LeftAndMain->model_class). This is used in methods like [`getRecord()`](api:SilverStripe\Admin\LeftAndMain::getRecord()) to get a record of the correct class. @@ -780,7 +791,8 @@ Note that the change from `ViewableData` to `ModelData` specifically was made to ### GraphQL removed from the CMS {#graphql-removed} -> [!INFO] If you need to use GraphQL in your project for public-facing frontend schemas, you can still install and use the [`silverstripe/graphql`](https://github.com/silverstripe/silverstripe-graphql) module. +> [!NOTE] +> If you need to use GraphQL in your project for public-facing frontend schemas, you can still install and use the [`silverstripe/graphql`](https://github.com/silverstripe/silverstripe-graphql) module. GraphQL has been removed from the admin section of the CMS and is no longer installed when creating a new project using [`silverstripe/installer`](https://github.com/silverstripe/silverstripe-installer), or an existing project that uses [`silverstripe/recipe-cms`](https://github.com/silverstripe/recipe-cms). All existing functionality in the CMS that previously relied on GraphQL has been migrated to use regular Silverstripe CMS controllers instead. @@ -798,7 +810,7 @@ Core implementations of most extension hooks such as `updateCMSFields()` now hav In order to better align the codebase in Silverstripe CMS with best practices, the following extension hook methods have changed name: -|class that defined the hook|old name|new name| +|Class that defined the hook|Old name|New name| |---|---|---| |[`Member`](api:SilverStripe\Security\Member)|`afterMemberLoggedIn`|`onAfterMemberLoggedIn`| |[`Member`](api:SilverStripe\Security\Member)|`afterMemberLoggedOut`|`onAfterMemberLoggedOut`| @@ -851,7 +863,7 @@ Injector::inst()->load([ The class names for the `TopPage` feature in [`dnadesign/silverstripe-elemental`](https://github.com/silverstripe/silverstripe-elemental) did not follow the correct naming convention for Silverstripe CMS. The class names have been changed as follows: -|old name|new name| +|Old name|New name| |---|---| |`DNADesign\Elemental\TopPage\DataExtension`|`DNADesign\Elemental\Extensions\TopPageElementExtension`| |`DNADesign\Elemental\TopPage\FluentExtension`|`DNADesign\Elemental\Extensions\TopPageElementFluentExtension`|