From 068dbdcc7b2784aa8361ba5959a59634102c081f Mon Sep 17 00:00:00 2001 From: Ferdinand Thiessen Date: Tue, 25 May 2021 16:26:41 +0200 Subject: [PATCH] [docs] README section about plugin development --- README.md | 45 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 35 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 9aeb055..7c8f5bc 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ Modular student club administration system, licensed under the MIT license. ## Installation ### Requirements + ``` "engines": { "node": ">= 12.22.1", @@ -12,6 +13,7 @@ Modular student club administration system, licensed under the MIT license. "yarn": ">= 1.21.1" } ``` + So on debian (buster and bullseye) you will need to install node.js and yarn beside the debian packages to meet the needed versions. ```bash @@ -23,11 +25,13 @@ npm i -g yarn npm i -g @quasar/cli popd ``` + ### Install the dependencies ```bash yarn install ``` + Be aware npm might not work. ### Configure Plugins @@ -41,7 +45,7 @@ The application is using the API of [the backend](https://flaschengeist.dev/Flas This access needs to be configured in `src/config.ts'->config.baseURL - either you do have a proxy webserver that maps the '/api' to the backend (http://localhost:5000) or -- you do directly configure the backend there:```baseURL: 'http://localhost:5000'```. Be aware not committing this configuration. +- you do directly configure the backend there:`baseURL: 'http://localhost:5000'`. Be aware not committing this configuration. ### Build the application @@ -76,15 +80,36 @@ yarn run lint #### Build a Plugin -A Flaschengeist-Frontend-Plugin should be placed in `src/plugins`. -It needs a `plugin.ts` File which exports a plugin with the following interface: +Create a new node.js project and add `@flaschengeist/api` as a peer dependency (e.g. `yarn add --peer '@flaschengeist/api'`). +If your plugin depends on an other plugin (e.g. you use the `@flaschengeist/users` plugin / stores), +then you have to add that plugin as a peer dependency too. -``` -name: string; -mainRoutes?: PluginRouteConfig[]; -outRoutes?: PluginRouteConfig[]; -requiredModules: string[]; -version: string; +You need to define a main entry point for your plugin (e.g. `"main": "src/index.ts"` in your `package.json`) which exportes +a plugin descriptor as the default export (see `@flaschengeist/types` -> `FG_Plugin.Plugin`). +E.g. + +```ts +import { FG_Plugin } from '@flaschengeist/types'; +import { routes } from './routes'; + +const plugin: FG_Plugin.Plugin = { + id: 'com.example.myplugin', + name: 'myplugin', + innerRoutes: routes, + // This are required backend plugins: + requiredModules: [['auth'], ['users'], ['roles']], + version: '0.0.1', + widgets: [ + { + priority: 1, + name: 'greeting', + permissions: [], + widget: defineAsyncComponent(() => import('./components/Widget.vue')), + }, + ], +}; + +export default plugin; ``` -You have to import `FG_Plugin` from `plugins.d.ts`. +This will add a plugin providing a widget for the dashboard side and some routes.