Site App Development
This document details instructions and guidelines for developing site apps to be used with the SODAR Core framework.
It is recommended to read Project App Development before this document.
Site App Basics
Site apps are basically normal Django apps not intended to be used with a single SODAR project, such as site-level administrator apps. They provide certain features to be used in a SODAR-enabled Django site:
Rules for accessing app data (similar to project apps but without the need for being associated with a project).
Dynamic inclusion into the site and default templates via plugins.
The ability to show site-wide messages to users.
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.
Rules File
Generate a rules.py
file similar to a project app. However, you should not
use project predicates in this one. Example:
import rules
# Allow viewing data
rules.add_perm('{APP_NAME}.view_data', rules.is_authenticated)
If you allow anonymous users on your site and want to enable anonymous access to
your site app, use the is_allowed_anonymous
predicate:
from projectroles import rules as pr_rules
rules.add_perm(
'{APP_NAME}.view_data',
rules.is_authenticated | pr_rules.is_allowed_anonymous
)
SiteAppPlugin
Create a file plugins.py
in your app’s directory. In the file, declare a
SiteAppPlugin
class implementing
projectroles.plugins.SiteAppPluginPoint
. Within the class, implement
member variables and functions as instructed in comments and docstrings.
from projectroles.plugins import SiteAppPluginPoint
from .urls import urlpatterns
class SiteAppPlugin(SiteAppPluginPoint):
"""Plugin for registering a site-wide app"""
name = 'example_site_app'
title = 'Example Site 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.
urls
Urlpatterns, usually imported from the app’s
urls.py
file.icon
Iconify collection and icon name (e.g.
mdi:home
).entry_point_url_id
View ID for the app entry point.
description
Verbose description of the app.
app_permission
Basic permission for viewing app data in project (see above).
Implementing the following is optional:
app_settings
Implement if project or user specific settings for the app are needed. See the plugin point definition for an example.
info_settings
List of names for app-specific Django settings to be displayed for administrators in the siteinfo app.
get_messages()
Implement if your site app needs to display site-wide messages for users.
get_statistics()
Return statistics for the siteinfo app. See details in the siteinfo documentation.
get_object_link()
Return object link for a Timeline event.
get_extra_data_link()
Return extra data link for a Timeline event.
Views
In your views, you can still use projectroles mixins which are not related to
projects. Especially LoggedInPermissionMixin
is useful to ensure users not
allowed to access a view are properly redirected. Example:
from django.views.generic import TemplateView
from projectroles.views import LoggedInPermissionMixin
class ExampleView(LoggedInPermissionMixin, TemplateView):
"""Site app example view"""
permission_required = 'example_site_app.view_data'
template_name = 'example_site_app/example.html'
Note
The entry point URL is not expected to have any URL kwargs in the current implementation. If you intend to use a view which makes use of URL kwargs, you may need to modify it into also accepting a request without any parameters (e.g. displaying default content for the view).
Templates
It is recommended for you to extend projectroles/base.html
and put your
actual app content within the projectroles
block. Example:
{# Projectroles dependency #}
{% extends 'projectroles/base.html' %}
{% load projectroles_common_tags %}
{% block title %}
Example Site App Page Title
{% endblock title %}
{% block projectroles %}
<div class="container sodar-subtitle-container">
<h2>
<i class="iconify" data-icon="mdi:rocket-launch-outline"></i>
Example Site App
</h2>
</div>
<div class="container-fluid sodar-page-container">
<div class="alert alert-info">
This is an example and the entry point for <code>example_site_app</code>.
</div>
</div>
{% endblock projectroles %}
Site App Messages
The site app provides a way to display certain messages to users. For this, you
need to implement get_messages()
in the SiteAppPlugin
class.
If you need to control e.g. which user should see the message or removal of a message after showing, you need to implement relevant logic in the function.
Example:
def get_messages(self, user=None):
"""
Return a list of messages to be shown to users.
:param user: User object (optional)
:return: List of dicts or and empty list if no messages
"""
return [{
'content': 'Message content in here, can contain html',
'color': 'info', # Corresponds to bg-* in Bootstrap
'dismissable': True # False for non-dismissable
'require_auth': True # Only view for authorized users
}]