Plugins, Events and Hooks¶
Warning
This section is a work in progress and does not contain full documentation of what Plugins can do in Janeway.
Janeway is, first and foremost, a Django application. This means that you can create a normal django application and include it in Janeway via the normal Django routes. In addition we provide a small plugins framework to make adding new elements to the core easier.
Plugins¶
Janeway plugins look very similar to Django applications. The Janeway team maintain a suite of plugins that you can use. Janeway plugins are usually laid out in this manner:
- example_plugin
- install
- settings.json
- templates
- example_plugin
- index.html
- …
- plugin_settings.py
- urls.py
- models.py
- forms.py
- views.py
- admin.py
- hooks.py
Note
Not all of these elements are required for every plugin but this is a generic example of a plugin that has its own models, views and templates.
Tip
We have a plugin generator that you can use to create empty plugins: https://github.com/BirkbeckCTP/generic_plugin_generator
plugin_settings¶
The plugin settings file tells Janeway about your plugin and is used to connect it with core areas of Janeway.
from events import logic as events_logic
from utils import plugins
from utils.install import update_settings
PLUGIN_NAME = 'Example Plugin'
DISPLAY_NAME = 'Example'
DESCRIPTION = 'Just Another Example'
AUTHOR = 'Birkbeck Centre for Technology and Publishing'
VERSION = '0.1'
SHORT_NAME = 'example'
MANAGER_URL = 'example_manager' # this must be a named URL route in your plugin urls.py
JANEWAY_VERSION = "1.3.9" # the minimum version of Janeway that this plugin works with
# The following settings are only used if your plugin is used as part of the article workflow.
IS_WORKFLOW_PLUGIN = True
JUMP_URL = 'example_article' # a named URL route that will include the article_id kwarg
HANDSHAKE_URL = 'example_articles' # the initial page, usually lists all articles in the plugin's stage
ARTICLE_PK_IN_HANDSHAKE_URL = True
STAGE = 'example_plugin' # name of the stage stored against an article when in this stage, can be used to filter articles by the plugin's stage
KANBAN_CARD = 'example/elements/card.html' # path to a template that can be included in the Kanban page, is looped over per article in the plugin's stage
DASHBOARD_TEMPLATE = 'example/elements/dashboard.html' # path to a template that is included on Janeway's dashboard page
class ExamplePlugin(plugins.Plugin):
plugin_name = PLUGIN_NAME
display_name = DISPLAY_NAME
description = DESCRIPTION
author = AUTHOR
short_name = SHORT_NAME
stage = STAGE
manager_url = MANAGER_URL
version = VERSION
janeway_version = JANEWAY_VERSION
is_workflow_plugin = IS_WORKFLOW_PLUGIN
handshake_url = HANDSHAKE_URL
article_pk_in_handshake_url = ARTICLE_PK_IN_HANDSHAKE_URL
def install():
ExamplePlugin.install()
update_settings(
file_path='plugins/example/install/settings.json'
)
# Plugins can register for hooks, when a hook is rendered in a template the registered function will be called.
def hook_registry():
return {
'article_footer_block':
{
'module': 'plugins.example.hooks',
'function': 'example_hook',
},
}
# Plugins can register for events (see events/logic.py for a list) when an event is fired the registered function is called.
def register_for_events():
# Plugin modules can't be imported until plugin is loaded
from plugins.example import events
events_logic.Events.register_for_event(
ON_ARTICLE_SUBMITTED,
events.example_event_func,
)
Other than the unique nature of plugin_settings, hooks and events plugins operate like normal Django applications.
Note
To avoid clashes with core elements all plugin URLs are imported and available at plugins/SHORT_NAME/path/
Events¶
The events framework is designed in a similar way to Django signals but for workflow events. A plugin or Django application can register a function to be called when an event is fired.
from events import logic as events_logic
events_logic.Events.register_for_event(
ON_ARTICLE_SUBMITTED, # The event to be registered for
events.example_event_func, # The function to be called
)
Plugins can register for events by adding code similar to the above in the register_for_events function in plugin_settings.
Each event has a set of keyword arguments (kwargs) that will be passed to it. You can see these in events.logic.Events
.
def example_event_func(**kwargs):
request = kwargs.get('request')
article = kwargs.get('article')
# do something here
Hooks¶
Janeway also has hooks in its templates. This allows a plugin to insert HTML or do something when a hook is fired on a template. There are only a few of these hooks throughout the system, the main example is to allow plugins to add nav items:
def hook_registry():
return {
'press_admin_nav_block': {'module': 'plugins.example.hooks', 'function': 'admin_hook'},
}
In this example when the press_admin_nav_block hook is fired, plugins.example.hooks.admin_hook
will be called. The function should return HTML, it can do this by returning a string or by rendering and returning a template.
def admin_hook(context):
return '<li><a href="{url}"><i class="fa fa-money"></i> Example Plugin Admin</a></li>'.format(
url=reverse('example_admin_index'),
)s
You can find hooks in the source by searching for {% hook
. Here is a non-exhaustive lise of hooks in Janeway:
- templates/admin/core/article.html
- edit_article
- core_article_tasks
- core_article_footer
- templates/admin/core/nav.html
- journal_admin_nav_block
- templates/admin/journal/manage/archive_article.html
- request_edit
- templates/admin/press/nav.html
- press_admin_nav_block
- templates/admin/production/assigned_article.html
- conversion_buttons
- templates/admin/submission/start.html
- publication_fees
- templates/admin/submission/submit_review.html
- submission_review
- themes/theme_name/templates/core/base.html
- base_head_css
- themes/theme_name/templates/core/nav.html
- nav_block
- themes/theme_name/templates/journal/article.html
- article_footer_block