flaschengeist-frontend/README.md

# Flaschengeist (frontend)

Modular student club administration system, licensed under the MIT license.

## Installation

### Requirements

```
 "engines": {
    "node": ">= 12.22.1",
    "npm": ">= 6.14.12",
    "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
pushd ~/opt
wget https://nodejs.org/dist/v16.2.0/node-v16.2.0-linux-x64.tar.xz
tar -xJf node-v16.2.0-linux-x64.tar.xz
export PATH="$(pwd)/node-v16.2.0-linux-x64/bin":"$PATH"
npm i -g yarn
npm i -g @quasar/cli
popd
```

### Install the dependencies

```bash
yarn install
```

Be aware npm might not work.

### Configure Plugins

#### Installing a plugin

Simply add it as a dependency and install it, for example installing the `pricelist`-plugin:

```sh
yarn add '@flaschengeist/pricelist'
yarn install
```

#### Enable / Disable a plugin

After installing a plugin you will have to enable it,
this is done by adding it to the `plugin.config.js` file.
For the example above the file should look like:

```js
module.exports = [
  // pricelist plugin:
  '@flaschengeist/pricelist',
];
```

Remember to rebuild the project

### Configure Backend

The application is using the API of [the backend](https://flaschengeist.dev/Flaschengeist/flaschengeist)
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.

### Build the application

```sh
yarn quasar build
```

## Development

### Icons used

We are using the `mdi-v5` icon set, so feel free to use any icon from it.
A list can be found [here](https://materialdesignicons.com/)

### Commands useful for development

#### Start the app in development mode

Provides hot-code reloading, error reporting, etc.

```bash
yarn quasar dev
```

#### File linting

```bash
yarn run lint
```

### Plugins

#### Build a Plugin

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.

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;
```

This will add a plugin providing a widget for the dashboard side and some routes.