From 0a33e3ade5c5894decb6a5621fb2d0dd55f9802e Mon Sep 17 00:00:00 2001 From: soupette Date: Thu, 30 Jan 2020 14:42:53 +0100 Subject: [PATCH] Add documentation about the settings api Signed-off-by: soupette --- .../frontend-settings-api.md | 193 ++++++++++++++++++ .../plugins/myplugin/admin/src/index.js | 1 - .../SettingsPage/SettingDispatcher.js | 2 +- 3 files changed, 194 insertions(+), 2 deletions(-) create mode 100644 docs/3.0.0-beta.x/plugin-development/frontend-settings-api.md diff --git a/docs/3.0.0-beta.x/plugin-development/frontend-settings-api.md b/docs/3.0.0-beta.x/plugin-development/frontend-settings-api.md new file mode 100644 index 0000000000..712dd36f57 --- /dev/null +++ b/docs/3.0.0-beta.x/plugin-development/frontend-settings-api.md @@ -0,0 +1,193 @@ +# Plugin's front-end settings API + +As plugins developer you may need to add some settings into the main application **`Settings`** view (it corresponds to the `Settings` link located in the menu). To do so an API is available in order for a plugin to add links into the main view. + +These settings can be declared directly into the main plugin object so they will dynamically be injected into the view. + +## Adding a setting + +The front-end part of a plugin exports a function which registers the plugin in the administration panel. The argument is composed of two main paramenters: + +- `registerPlugin`: `Function` +- `settingsBaseURL`: `String` + +### Creating the links into the view's menu + +Each plugin that comes with a setting object will create a new section into the view's menu. + +The menu section can be declared as follows: + +**Path —** `plugins/my-plugin/admin/src/index.js`. + +``` +import pluginPkg from '../../package.json'; +import pluginId from './pluginId'; + +export default strapi => { + const pluginDescription = + pluginPkg.strapi.description || pluginPkg.description; + + // Declare the links that will be injected into the settings menu + const menuSection = { + // Unique id of the section + id: pluginId, + // Title of Menu section using i18n + title: { + id: `${pluginId}.foo`, + defaultMessage: 'Super cool setting', + }, + // Array of links to be displayed + links: [ + { + // Using string + title: 'Setting page 1', + to: `${strapi.settingsBaseURL}/${pluginId}/setting1`, + name: 'setting1', + }, + { + // Using i18n with a corresponding translation key + title: { + id: `${pluginId}.bar`, + defaultMessage: 'Setting page 2', + }, + to: `${strapi.settingsBaseURL}/${pluginId}/setting2`, + name: 'setting2', + }, + ], + }; + + const plugin = { + blockerComponent: null, + blockerComponentProps: {}, + description: pluginDescription, + icon: pluginPkg.strapi.icon, + id: pluginId, + initializer: () => null, + injectedComponents: [], + isReady: true, + leftMenuLinks: [], + leftMenuSections: [], + mainComponent: null, + name: pluginPkg.strapi.name, + preventComponentRendering: false, + settings: { + menuSection, + }, + trads: {}, + }; + + return strapi.registerPlugin(plugin); +}; +``` + +At this point, the plugin creates a new section (**_Super cool setting_**) which will contains two links `Setting page 1` and `Setting page 2` these links doesn't point to any component as the corresponding as not been declared yet. + +### Declaring the setting Component + +The exported Setting component which receives `settingsBaseURL` as props in order to generate a dynamic routing which should be used to associated the two endpoints created with their corresponding components. + +With the configuration from above we could easily create our plugin Settings view. + +**Path —** `plugins/my-plugin/admin/src/containers/Settings/index.js`. + +``` +import React from 'react'; +import PropTypes from 'prop-types'; +import { Switch, Route } from 'react-router-dom'; +import pluginId from '../../pluginId'; + +const SettingPage1 = () => ( +
+

Setting Page 1

+
+); +const SettingPage2 = () => ( +
+

Setting Page 2

+
+); + +const Settings = ({ settingsBaseURL }) => { + return ( + + + + + ); +}; + +Settings.propTypes = { + settingsBaseURL: PropTypes.string.isRequired, +}; + +export default Settings; +``` + +Now that the `Settings` component is declared in your plugin the only thing left is to add it to your settings configuration: + +**Path —** `plugins/my-plugin/admin/src/index.js`. + +``` +import pluginPkg from '../../package.json'; +// Import the component +import Settings from './containers/Settings'; +import pluginId from './pluginId'; + +export default strapi => { + const pluginDescription = + pluginPkg.strapi.description || pluginPkg.description; + + // Declare the links that will be injected into the settings menu + const menuSection = { + id: pluginId, + title: { + id: `${pluginId}.foo`, + defaultMessage: 'Super cool setting', + }, + links: [ + { + title: 'Setting page 1', + to: `${strapi.settingsBaseURL}/${pluginId}/setting1`, + name: 'setting1', + }, + { + title: { + id: `${pluginId}.bar`, + defaultMessage: 'Setting page 2', + }, + to: `${strapi.settingsBaseURL}/${pluginId}/setting2`, + name: 'setting2', + }, + ], + }; + + const plugin = { + blockerComponent: null, + blockerComponentProps: {}, + description: pluginDescription, + icon: pluginPkg.strapi.icon, + id: pluginId, + initializer: () => null, + injectedComponents: [], + isReady: true, + leftMenuLinks: [], + leftMenuSections: [], + mainComponent: null, + name: pluginPkg.strapi.name, + preventComponentRendering: false, + settings: { + mainComponent: Settings, + menuSection, + }, + trads: {}, + }; + + return strapi.registerPlugin(plugin); +}; +``` diff --git a/examples/getstarted/plugins/myplugin/admin/src/index.js b/examples/getstarted/plugins/myplugin/admin/src/index.js index f88a4bb535..656bb106d3 100644 --- a/examples/getstarted/plugins/myplugin/admin/src/index.js +++ b/examples/getstarted/plugins/myplugin/admin/src/index.js @@ -1,5 +1,4 @@ import pluginPkg from '../../package.json'; - import pluginId from './pluginId'; export default strapi => { diff --git a/packages/strapi-admin/admin/src/containers/SettingsPage/SettingDispatcher.js b/packages/strapi-admin/admin/src/containers/SettingsPage/SettingDispatcher.js index d0df68ed44..95bb327d87 100644 --- a/packages/strapi-admin/admin/src/containers/SettingsPage/SettingDispatcher.js +++ b/packages/strapi-admin/admin/src/containers/SettingsPage/SettingDispatcher.js @@ -19,7 +19,7 @@ const SettingDispatcher = () => { const Compo = pluginToRender; - return ; + return ; }; export default memo(SettingDispatcher);