# Example on Plugin Development

## File Structure
```
- root
  - flaschengeist_example
    - __init__.py
    - plugin.py
    [- migrations]
  - setup.cfg
```

In a minimal example, you would only need two python source files and
your setup configuration.
If you also use custom database tables, you would also need a directory
containing your _alembic_-migration files.

## Source code
Code is seperated in two locations, the meta data of your plugin goes into the `__init__.py` and all logic goes into the `plugin.py`, of cause you could add more files, but make sure to not depend on some external packages in the `__init__.py`.

### Project data / setuptools
For **Flaschengeist** to find your plugin, you have to
install it corretly, especially the entry points have to be set.
```ini
[metadata]
license = MIT
version = 1.0.0
name = flaschengeist-example
description = Example plugin for Flaschengeist
# ...

[options]
packages =
    flaschengeist_example
install_requires =
    flaschengeist == 2.0.*

[options.entry_points]
    # Path to your meta data instance
    flaschengeist.plugins =
        example = flaschengeist_example:plugin

```


### Metadata
The `__init__.py` contains the plugin meta data.

```python
# __init__.py
from flaschengeist.plugins import PluginMetadata
plugin = PluginMetadata(
    id="com.example.plugin", # unique, recommend FQN
    name="Example Plugin", # Human readable name
    version="1.0.0", # Optional
    module="flaschengeist_example.plugin.ExamplePlugin" # module and class of your plugin
)
```

`version` is optional, if not provided the version of your distribution (set in setup.cfg) is used.

### Implementation
You plugin implementation goes into the `plugin.py`.
Here you define your Plugin class, make sure it inheritates from `flaschengeist.plugins.Plugin` or `flaschengeist.plugins.AuthPlugin` respectivly.

It will get initalized with the meta data you defined in the `__init__.py` and the configuration object.

```python
from flaschengeist.plugins import Plugin
from flask import Blueprint

bp = Blueprint(...)

class ExamplePlugin(Plugin):
    blueprint = bp
    ...

@bp.route("/example")
def get_example():
    ...

```