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 = () => ( +