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 Project App Development before this document.
Backend App Basics¶
Backend apps are intended as apps used by other apps via their plugin, without requiring hard-coded imports. These may provide their own views for e.g. Ajax API functionality, but mostly they’re intended to be internal (hence the name).
Prerequisites¶
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 (ideally should correspond to the app package name)title
: Printable app titleicon
: Font Awesome 4.7 icon name (without thefa-*
prefix)description
: Verbose description of appget_api()
: Function for retrieving the API class for the backend, to be implemented
Implementing the following is optional:
javascript_url
: Path to on demand includeable Javascript filecss_url
: Path to on demand includeable CSS fileget_statistics()
: Return statistics for the siteinfo app. See details in the siteinfo documentation.
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 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.