+ +:::strapi Additional resources +The Strapi blog features a [tutorial series](https://strapi.io/blog/how-to-create-a-strapi-v4-plugin-server-customization-4-6) about creating a Strapi v4 'Todo' plugin. The [contributors documentation](https://contributor.strapi.io/) can also include additional information useful while developing a Strapi plugin. +::: diff --git a/docusaurus/docs/dev-docs/plugins/development/create-a-plugin.md b/docusaurus/docs/dev-docs/plugins/development/create-a-plugin.md new file mode 100644 index 0000000000..aab1c8efff --- /dev/null +++ b/docusaurus/docs/dev-docs/plugins/development/create-a-plugin.md @@ -0,0 +1,314 @@ +--- +title: Plugin creation & setup +description: Learn how to create a Strapi plugin and how to start the development servers +pagination_next: dev-docs/plugins/development/plugin-structure +--- + +# Plugin creation and setup + +To start developing a Strapi plugin, you need to: + +1. create the plugin, +2. enable the plugin, +3. install dependencies, build the admin panel, and start the server(s). + +:::prerequisites +You created a Strapi project. +
+
+
+
+
+```bash
+yarn create strapi-app my-project --quickstart
+```
+
+
+
+
+
+```bash
+npx create-strapi-app@latest my-project --quickstart
+```
+
+
+
+
+
+More details can be found in the [CLI installation guide](/dev-docs/installation/cli).
+
+:::
+
+## Create the plugin using the CLI generator
+
+The fastest way to create a Strapi plugin is to use the CLI generator. To do so:
+
+1. Navigate to the root of an existing Strapi project, or create a new one.
+2. Run the following command in a terminal window to start the interactive CLI:
+
+ Use the CLI to create a project:
+ +Run the corresponding command in a terminal window, replacing `my-project` with the name of your choice: + +If created from a Strapi project using the CLI generator, plugins are located in the `src/plugins` folder (see [project structure](/dev-docs/project-structure)). + +2. Run the following command in the newly-created plugin directory to install plugin dependencies: + +
If created from a Strapi project using the CLI generator, plugins are located in the `src/plugins` folder (see [project structure](/dev-docs/project-structure)). + +2. Run the following command in the newly-created plugin directory to install plugin dependencies: + +
+ +:::note Notes about the usefulness of the different parts for your specific use case +- **Server-only plugin**: You can create a plugin that will just use the server part to enhance the API of your application. For instance, this plugin could have its own visible or invisible content-types, controller actions, and routes that are useful for a specific use case. In such a scenario, you don't need your plugin to have an interface in the admin panel. + +- **Admin panel plugin vs. application-specific customization**: You can create a plugin to inject some components into the admin panel. However, you can also achieve this by creating a `./src/admin/app.js` file and invoking the `bootstrap` lifecycle function to inject your components. In this case, deciding whether to create a plugin depends on whether you plan to reuse and distribute the code or if it's only useful for a unique Strapi application. +::: + +
+ +:::strapi What to read next? +The next steps of your Strapi plugin development journey will require you to use any of the Strapi plugins APIs. + +2 different types of resources help you understand how to use the plugin APIs: + +- The reference documentation for the [Admin Panel API](/dev-docs/api/plugins/admin-panel-api) and [Server API](/dev-docs/api/plugins/server-api) give an overview of what is possible to do with a Strapi plugin. +- [Guides](/dev-docs/plugins/developing-plugins#guides) cover some specific, use-case based examples. +::: diff --git a/docusaurus/docs/dev-docs/plugins/guides/marketplace.md b/docusaurus/docs/dev-docs/plugins/guides/marketplace.md new file mode 100644 index 0000000000..3ce1887eb6 --- /dev/null +++ b/docusaurus/docs/dev-docs/plugins/guides/marketplace.md @@ -0,0 +1,203 @@ +--- +title: Publishing a Strapi plugin to the Marketplace +# description: todo +displayed_sidebar: devDocsSidebar +--- + +# Publishing your Strapi plugin + +_Coming soonβ¦_ + +:::tip +Check [this blog post](https://strapi.io/blog/how-to-create-a-strapi-v4-plugin-publish-on-npm-6-6) to learn how to publish your Strapi plugin on npm. +::: + + + + diff --git a/docusaurus/docs/dev-docs/plugins/guides/pass-data-from-server-to-admin.md b/docusaurus/docs/dev-docs/plugins/guides/pass-data-from-server-to-admin.md new file mode 100644 index 0000000000..bc82d0e3d5 --- /dev/null +++ b/docusaurus/docs/dev-docs/plugins/guides/pass-data-from-server-to-admin.md @@ -0,0 +1,101 @@ +--- +title: How to pass data from server to admin panel with a Strapi plugin +description: Learn how to pass data from server to admin panel with a Strapi plugin +sidebar_label: Pass data from server to admin +displayed_sidebar: devDocsSidebar +--- + +# How to pass data from server to admin panel with a Strapi plugin + +Strapi is **headless**
+ strapi generate content-type CLI generator is used to create a basic content-type for a plugin.+ +The CLI will generate some code required to use your plugin, which includes the following: + +- the [content-type schema](/dev-docs/backend-customization/models#model-schema) +- and a basic [controller](/dev-docs/backend-customization/controllers), [service](/dev-docs/backend-customization/services), and [route](/dev-docs/backend-customization/routes) for the content-type + +:::tip +You may want to create the whole structure of your content-types either entirely with the CLI generator or by directly creating and editing `schema.json` files. We recommend you first create a simple content-type with the CLI generator and then leverage the [Content-Type Builder](/user-docs/content-type-builder) in the admin panel to edit your content-type. + +If your content-type is not visible in the admin panel, you might need to set the `content-manager.visible` and `content-type-builder.visible` parameters to `true` in the `pluginOptions` object of the content-type schema: + +
+
+:::
+
+### Ensure plugin content-types are imported
+
+The CLI generator might not have imported all the related content-type files for your plugin, so you might have to make the following adjustments after the `strapi generate content-type` CLI command has finished running:
+
+1. In the `/server/index.js` file, import the content-types:
+
+ ```js {7,22} showLineNumbers title="/server/index.js"
+ 'use strict';
+
+ const register = require('./register');
+ const bootstrap = require('./bootstrap');
+ const destroy = require('./destroy');
+ const config = require('./config');
+ const contentTypes = require('./content-types');
+ const controllers = require('./controllers');
+ const routes = require('./routes');
+ const middlewares = require('./middlewares');
+ const policies = require('./policies');
+ const services = require('./services');
+
+ module.exports = {
+ register,
+ bootstrap,
+ destroy,
+ config,
+ controllers,
+ routes,
+ services,
+ contentTypes,
+ policies,
+ middlewares,
+ };
+
+ ```
+
+2. In the `/server/content-types/index.js` file, import the content-type folder:
+
+ ```js title="/server/content-types/index.js"
+ 'use strict';
+
+ module.exports = {
+ // In the line below, replace my-plugin-content-type
+ // with the actual name and folder path of your content type
+ "my-plugin-content-type": require('./my-plugin-content-type'),
+ };
+ ```
+
+3. Ensure that the `/server/content-types/[your-content-type-name]` folder contains not only the `schema.json` file generated by the CLI, but also an `index.js` file that exports the content-type with the following code:
+
+ ```js title="/server/content-types/my-plugin-content-type/index.js
+ 'use strict';
+
+ const schema = require('./schema');
+
+ module.exports = {
+ schema,
+ };
+ ```
+
+## Interact with data from the plugin
+
+Once you have created a content-type for your plugin, you can create, read, update, and delete data.
+
+:::note
+A plugin can only interact with data from the `/server` folder. If you need to update data from the admin panel, please refer to the [passing data guide](/dev-docs/plugins/guides/pass-data-from-server-to-admin).
+:::
+
+To create, read, update, and delete data, you can use either the [Entity Service API](/dev-docs/api/entity-service) or the [Query Engine API](/dev-docs/api/query-engine). While it's recommended to use the Entity Service API, especially if you need access to components or dynamic zones, the Query Engine API is useful if you need unrestricted access to the underlying database.
+
+Use the `plugin::your-plugin-slug.the-plugin-content-type-name` syntax for content-type identifiers in Entity Service and Query Engine API queries.
+
+**Example:**
+
+Here is how to find all the entries for the `my-plugin-content-type` collection type created for a plugin called `my-plugin`:
+
+```js
+// Using the Entity Service API
+let data = await strapi.entityService.findMany('plugin::my-plugin.my-plugin-content-type');
+
+// Using the Query Engine API
+let data = await strapi.db.query('plugin::my-plugin.my-plugin-content-type').findMany();
+````
+
+:::tip
+You can access the database via the `strapi` object which can be found in `middlewares`, `policies`, `controllers`, `services`, as well as from the `register`, `boostrap`, `destroy` lifecycle functions.
+:::
diff --git a/docusaurus/sidebars.js b/docusaurus/sidebars.js
index f287a0d137..c334483cda 100644
--- a/docusaurus/sidebars.js
+++ b/docusaurus/sidebars.js
@@ -215,15 +215,6 @@ const sidebars = {
"dev-docs/api/query-engine/order-pagination",
],
},
- {
- type: 'category',
- label: 'APIs for plugins',
- collapsed: false,
- items: [
- 'dev-docs/api/plugins/admin-panel-api',
- 'dev-docs/api/plugins/server-api',
- ]
- },
]
},
{
@@ -300,14 +291,7 @@ const sidebars = {
}
]
},
- 'dev-docs/plugins-extension',
- 'dev-docs/plugins-development',
'dev-docs/typescript',
- {
- type: 'doc',
- label: 'Custom fields',
- id: 'dev-docs/custom-fields',
- },
{
type: "doc",
label: "Providers",
@@ -465,6 +449,8 @@ const sidebars = {
label: 'Introduction',
id: 'dev-docs/plugins/developing-plugins'
},
+ 'dev-docs/plugins/development/create-a-plugin',
+ 'dev-docs/plugins/development/plugin-structure',
{
type: 'doc',
id: 'dev-docs/api/plugins/admin-panel-api',
@@ -477,6 +463,18 @@ const sidebars = {
},
'dev-docs/custom-fields',
'dev-docs/plugins-extension',
+ {
+ type: 'category',
+ label: 'Guides',
+ link: {
+ type: 'doc',
+ id: 'dev-docs/plugins/developing-plugins',
+ },
+ items: [
+ 'dev-docs/plugins/guides/store-and-access-data',
+ 'dev-docs/plugins/guides/pass-data-from-server-to-admin',
+ ]
+ }
]
}
]
diff --git a/docusaurus/src/components/PluginStructure.js b/docusaurus/src/components/PluginStructure.js
new file mode 100644
index 0000000000..5e8073d801
--- /dev/null
+++ b/docusaurus/src/components/PluginStructure.js
@@ -0,0 +1,131 @@
+import React from 'react'
+import Tabs from '@theme/Tabs'
+import TabItem from '@theme/TabItem'
+
+export default function InteractivePluginStructure() {
+ return (
+ Making a plugin content-type visible in the admin panel:
+ +The following highlighted lines in an example `schema.json` file show how to make a plugin content-type visible to the Content-Type Builder and Content-Manager: + +```json title="/server/content-types/my-plugin-content-type/schema.json" {13-20} showLineNumbers +{ + "kind": "collectionType", + "collectionName": "my_plugin_content_types", + "info": { + "singularName": "my-plugin-content-type", + "pluralName": "my-plugin-content-types", + "displayName": "My Plugin Content-Type" + }, + "options": { + "draftAndPublish": false, + "comment": "" + }, + "pluginOptions": { + "content-manager": { + "visible": true + }, + "content-type-builder": { + "visible": true + } + }, + "attributes": { + "name": { + "type": "string" + } + } +} + +``` + +
+
+
+
+ The following diagram is interactive: you can click on any file or folder name highlighted in purple to go to the corresponding documentation section.
+ +
+
+
+
+ The following diagram is interactive: you can click on any file or folder name highlighted in purple to go to the corresponding documentation section.
+ +
+
+
+ );
+}
+
diff --git a/docusaurus/src/components/ReusableAnnotationComponents/ReusableAnnotationComponents.jsx b/docusaurus/src/components/ReusableAnnotationComponents/ReusableAnnotationComponents.jsx
new file mode 100644
index 0000000000..0e60356ccf
--- /dev/null
+++ b/docusaurus/src/components/ReusableAnnotationComponents/ReusableAnnotationComponents.jsx
@@ -0,0 +1,36 @@
+import React from 'react'
+import { Annotation } from '../Annotation';
+
+export function PluginsConfigurationFile() {
+ return (
+ + +
+
+ . # root of the plugin folder (e.g., /src/plugins/my-plugin)
+ βββ admin # Admin panel part of your plugin.
+ β βββ src
+ β βββ components # Contains your front-end components
+ β β βββ Initializer
+ β β β βββ index.js # Plugin initializer
+ β β βββ PluginIcon
+ β β βββ index.js # Contains the icon of your plugin in the main navigation
+ β βββ pages # Contains the pages of your plugin
+ β β βββ App
+ β β β βββ index.js # Skeleton around the actual pages
+ β β βββ HomePage
+ β β βββ index.js # Homepage of your plugin
+ β βββ translations # Translations files to make your plugin i18n-friendly
+ β β βββ en.json
+ β β βββ fr.json
+ β βββ utils
+ β β βββ getTrad.js # getTrad function to return the corresponding plugin translations
+ β βββ index.js # Main setup of your plugin, used to register elements in the admin panel
+ β βββ pluginId.js # pluginId variable computed from package.json name
+ βββ node_modules
+ βββ server # Back-end part of your plugin
+ β βββ config
+ β β βββ index.js # Contains the default server configuration
+ β βββ content-types # Content-types specific to your plugin
+ β β βββ index.js # Loads all the plugin's content-types
+ β βββ controllers # Controllers specific to your plugin
+ β β βββ index.js # Loads all the plugin's controllers
+ β β βββ my-controller.js # Custom controller example. You can rename it or delete it.
+ β βββ middlewares # Middlewares specific to your plugin
+ β β βββ index.js # Loads all the plugin's middlewares
+ β βββ policies # Policies specific to your plugin
+ β β βββ index.js # Loads all the plugin's policies
+ β βββ routes # Routes specific to your plugin
+ β β βββ index.js # Contains an example route for the my-controller custom controller example
+ β βββ services # Services specific to your plugin
+ β β βββ index.js # Loads all the plugin's services
+ β β βββ my-service.js # Custom service example. You can rename it or delete it.
+ β βββ bootstrap.js # Function that is called right after the plugin has registered
+ β βββ destroy.js # Function that is called to clean up the plugin after Strapi instance is destroyed
+ β βββ index.js # Loads the code for all the server elements
+ β βββ register.js # Function that is called to load the plugin, before bootstrap.
+ βββ package.json
+ βββ README.md
+ βββ strapi-admin.js # Entrypoint for the admin panel (front end)
+ βββ strapi-server.js # Entrypoint for the server (back end)
+
+
+
+
+ + +
+
+ . # root of the plugin folder (e.g., /src/plugins/my-plugin)
+ βββ admin # Admin panel part of your plugin.
+ β βββ src
+ β βββ components # Contains your front-end components
+ β β βββ Initializer
+ β β β βββ index.tsx # Plugin initializer
+ β β βββ PluginIcon
+ β β βββ index.tsx # Contains the icon of your plugin in the main navigation
+ β βββ pages # Contains the pages of your plugin
+ β β βββ App
+ β β β βββ index.tsx # Skeleton around the actual pages
+ β β βββ HomePage
+ β β βββ index.tsx # Homepage of your plugin
+ β βββ translations # Translations files to make your plugin i18n-friendly
+ β β βββ en.json
+ β β βββ fr.json
+ β βββ utils
+ β β βββ getTrad.ts # getTrad function to return the corresponding plugin translations
+ β βββ index.tsx # Main setup of your plugin, used to register elements in the admin panel
+ β βββ pluginId.tsx # pluginId variable computed from package.tsxon name
+ βββ dist # Build of the backend
+ βββ node_modules
+ βββ server # Back-end part of your plugin
+ β βββ config
+ β β βββ index.ts # Contains the default server configuration
+ β βββ content-types # Content-types specific to your plugin
+ β β βββ index.ts # Loads all the plugin's content-types
+ β βββ controllers # Controllers specific to your plugin
+ β β βββ index.ts # Loads all the plugin's controllers
+ β β βββ my-controller.ts # Custom controller example. You can rename it or delete it.
+ β βββ middlewares # Middlewares specific to your plugin
+ β β βββ index.ts # Loads all the plugin's middlewares
+ β βββ policies # Policies specific to your plugin
+ β β βββ index.ts # Loads all the plugin's policies
+ β βββ routes # Routes specific to your plugin
+ β β βββ index.ts # Contains an example route for the my-controller custom controller example
+ β βββ services # Services specific to your plugin
+ β β βββ index.ts # Loads all the plugin's services
+ β β βββ my-service.ts # Custom service example. You can rename it or delete it.
+ β βββ bootstrap.ts # Function that is called right after the plugin has registered
+ β βββ destroy.ts # Function that is called to clean up the plugin after Strapi instance is destroyed
+ β βββ index.ts # Loads the code for all the server elements
+ β βββ register.ts # Function that is called to load the plugin, before bootstrap.
+ βββ custom.d.ts # Generated types
+ βββ package.json
+ βββ README.md
+ βββ strapi-admin.js # Entrypoint for the admin panel (front end)
+ βββ strapi-server.js # Entrypoint for the server (back end)
+ βββ tsconfig.json # TypeScript compiler options for the admin panel part
+ βββ tsconfig.server.json # TypeScript compiler options for the server part
+
+
+
+
+ The plugins configuration file config/plugins.js|ts:
+
-
+
- declares all plugins that are enabled, +
- and can be used to pass additional configuration options to some plugins. +
+ More details can be found in the plugins configuration documentation. +
++ A headless CMS is a Content Management System that separates the presentation layer (i.e., the front end, where content is displayed) from the back end (where content is managed). +
++ Strapi is a headless CMS that provides: +
-
+
- a back-end server exposing an API for your content, +
- and a graphical user interface, called the admin panel, to manage the content. +