This is an automated email from the ASF dual-hosted git repository. linkinstar pushed a commit to branch build-community-plugin in repository https://gitbox.apache.org/repos/asf/incubator-answer-website.git
commit 704b607f221ae8eb79da7516f505c5720690239e Author: LinkinStars <[email protected]> AuthorDate: Mon Nov 27 15:29:40 2023 +0800 docs(plugin): move docs plugins to community --- community/contributing/plugins.md | 115 ++++++++++++++++++- .../contributing/plugins}/plugin-config.md | 0 .../contributing/plugins}/plugin-for-ui.md | 0 .../contributing/plugins}/plugin-translation.md | 0 docs/development/extending/plugins.md | 123 +-------------------- sidebars.js | 22 +--- sidebarsCommunity.js | 15 ++- 7 files changed, 133 insertions(+), 142 deletions(-) diff --git a/community/contributing/plugins.md b/community/contributing/plugins.md index e8cb358b..51cc2b4b 100644 --- a/community/contributing/plugins.md +++ b/community/contributing/plugins.md @@ -5,14 +5,125 @@ slug: /plugins # Contribute for Plugins +:::tip +Viewing the official plugin code will make you to quickly understand and learn plugin development. + +https://github.com/apache/incubator-answer-plugins +::: + ## Plugin types Currently we have three types of plugins: -- Backend -- Builtin plugin +- Only Backend plugin +- Frontend Builtin plugin - Standard UI plugin +## Backend plugin +### Implement the Base interface +> The `Base` interface contains basic information about the plugin and is used to display. + +```go +// Info presents the plugin information +type Info struct { + Name Translator + SlugName string + Description Translator + Author string + Version string + Link string +} + +// Base is the base plugin +type Base interface { + // Info returns the plugin information + Info() Info +} +``` + +:::caution +The `SlugName` of the plugin must be unique. Two plugins with the same `SlugName` will panic when registering. +::: + +### Implement the function interface +:::note +Different plugin types require different interfaces of implementation. + +For example, following is the `Connector` plugin interface. +::: + +```go +type Connector interface { + Base + + // ConnectorLogoSVG presents the logo in svg format + ConnectorLogoSVG() string + + // ConnectorName presents the name of the connector + // e.g. Facebook, Twitter, Instagram + ConnectorName() Translator + + // ConnectorSlugName presents the slug name of the connector + // Please use lowercase and hyphen as the separator + // e.g. facebook, twitter, instagram + ConnectorSlugName() string + + // ConnectorSender presents the sender of the connector + // It handles the start endpoint of the connector + // receiverURL is the whole URL of the receiver + ConnectorSender(ctx *GinContext, receiverURL string) (redirectURL string) + + // ConnectorReceiver presents the receiver of the connector + // It handles the callback endpoint of the connector, and returns the + ConnectorReceiver(ctx *GinContext, receiverURL string) (userInfo ExternalLoginUserInfo, err error) +} +``` + +:::tip +`Translator` is a struct for translation. Please refer to [the documentation](/docs/plugins/plugin-translation) for details. +::: + + +### Implement the configuration interface +For details on the description of each configuration item, please refer to [the documentation](/docs/plugins/plugin-config). + +```go +type Config interface { + Base + + // ConfigFields returns the list of config fields + ConfigFields() []ConfigField + + // ConfigReceiver receives the config data, it calls when the config is saved or initialized. + // We recommend to unmarshal the data to a struct, and then use the struct to do something. + // The config is encoded in JSON format. + // It depends on the definition of ConfigFields. + ConfigReceiver(config []byte) error +} +``` + +### Register initialization function +```go +import "github.com/apache/incubator-answer/plugin" + +func init() { + plugin.Register(&GitHubConnector{ + Config: &GitHubConnectorConfig{}, + }) +} +``` + +### Debugging tips +:::tip +During the development and debugging phase, you can use the following tips to avoid repetitive packaging. +::: + +1. Use answer source code for development. +2. Write your plugin directly in the plugin directory. +3. Import your plugin in the main function + +After that you just need to start the answer project normally and it will contain the plugins you developed. + ## Registration and activation of plugins All types of plug-in activation registration (or display) logic are in the `ui/utils/pluginKit/index.ts` file. During the development process, you can modify `registerPlugins` or call `changePluginActiveStatus` either of these two methods. to control whether your plugin is displayed. diff --git a/docs/development/extending/plugin-config.md b/community/contributing/plugins/plugin-config.md similarity index 100% rename from docs/development/extending/plugin-config.md rename to community/contributing/plugins/plugin-config.md diff --git a/docs/development/extending/plugin-for-ui.md b/community/contributing/plugins/plugin-for-ui.md similarity index 100% rename from docs/development/extending/plugin-for-ui.md rename to community/contributing/plugins/plugin-for-ui.md diff --git a/docs/development/extending/plugin-translation.md b/community/contributing/plugins/plugin-translation.md similarity index 100% rename from docs/development/extending/plugin-translation.md rename to community/contributing/plugins/plugin-translation.md diff --git a/docs/development/extending/plugins.md b/docs/development/extending/plugins.md index c006f254..5c729cad 100644 --- a/docs/development/extending/plugins.md +++ b/docs/development/extending/plugins.md @@ -31,6 +31,8 @@ You can find a list of officially supported plugins for Answer [here](https://gi ### Prerequisites - Original Answer binary - [Golang](https://go.dev/) `>=1.18` +- [Node.js](https://nodejs.org/) `>=16.17` +- [pnpm](https://pnpm.io/) `>=7` ### Command :::tip @@ -87,124 +89,9 @@ We recommend the use of [official plugins](https://github.com/apache/incubator-a ## Upgrade You just need to recompile and use the latest version of the plugin. -## Develop -:::tip -Viewing the [official plugin](https://github.com/apache/incubator-answer-plugins) code will make you to quickly understand and learn plugin development. -::: - -### Backend Development -#### Implement the base -> The `Base` interface contains basic information about the plugin and is used to display. - -```go -// Info presents the plugin information -type Info struct { - Name Translator - SlugName string - Description Translator - Author string - Version string - Link string -} - -// Base is the base plugin -type Base interface { - // Info returns the plugin information - Info() Info -} -``` - -:::caution -The `SlugName` of the plugin must be unique. Two plugins with the same `SlugName` will panic when registering. -::: - -#### Implement the function interface -:::note -Different plugin types require different interfaces of implementation. - -For example, following is the `Connector` plugin interface. -::: - -```go -type Connector interface { - Base - - // ConnectorLogoSVG presents the logo in svg format - ConnectorLogoSVG() string - - // ConnectorName presents the name of the connector - // e.g. Facebook, Twitter, Instagram - ConnectorName() Translator - - // ConnectorSlugName presents the slug name of the connector - // Please use lowercase and hyphen as the separator - // e.g. facebook, twitter, instagram - ConnectorSlugName() string - - // ConnectorSender presents the sender of the connector - // It handles the start endpoint of the connector - // receiverURL is the whole URL of the receiver - ConnectorSender(ctx *GinContext, receiverURL string) (redirectURL string) - - // ConnectorReceiver presents the receiver of the connector - // It handles the callback endpoint of the connector, and returns the - ConnectorReceiver(ctx *GinContext, receiverURL string) (userInfo ExternalLoginUserInfo, err error) -} -``` - -:::tip -`Translator` is a struct for translation. Please refer to [the documentation](/docs/plugins/plugin-translation) for details. -::: - - -#### Implement the configuration interface -For details on the description of each configuration item, please refer to [the documentation](/docs/plugins/plugin-config). - -```go -type Config interface { - Base - - // ConfigFields returns the list of config fields - ConfigFields() []ConfigField - - // ConfigReceiver receives the config data, it calls when the config is saved or initialized. - // We recommend to unmarshal the data to a struct, and then use the struct to do something. - // The config is encoded in JSON format. - // It depends on the definition of ConfigFields. - ConfigReceiver(config []byte) error -} -``` - -#### Register initialization function -```go -import "github.com/apache/incubator-answer/plugin" - -func init() { - plugin.Register(&GitHubConnector{ - Config: &GitHubConnectorConfig{}, - }) -} -``` - -#### Debugging tips -:::tip -During the development and debugging phase, you can use the following tips to avoid repetitive packaging. -::: - -1. Use answer source code for development. -2. Write your plugin directly in the plugin directory. -3. Import your plugin in the main function - -After that you just need to start the answer project normally and it will contain the plugins you developed. - - -## Contributing -For plugin types that have not been implemented yet, please wait for the official implementation to be completed before contributing. -For existing plugin types, you can follow the steps below to contribute the plugin implementation to us. - -1. Submit an issue request to ensure that the official is not developing the same plug-in as you. -2. Get confirmation that you can develop your plugin, test it and submit a PR. -3. Wait for the PR merge, the official will include your plugin. +## Develop and Contributing +Please refer to [the documentation](/community/plugins) for details. ## Design & Principle Since Golang is a static language, there is no friendly plugin mechanism. So instead of a dynamic approach, we use recompilation for deployment. +Please refer to [the blog](/blog/2023/07/22/why-the-answer-plugin-system-was-designed-this-way) for details. diff --git a/sidebars.js b/sidebars.js index c71858b6..6c05fe99 100644 --- a/sidebars.js +++ b/sidebars.js @@ -44,27 +44,7 @@ module.exports = { 'guides/settings', ], }, - { - type: 'category', - label: 'Development', - collapsed: true, - items: [ - { - type: 'category', - label: 'Plugins', - link: { - type: 'doc', - id: 'development/extending/plugins', - }, - collapsed: false, - items: [ - 'development/extending/plugin-config', - 'development/extending/plugin-translation', - 'development/extending/plugin-for-ui', - ], - }, - ], - }, + 'development/extending/plugins', 'notice', 'faq', ], diff --git a/sidebarsCommunity.js b/sidebarsCommunity.js index 4ae545d0..faba7be6 100644 --- a/sidebarsCommunity.js +++ b/sidebarsCommunity.js @@ -14,7 +14,20 @@ module.exports = { 'contributing/issues', 'contributing/development', 'contributing/pull-request', - 'contributing/plugins', + { + type: 'category', + label: 'Plugins', + link: { + type: 'doc', + id: 'contributing/plugins', + }, + collapsed: true, + items: [ + 'contributing/plugins/plugin-config', + 'contributing/plugins/plugin-for-ui', + 'contributing/plugins/plugin-translation', + ], + }, 'contributing/translation', 'contributing/how-to-release', ],
