From f32c215d2bc3b2ee89269658f58373380c0d6ba1 Mon Sep 17 00:00:00 2001 From: Derick Ruiz Date: Thu, 28 Nov 2024 12:32:19 +0700 Subject: [PATCH 1/5] (docs): Moving the Plugin Guides section to the Learn section and naming it Guides because they're showing in general how to do things in Amplication and it should not be specific to the plugins section. It makes more sense here. --- docs/concepts/event-driven-architecture.md | 2 +- docs/how-to/authentication-plugin-examples.mdx | 2 +- .../how-to/choose-configure-update-database.md | 2 +- docs/how-to/create-message-broker.md | 2 +- docs/how-to/index.md | 2 +- docusaurus.config.js | 4 ++++ sidebars.js | 18 +++++++++--------- 7 files changed, 18 insertions(+), 14 deletions(-) diff --git a/docs/concepts/event-driven-architecture.md b/docs/concepts/event-driven-architecture.md index f150e603..eb0e53d0 100644 --- a/docs/concepts/event-driven-architecture.md +++ b/docs/concepts/event-driven-architecture.md @@ -45,7 +45,7 @@ For a step-by-step guide on building an event-driven application with Amplicatio ## Step 1: Create a Message Broker -In your Amplication project, navigate to "Add Resource" and select "[Message Broker](/how-to/create-message-broker)". This will lead you to the Message Broker Creation Wizard. +In your Amplication project, navigate to "Add Resource" and select "[Message Broker](/guides/message-broker)". This will lead you to the Message Broker Creation Wizard. After creating the message broker, you'll be able to configure the settings by installing and configuring the appropriate [message broker plugin](#supported-message-brokers). diff --git a/docs/how-to/authentication-plugin-examples.mdx b/docs/how-to/authentication-plugin-examples.mdx index fb427fc9..17c49d4f 100644 --- a/docs/how-to/authentication-plugin-examples.mdx +++ b/docs/how-to/authentication-plugin-examples.mdx @@ -1,7 +1,7 @@ --- title: Authentication Plugin Guide sidebar_label: Authentication Plugin Guide -slug: /plugins/guides/authentication +slug: /guides/authentication pagination_next: getting-started/authentication --- diff --git a/docs/how-to/choose-configure-update-database.md b/docs/how-to/choose-configure-update-database.md index f9876c69..dea549e1 100644 --- a/docs/how-to/choose-configure-update-database.md +++ b/docs/how-to/choose-configure-update-database.md @@ -3,7 +3,7 @@ id: choose-configure-update-database title: How To Choose, Configure, and Update Your Database description: Learn how to choose, configure, and update your Amplication database using plugins. sidebar_label: Database Plugin Guide -slug: /plugins/guides/database +slug: /guides/database --- # How To Choose, Configure, and Update Your Database diff --git a/docs/how-to/create-message-broker.md b/docs/how-to/create-message-broker.md index dd4f9ef9..5a13e6ba 100644 --- a/docs/how-to/create-message-broker.md +++ b/docs/how-to/create-message-broker.md @@ -2,7 +2,7 @@ id: create-message-broker title: How to create a message broker sidebar_label: Create a Message Broker -slug: /how-to/create-message-broker +slug: /guides/message-broker --- # Create a message broker diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 7cb3b07d..c4ed1b94 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -18,6 +18,6 @@ Whether you are a beginner just starting with Amplication or an experienced deve - [Entity Relations](/relations/) - [Base Directories](/how-to/base-directories) - [Configure selective code generation](/how-to/api-admin-ui-settings/) -- [Create a message broker](/how-to/create-message-broker) +- [Create a message broker](/guides/message-broker) Browse through the available tutorials and start building your web app with Amplication. diff --git a/docusaurus.config.js b/docusaurus.config.js index 163a466b..9d15cf99 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -194,6 +194,10 @@ module.exports = { "@docusaurus/plugin-client-redirects", { redirects: [ + { + to: "/guides/message-broker", + from: ["/how-to/create-message-broker"] + }, { to: "/plugins/guides/authentication", from: ["/authentication-plugin-examples"] diff --git a/sidebars.js b/sidebars.js index e092d67f..d219b712 100644 --- a/sidebars.js +++ b/sidebars.js @@ -183,15 +183,6 @@ const sidebars = { "getting-started/plugins", "getting-started/community-plugins", "plugins/dotnet-plugins", - { - type: "category", - label: "Plugin Guides", - items: [ - "how-to/choose-configure-update-database", - "how-to/authentication-plugin-examples", - "how-to/create-message-broker", - ] - }, { type: "category", label: "Custom Plugins", @@ -280,6 +271,15 @@ const sidebars = { items: [ "tutorials/index", "tutorials/community-tutorials", + { + type: "category", + label: "Guides", + items: [ + "how-to/choose-configure-update-database", + "how-to/authentication-plugin-examples", + "how-to/create-message-broker", + ] + }, { type: "link", label: "Developer Tutorials", From 4e78a96da29d1dc6d939e460ef26a2fed86ade76 Mon Sep 17 00:00:00 2001 From: Derick Ruiz Date: Thu, 28 Nov 2024 12:45:55 +0700 Subject: [PATCH 2/5] (docs): Making various adjustments to the sidebars, titles, sidebar titles, etc. to make the hierarchy more understandable. --- docs/plugins/define-plugin-settings.md | 2 +- docs/plugins/developing-a-plugin.md | 9 ++++----- docs/plugins/event-hierarchy.md | 6 +++--- docs/plugins/plugin-architecture.md | 4 ++-- docs/plugins/private-plugins.md | 3 ++- docs/plugins/publish-your-plugin.md | 8 ++++++-- docs/plugins/testing-a-plugin.md | 4 ++-- sidebars.js | 9 ++++----- 8 files changed, 24 insertions(+), 21 deletions(-) diff --git a/docs/plugins/define-plugin-settings.md b/docs/plugins/define-plugin-settings.md index 7367f93e..dcf63626 100644 --- a/docs/plugins/define-plugin-settings.md +++ b/docs/plugins/define-plugin-settings.md @@ -1,7 +1,7 @@ --- id: define-plugin-settings title: How To Define Plugin Settings -sidebar_label: How To Define Plugin Settings +sidebar_label: Define Plugin Settings slug: /plugins/define-plugin-settings --- diff --git a/docs/plugins/developing-a-plugin.md b/docs/plugins/developing-a-plugin.md index 53c12793..9cf08ef1 100644 --- a/docs/plugins/developing-a-plugin.md +++ b/docs/plugins/developing-a-plugin.md @@ -1,14 +1,13 @@ --- id: how-to-create-plugin -title: How to Create a Custom Plugin -sidebar_label: How to Create a Custom Plugin +title: How to Develop a Plugin +sidebar_label: Develop a Plugin slug: /plugins/how-to-create-plugin --- -Amplication includes several plugins - some allow you to choose an authentication strategy, some allow you to choose which database you want to integrate with and one allows you to connect your service to a message broker. +### Pre-requisites -### Planning and POC: -Before any development of a plugin, we take the following steps: +Before the development of a plugin, take the following steps: 1. Generate a service with Amplication 2. Apply the changes that we need: diff --git a/docs/plugins/event-hierarchy.md b/docs/plugins/event-hierarchy.md index df92cea8..aad83f9c 100644 --- a/docs/plugins/event-hierarchy.md +++ b/docs/plugins/event-hierarchy.md @@ -1,11 +1,11 @@ --- id: event-hierarchy -title: Event Hierarchy -sidebar_label: Event Hierarchy +title: Plugin Event Hierarchy +sidebar_label: Plugin Event Hierarchy slug: /plugins/event-hierarchy --- -# Event Hierarchy +# Plugin Event Hierarchy We have two main event hierarchies in our Data Service Generator (DSG) service: one for Node.js services and one for .NET services. Each of these hierarchies includes events to create the server's files and, in the case of Node.js, the admin-ui files. diff --git a/docs/plugins/plugin-architecture.md b/docs/plugins/plugin-architecture.md index 56de5452..450c4d95 100644 --- a/docs/plugins/plugin-architecture.md +++ b/docs/plugins/plugin-architecture.md @@ -1,7 +1,7 @@ --- id: plugin-architecture -title: Plugin Architecture Overview -sidebar_label: Custom Plugin Architecture +title: Plugin Architecture +sidebar_label: Plugin Architecture slug: /plugins/plugin-architecture --- diff --git a/docs/plugins/private-plugins.md b/docs/plugins/private-plugins.md index 478d973e..28347bd2 100644 --- a/docs/plugins/private-plugins.md +++ b/docs/plugins/private-plugins.md @@ -1,10 +1,11 @@ --- id: private-plugins +sidebar_label: Private Plugins slug: /private-plugins toc_max_heading_level: 2 --- -# Creating and Using Private Plugins +# Private Plugins Private Plugins enable you to create plugins exclusively for your organization's use. These plugins let you build secure, proprietary integrations and define your organization's standards. You can use them to protect sensitive business logic and enforce development best practices across your services. diff --git a/docs/plugins/publish-your-plugin.md b/docs/plugins/publish-your-plugin.md index 379fb2dc..a65997f3 100644 --- a/docs/plugins/publish-your-plugin.md +++ b/docs/plugins/publish-your-plugin.md @@ -1,11 +1,15 @@ --- id: publish-plugin -title: How To Publish a Custom Plugin -sidebar_label: How To Publish a Custom Plugin +title: How To Publish a Plugin +sidebar_label: Publish a Plugin description: Learn how to publish your Amplication plugin. slug: /plugins/publish-plugin --- +:::info +These steps are for publishing a publicly available [community plugin](/getting-started/plugins/). For information on releasing private plugins, see the [Private Plugins](/private-plugins/) page. +::: + Step 1. Create the Plugin Step 2. Publish the Plugin in NPM. For details, see [NPM documentation](https://docs.npmjs.com/cli/v6/commands/npm-publish) diff --git a/docs/plugins/testing-a-plugin.md b/docs/plugins/testing-a-plugin.md index cf86a28a..97ff4556 100644 --- a/docs/plugins/testing-a-plugin.md +++ b/docs/plugins/testing-a-plugin.md @@ -1,7 +1,7 @@ --- id: how-to-test-plugin -title: How to Test a Custom Plugin -sidebar_label: How to Test a Custom Plugin +title: How to Test a Plugin +sidebar_label: Test a Plugin slug: /plugins/how-to-test-plugin --- diff --git a/sidebars.js b/sidebars.js index d219b712..c4d1b0d9 100644 --- a/sidebars.js +++ b/sidebars.js @@ -185,7 +185,7 @@ const sidebars = { "plugins/dotnet-plugins", { type: "category", - label: "Custom Plugins", + label: "Plugin Development", link: { type:"doc", id: "plugins/overview" @@ -193,14 +193,13 @@ const sidebars = { items: [ "plugins/overview", "plugins/plugin-architecture", + "plugins/event-hierarchy", + "plugins/plugin-events-before-after", + "plugins/context-skip-default", "plugins/how-to-create-plugin", "plugins/define-plugin-settings", "plugins/how-to-test-plugin", "plugins/publish-plugin", - "plugins/private-plugins", - "plugins/plugin-events-before-after", - "plugins/context-skip-default", - "plugins/event-hierarchy", { type: "category", label: ".NET Plugin Events - Reference", From 4ce47a0deac8f5592335e092888b91a582ab0a6c Mon Sep 17 00:00:00 2001 From: Derick Ruiz Date: Thu, 28 Nov 2024 13:28:49 +0700 Subject: [PATCH 3/5] (docs): Adding some content adjustments to the file so that things are more clear for the plugin section. --- docs/getting-started/plugins.md | 3 ++- docs/plugins/plugin-architecture.md | 11 ++++++++++- docs/plugins/plugindev-overview.md | 3 ++- 3 files changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/plugins.md b/docs/getting-started/plugins.md index 0c98e433..801911a0 100644 --- a/docs/getting-started/plugins.md +++ b/docs/getting-started/plugins.md @@ -10,7 +10,8 @@ pagination_prev: getting-started/community-plugins Amplication uses _Plugins_ to extend the functionality of your generated service. These software additions allow developers to customize the default behavior of [Amplication's code generation process](/plugins/plugin-architecture/), providing hooks into various stages of service creation. -Amplication offers a wide range of community-created plugins that are open-source and available on GitHub. You also have the flexibility to develop your own [custom plugins](/plugins/overview/) so you can tailor your generated service to meet your exact requirements. +Amplication offers a wide range of community plugins that are open-source and available on GitHub. +You can also [develop your own private plugins](/private-plugins/) and [community plugins](/plugins/overview/) to extend Amplication's functionality and have it meet your exact requirements. You can enable certain plugins when you first create your service. For example, if you choose MySQL as your database, the _MySQL DB_ plugin will be enabled. diff --git a/docs/plugins/plugin-architecture.md b/docs/plugins/plugin-architecture.md index 450c4d95..4d49f793 100644 --- a/docs/plugins/plugin-architecture.md +++ b/docs/plugins/plugin-architecture.md @@ -15,7 +15,16 @@ The `pluginWrapper` function is invoked with the following arguments: - **event** - the name of event we want to capture, and change something in the triggered process. - **args** - the original parameters of the DSG function. These are likely to be used as the parameters of the event, for the plugin developer to have access to these params and manipulate the returned value of the function. -For the purpose of this architecture overview, remember that every event has before and after property (which is a function), representing the event's lifecycle in which you can intervene (before the emission of the event and after the emission of the event). For more information about `before` and `after` event see [Before and After Lifecycle Functions](docs\plugins\before-after.md) +## Event Lifecycle + +Each plugin event supports two execution points: + +- `before`: Executes before the main event processing +- `after`: Executes after the main event processing + +These lifecycle hooks allow precise control over the code generation process. + +For more information about `before` and `after` event see [Before and After Lifecycle Functions](docs\plugins\before-after.md) When the `pluginWrapper` function is invoked, it checks whether the event argument that was passed has a `before` or `after` property. If so, it invokes other functions that are responsible for calculating the final behavior when this event is emitted, or in other words, the outcome of the function that this event is responsible to execute. diff --git a/docs/plugins/plugindev-overview.md b/docs/plugins/plugindev-overview.md index 007d8c9e..57004d81 100644 --- a/docs/plugins/plugindev-overview.md +++ b/docs/plugins/plugindev-overview.md @@ -9,7 +9,8 @@ pagination_prev: plugins/event-hierarchy # Plugin Development Overview -A plugin is a custom code that extends Amplication developer platform with new features. The features incorporated can be generic, useful to a wide variety of users, or can be very specific to deal with specialized requirements. +A plugin is code that extends the Amplication developer platform by adding new features or modifying existing functionality. +The features incorporated can be generic, useful to a wide variety of users, or can be very specific to deal with specialized requirements. If you or your organization have a specific workflow, install an existing plugin or write one to customize the platform to perform your required tasks. From 06a35df442c5ba08a0bb7446e16488bdb51ed57f Mon Sep 17 00:00:00 2001 From: Derick Ruiz Date: Wed, 4 Dec 2024 16:08:14 +0700 Subject: [PATCH 4/5] (docs): Fixing the redirect issue to a non-existent page. --- docusaurus.config.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 9d15cf99..a9513f92 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -199,7 +199,7 @@ module.exports = { from: ["/how-to/create-message-broker"] }, { - to: "/plugins/guides/authentication", + to: "/guides/authentication", from: ["/authentication-plugin-examples"] }, { From 43113c30b70c47e6c6e843821baf4153571c15b7 Mon Sep 17 00:00:00 2001 From: Derick Ruiz Date: Wed, 4 Dec 2024 16:23:31 +0700 Subject: [PATCH 5/5] (docs): Adding a redirect for the database plugin guide. --- docusaurus.config.js | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docusaurus.config.js b/docusaurus.config.js index de17c320..dcb96982 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -198,6 +198,10 @@ module.exports = { "@docusaurus/plugin-client-redirects", { redirects: [ + { + to: "/guides/database", + from: ["/plugins/guides/database/"] + }, { to: "/guides/message-broker", from: ["/how-to/create-message-broker"]