Skip to content

Latest commit

 

History

History
151 lines (106 loc) · 4.6 KB

dev_backend_app.rst

File metadata and controls

151 lines (106 loc) · 4.6 KB
Raw

Backend App Development

This document details instructions and guidelines for developing backend apps to be used with the SODAR Core framework.

It is recommended to read dev_project_app before this document.

Backend App Basics

Backend apps are intended to be used by other apps via their plugin without requiring hard-coded imports. They may provide their own views for e.g. Ajax API functionality, but mostly they're intended to be internal "helper" apps as the name suggests.

Prerequisites

See dev_project_app.

Models

No specific model implementation is required. However, it is strongly to refer to objects using sodar_uuid fields instead of the database private key.

BackendAppPlugin

The plugin is detected and retrieved using a BackendAppPlugin.

Declaring the Plugin

Create a file plugins.py in your app's directory. In the file, declare a BackendAppPlugin class implementing projectroles.plugins.BackendPluginPoint. Within the class, implement member variables and functions as instructed in comments and docstrings.

from projectroles.plugins import BackendPluginPoint
from .urls import urlpatterns

class BackendAppPlugin(BackendPluginPoint):
    """Plugin for registering a backend app"""
    name = 'example_backend_app'
    title = 'Example Backend App'
    urls = urlpatterns
    # ...

The following variables and functions are mandatory:

name

App name. In most cases this should match the app package name.

title

Printable app title.

icon

Iconify collection and icon name (e.g. mdi:home).

description

Verbose description of the app.

get_api()

Method for retrieving the API class for the backend. The user should implement this API class to be retrieved.

Implementing the following is optional:

javascript_url

Path to on demand includeable Javascript file.

css_url

Path to on demand includeable CSS file.

info_settings

List of names for app-specific Django settings to be displayed for administrators in the siteinfo app.

get_statistics()

Return statistics for the siteinfo app. See details in the siteinfo documentation <app_siteinfo>.

get_object_link()

Return object link for a Timeline event.

get_extra_data_link()

Return extra data link for a Timeline event.

Hint

If you want to implement a backend API which is closely tied to a project app, there's no requirement to declare your backend as a separate Django app. You can just include the BackendAppPlugin in your app's plugins.py along with your ProjectAppPlugin. See the timeline app <app_timeline> for an example of this.

Using the Plugin

To retrieve the API for the plugin, use the function projectroles.plugins.get_backend_api() as follows:

from projectroles.plugins import get_backend_api
example_api = get_backend_api('example_backend_app')

if example_api:     # Make sure the API is there, and only after that..
    pass            # ..do stuff with the API

Including Backend Javascript/CSS

If you want Javascript or CSS files to be associated with your plugin you can set the javascript_url or css_url variables to specify the path to your file. Note that these should correspond to STATIC paths under your app directory.

class BackendPlugin(BackendPluginPoint):

    name = 'example_backend_app'
    title = 'Example Backend App'
    javascript_url = 'example_backend_app/js/example.js'
    css_url = 'example_backend_app/css/example.css'

The get_backend_include template-tag will return a <script> or <link> html tag with your specific file path, to be used in a template of your app making use of the backend plugin:

{% load projectroles_common_tags %}
{% get_backend_include 'example_backend_app' 'js' as javascript_include_tag %}
{{ javascript_include_tag|safe }}

{% get_backend_include 'example_backend_app' 'css' as css_include_tag %}
{{ css_include_tag|safe }}

This will result in the following HTML:

<script type="text/javascript" src="/static/example.js"></script>
<link rel="stylesheet" type="text/css" href="/static/example.css"/>

Be sure to use the backend plugin's name (not the title) as the key and filter the result by safe, so the tag won't be auto-escaped.