+ );
+ }
+ },
+ )
+];
+```
+
+### Available Setting Types
+
+This is a list of setting types available by default:
+
+**Toggle:** `bool` or `checkbox` or `switch` or `boolean`
+
+**Textarea:** `textarea`
+
+**Color Picker:** `color-preview`
+
+**Text Input**: `text` or any HTML input types such as `tel` or `number`
+
+```ts
+{
+ setting: 'setting_unique_key',
+ label: app.translator.trans('acme-interstellar.admin.settings.setting_unique_key', {}, true),
+ type: 'bool' // Any of the mentioned values above
+}
+```
+
+**Selection:** `select` or `dropdown` or `selectdropdown`
+
+```ts
+{
+ setting: 'setting_unique_key',
+ label: app.translator.trans('acme-interstellar.admin.settings.setting_unique_key', {}, true),
+ type: 'select', // Any of the mentioned values above
+ options: {
+ 'option_key': 'Option Label',
+ 'option_key_2': 'Option Label 2',
+ 'option_key_3': 'Option Label 3',
+ },
+ default: 'option_key'
+}
+```
+
+**Image Upload Button:** `image-upload`
+
+```ts
+{
+ setting: 'setting_unique_key',
+ label: app.translator.trans('acme-interstellar.admin.settings.setting_unique_key', {}, true),
+ type: 'image-upload',
+ name: 'my_image_name', // The name of the image, this will be used for the request to the backend.
+ routePath: '/upload-my-image', // The route to upload the image to.
+ url: () => app.forum.attribute('myImageUrl'), // The URL of the image, this will be used to preview the image.
+}
```
### Registering Permissions
-New in beta 15, permissions can now be found in 2 places. Now, you can view each extension's individual permissions on their page. All permissions can still be found on the permissions page.
+Permissions can be found in 2 places. You can view each extension's individual permissions on their dedicated page, or you can view all permissions in the main permissions page.
-In order for that to happen, permissions must be registered with `ExtensionData`. This is done in a similar way to settings, call `registerPermission`.
+In order for that to happen, permissions must be registered using the `permission` method of the `Admin` extender, similar to how settings are registered.
Arguments:
* Permission object
@@ -127,21 +187,22 @@ Arguments:
Back to our favorite rocket extension:
```js
-app.initializers.add('interstellar', function(app) {
+import Extend from 'flarum/common/extenders';
+import app from 'flarum/admin/app';
- app.extensionData
- .for('acme-interstellar')
- .registerPermission(
- {
+return [
+ new Extend.Admin()
+ .permission(
+ () => ({
icon: 'fas fa-rocket', // Font-Awesome Icon
- label: app.translator.trans('acme-interstellar.admin.permissions.fly_rockets_label'), // Permission Label
+ label: app.translator.trans('acme-interstellar.admin.permissions.fly_rockets_label', {}, true), // Permission Label
permission: 'discussion.rocket_fly', // Actual permission name stored in database (and used when checking permission).
tagScoped: true, // Whether it be possible to apply this permission on tags, not just globally. Explained in the next paragraph.
- },
+ }),
'start', // Category permission will be added to on the grid
95 // Optional: Priority
- );
-});
+ )
+];
```
If your extension interacts with the [tags extension](https://github.com/flarum/tags) (which is fairly common), you might want a permission to be tag scopable (i.e. applied on the tag level, not just globally). You can do this by including a `tagScoped` attribute, as seen above. Permissions starting with `discussion.` will automatically be tag scoped unless `tagScoped: false` is indicated.
@@ -153,17 +214,23 @@ To learn more about Flarum permissions, see [the relevant docs](permissions.md).
Remember these functions can all be chained like:
```js
-app.extensionData
- .for('acme-interstellar')
- .registerSetting(...)
- .registerSetting(...)
- .registerPermission(...)
- .registerPermission(...);
+import Extend from 'flarum/common/extenders';
+import app from 'flarum/admin/app';
+
+return [
+ new Extend.Admin()
+ .setting(...)
+ .permission(...)
+ .permission(...)
+ .permission(...)
+ .setting(...)
+ .setting(...)
+];
```
### Extending/Overriding the Default Page
-Sometimes you have more complicated settings that mess with relationships, or just want the page to look completely different. In this case, you will need to tell `ExtensionData` that you want to provide your own page. Note that `buildSettingComponent`, the util used to register settings by providing a descriptive object, is available as a method on `ExtensionPage` (extending from `AdminPage`, which is a generic base for all admin pages with some util methods).
+Sometimes you may have more complicated settings, or just want the page to look completely different. In this case, you will need to tell the `Admin` extender that you want to provide your own page. Note that `buildSettingComponent`, the util used to register settings by providing a descriptive object, is available as a method on `ExtensionPage` (extending from `AdminPage`, which is a generic base for all admin pages with some util methods).
Create a new class that extends the `Page` or `ExtensionPage` component:
@@ -180,35 +247,89 @@ export default class StarPage extends ExtensionPage {
```
-Then, simply run `registerPage`:
+Then, simply use the `page` method of the extender:
```js
+import Extend from 'flarum/common/extenders';
+import app from 'flarum/admin/app';
import StarPage from './components/StarPage';
-app.initializers.add('interstellar', function(app) {
-
- app.extensionData
- .for('acme-interstellar')
- .registerPage(StarPage);
-});
+return [
+ new Extend.Admin()
+ .page(StarPage)
+];
```
This page will be shown instead of the default.
You can extend the [`ExtensionPage`](https://api.docs.flarum.org/js/master/class/src/admin/components/extensionpage.js~extensionpage) or extend the base `Page` and design your own!
+### Admin Search
+
+The admin dashboard has a search bar that allows you to quickly find settings and permissions. If you have used the `Admin.settings` and `Admin.permissions` extender methods, your settings and permissions will be automatically indexed and searchable. However, if you have a custom setting, or custom page that structures its content differently, then you must manually add index entries that reference your custom settings.
+
+To do this, you can use the `Admin.generalIndexItems` extender method. This method takes a callback that returns an array of index items. Each index item is an object with the following properties:
+
+```ts
+export type GeneralIndexItem = {
+ /**
+ * The unique identifier for this index item.
+ */
+ id: string;
+ /**
+ * Optional: The tree path to this item, used for grouping in the search results.
+ */
+ tree?: string[];
+ /**
+ * The label to display in the search results.
+ */
+ label: string;
+ /**
+ * Optional: The description to display in the search results.
+ */
+ help?: string;
+ /**
+ * Optional: The URL to navigate to when this item is selected.
+ * The default is to navigate to the extension page.
+ */
+ link?: string;
+ /**
+ * Optional: A callback that returns a boolean indicating whether this item should be visible in the search results.
+ */
+ visible?: () => boolean;
+};
+```
+
+Here is an example of how to add an index item:
+
+```js
+import Extend from 'flarum/common/extenders';
+import app from 'flarum/admin/app';
+
+return [
+ new Extend.Admin()
+ .generalIndexItems(() => [
+ {
+ id: 'acme-interstellar',
+ label: app.translator.trans('acme-interstellar.admin.acme_interstellar_label', {}, true),
+ help: app.translator.trans('acme-interstellar.admin.acme_interstellar_help', {}, true),
+ },
+ ])
+];
+```
+
## Composer.json Metadata
-In beta 15, extension pages make room for extra info which is pulled from extensions' composer.json.
+Extension pages make room for extra info which is pulled from extensions' composer.json.
For more information, see the [composer.json schema](https://getcomposer.org/doc/04-schema.md).
-| Description | Where in composer.json |
-| --------------------------------- | -------------------------------------- |
-| discuss.flarum.org discussion link | "forum" key inside "support" |
-| Documentation | "docs" key inside "support" |
-| Support (email) | "email" key inside "support" |
-| Website | "homepage" key |
-| Donate | "funding" key block (Note: Only the first link will be used) |
-| Source | "source" key inside "support" |
+| Description | Where in composer.json |
+|------------------------------------|--------------------------------------------------------------|
+| discuss.flarum.org discussion link | "forum" key inside "support" |
+| Documentation | "docs" key inside "support" |
+| Support (email) | "email" key inside "support" |
+| Website | "homepage" key |
+| Donate | "funding" key block (Note: Only the first link will be used) |
+| Source | "source" key inside "support" |
diff --git a/docs/extend/api.md b/docs/extend/api.md
index 0f1ad5322..e58294178 100644
--- a/docs/extend/api.md
+++ b/docs/extend/api.md
@@ -12,348 +12,1022 @@ To use the built-in REST API as part of an integration, see [Consuming the REST
Before we go into detail about how to extend Flarum's data API, it's worth thinking about the lifecycle of a typical API request:
-
+
1. An HTTP request is sent to Flarum's API. Typically, this will come from the Flarum frontend, but external programs can also interact with the API. Flarum's API mostly follows the [JSON:API](https://jsonapi.org/) specification, so accordingly, requests should follow [said specification](https://jsonapi.org/format/#fetching).
-2. The request is run through [middleware](middleware.md), and routed to the proper controller. You can learn more about controllers as a whole on our [routes and content documentation](routes.md). Assuming the request is to the API (which is the case for this section), the controller that handles the request will be a subclass of `Flarum\Api\AbstractSerializeController`.
-3. Any modifications done by extensions to the controller via the [`ApiController` extender](#extending-api-controllers) are applied. This could entail changing sort, adding includes, changing the serializer, etc.
-4. The `$this->data()` method of the controller is called, yielding some raw data that should be returned to the client. Typically, this data will take the form of a Laravel Eloquent model collection or instance, which has been retrieved from the database. That being said, the data could be anything as long as the controller's serializer can process it. Each controller is responsible for implementing its own `data` method. Note that for `PATCH`, `POST`, and `DELETE` requests, `data` will perform the operation in question, and return the modified model instance.
-5. That data is run through any pre-serialization callbacks that extensions register via the [`ApiController` extender](#extending-api-controllers).
-6. The data is passed through a [serializer](#serializers), which converts it from the backend, database-friendly format to the JSON:API format expected by the frontend. It also attaches any related objects, which are run through their own serializers. As we'll explain below, extensions can [add / override relationships and attributes](#attributes-and-relationships) at the serialization level.
+2. The request is run through [middleware](middleware.md), and routed to the proper API resource endpoint. Each API Resource is distinguished by a unique type and has a set of endpoints. You can read more about them in the below sections.
+3. Any modifications done by extensions to the API Resource endpoints via the [`ApiResource` extender](#extending-api-resources) are applied. This could entail changing sort, adding includes, eager loading relations, or executing some logic before and/or after the default implementation runs.
+4. The action of the endpoint is called, yielding some raw data that should be returned to the client. Typically, this data will take the form of a Laravel Eloquent model collection or instance, which has been retrieved from the database. That being said, the data could be anything as long as the API resource can process it. There are built-in reusable endpoint for CRUD operations, but custom endpoints can be implemented as well.
+5. Any modifications made through the [`ApiResource` extender](#extending-api-resources) to the API resource's fields will be applied. These can include adding new attributes or relationships to serialize, removing existing ones, or changing how the field value is computed.
+6. The fields (attributes and relationships) are serialized, converting the data from the backend database-friendly format to the JSON:API format expected by the frontend.
7. The serialized data is returned as a JSON response to the frontend.
8. If the request originated via the Flarum frontend's `Store`, the returned data (including any related objects) will be stored as [frontend models](#frontend-models) in the frontend store.
-## API Endpoints
+## API Resources
We learned how to use models to interact with data, but we still need to get that data from the backend to the frontend.
-We do this by writing API Controller [routes](routes.md), which implement logic for API endpoints.
+We do this by writing an API Resource for the model, which defines the fields (attributes and relationships) of the model, the endpoints of the resource API, and optionally some extra logic, such as visibility scoping, sorting options, etc. We will learn about this in the next few sections.
-As per the JSON:API convention, we'll want to add separate endpoints for each operation we support. Common operations are:
+CRUD endpoints are provided by Flarum, so you can simply add them to your API resource's `endpoints()` method. They are:
-- Listing instances of a model (possibly including searching/filtering)
-- Getting a single model instance
-- Creating a model instance
-- Updating a model instance
-- Deleting a single model instance
+- `Index`: Listing many instances of a model (possibly including searching/filtering)
+- `Show`: Getting a single model instance
+- `Create`: Creating a model instance
+- `Update`: Updating a model instance
+- `Delete`: Deleting a single model instance
-We'll go over each type of controller shortly, but once they're written, you can add these five standard endpoints (or a subset of them) using the `Routes` extender:
+:::info
-```php
- (new Extend\Routes('api'))
- ->get('/tags', 'tags.index', ListTagsController::class)
- ->get('/tags/{id}', 'tags.show', ShowTagController::class)
- ->post('/tags', 'tags.create', CreateTagController::class)
- ->patch('/tags/{id}', 'tags.update', UpdateTagController::class)
- ->delete('/tags/{id}', 'tags.delete', DeleteTagController::class)
+Flarum uses a forked version of Toby Zerner's [json-api-server](https://tobyzerner.github.io/json-api-server/). So some of what is documented there applies in Flarum, but not everything is the same.
+
+:::
+
+:::tip [Flarum CLI](https://github.com/flarum/cli)
+
+You can use the CLI to automatically create your API resource:
+```bash
+$ flarum-cli make backend api-resource
```
-:::caution
+:::
-Paths to API endpoints are not arbitrary! To support interactions with frontend models:
+***Example:*** if you had a `Label` model, the `LabelResource` you would create could look something like this:
-- The path should either be `/prefix/{id}` for get/update/delete, or `/prefix` for list/create.
-- the prefix (`tags` in the example above) must correspond to the JSON:API model type. You'll also use this model type in your serializer's `$type` attribute, and when registering the frontend model (`app.store.models.TYPE = MODEL_CLASS`).
-- The methods must match the example above.
+```php
+namespace Acme\Api;
-Also, remember that route names (`tags.index`, `tags.show`, etc) must be unique!
+use Acme\Label;
+use Flarum\Api\Context;
+use Flarum\Api\Endpoint;
+use Flarum\Api\Resource\AbstractDatabaseResource;
+use Flarum\Api\Schema;
-:::
+/** @extends AbstractDatabaseResource