docs(plugins): Some more documentation on the plugin class

This commit is contained in:
Ferdinand Thiessen 2021-12-19 18:58:57 +01:00
parent b8ac6eb462
commit 4df7f1cc01
1 changed files with 28 additions and 0 deletions

View File

@ -54,10 +54,21 @@ class Plugin:
If your class uses custom models add a static property called ``models``""" If your class uses custom models add a static property called ``models``"""
blueprint = None # You have to override blueprint = None # You have to override
"""Override with a `flask.blueprint` if the plugin uses custom routes"""
permissions = [] # You have to override permissions = [] # You have to override
"""Override to add custom permissions used by the plugin
A good style is to name the permissions with a prefix related to the plugin name,
to prevent clashes with other plugins. E. g. instead of *delete* use *plugin_delete*.
"""
id = "dev.flaschengeist.plugin" # You have to override id = "dev.flaschengeist.plugin" # You have to override
"""Override with the unique ID of the plugin (Hint: FQN)"""
name = "plugin" # You have to override name = "plugin" # You have to override
"""Override with human readable name of the plugin"""
models = None # You have to override models = None # You have to override
"""Override with models module"""
migrations_path = None # Override this with the location of your db migrations directory
"""Override with path to migration files, if custome db tables are used"""
def __init__(self, config=None): def __init__(self, config=None):
"""Constructor called by create_app """Constructor called by create_app
@ -68,17 +79,21 @@ class Plugin:
def install(self): def install(self):
"""Installation routine """Installation routine
Is always called with Flask application context Is always called with Flask application context
""" """
pass pass
def get_setting(self, name: str, **kwargs): def get_setting(self, name: str, **kwargs):
"""Get plugin setting from database """Get plugin setting from database
Args: Args:
name: string identifying the setting name: string identifying the setting
default: Default value default: Default value
Returns: Returns:
Value stored in database (native python) Value stored in database (native python)
Raises:
`KeyError` if no such setting exists in the database
""" """
try: try:
setting = ( setting = (
@ -95,6 +110,7 @@ class Plugin:
def set_setting(self, name: str, value): def set_setting(self, name: str, value):
"""Save setting in database """Save setting in database
Args: Args:
name: String identifying the setting name: String identifying the setting
value: Value to be stored value: Value to be stored
@ -114,10 +130,22 @@ class Plugin:
db.session.commit() db.session.commit()
def notify(self, user, text: str, data=None): def notify(self, user, text: str, data=None):
"""Create a new notification for an user
Args:
user: `flaschengeist.models.user.User` to notify
text: Visibile notification text
data: Optional data passed to the notificaton
Returns:
ID of the created `flaschengeist.models.notification.Notification`
Hint: use the data for frontend actions.
"""
if not user.deleted: if not user.deleted:
n = Notification(text=text, data=data, plugin=self.id, user_=user) n = Notification(text=text, data=data, plugin=self.id, user_=user)
db.session.add(n) db.session.add(n)
db.session.commit() db.session.commit()
return n.id
def serialize(self): def serialize(self):
"""Serialize a plugin into a dict """Serialize a plugin into a dict