Note
This documentation is for the new OMERO 5.3 version. See the latest OMERO 5.2.x version or the previous versions page to find documentation for the OMERO version you are using if you have not upgraded yet.
The webclient UI can be configured to include content from other web apps. This allows you to extend the webclient UI with your own functionality. This is used by the webtagging app and there are also some examples in the omero-webtest repository.
Currently you can add content in the following locations:
To begin with, you need to prepare your plugin pages in your own app, with their own URLs, views and templates. Then you can display these pages within the webclient UI, using the plugin framework.
Note
When you embed your pages in the webclient, there is potential for conflicts between JavaScript and CSS in the host page and your own code. Care must be taken not to overwrite global JavaScript functions (such as jQuery or the ‘OME’ namespace) or to add CSS codes that may affect host elements.
The webclient plugins work by adding some custom JavaScript snippets into the main pages of the webclient and adding HTML elements to specified locations in the webclient. These snippets of JavaScript can be used to load content into these HTML elements. Usually you will want to do this dynamically, to display data based on the currently selected objects (although this is optional). Helpers can be used to respond to changes in the selected objects and the selected tab, so you can load or refresh your plugin only when necessary.
To display content based on currently selected data, such as Projects, Datasets and Images, your app pages will need to have these defined in their URLs. For example:
# Webtagging: Tag images within the selected dataset
url(r'^auto_tag/dataset/(?P<datasetId>[0-9]+)/$', views.auto_tag),
# Webtest: Show a panel of ROI thumbnails for an image
url(r'^image_rois/(?P<imageId>[0-9]+)/', views.image_rois, name='webtest_image_rois'),
These URLs should simply display the content that you want to show in the webclient. When these pages load in the webclient, they will have all the webclient CSS and JavaScript (such as jQuery) available so you do not need to include these in your page.
You will need to specify an ID for the <div> element that is added to the webclient, so that you can refer to this element in the JavaScript. For example, image_roi_tab or auto_tag_panel.
This will contain the JavaScript snippet that is injected into the main webclient page <head> when the page is generated. This is added using Django’s templates, so it should be placed within your app’s /templates/<organization_appname>/ directory and named .html, e.g. /templates/<organization_appname>/webclient_plugins/right_plugin_rois.html. All the JavaScript should be within <script> and </script> tags. Your plugin initialization should happen after the page has loaded, so you use the jQuery on-ready function.
You use custom jQuery functions, called omeroweb_right_plugin or omeroweb_center_plugin, to initialize the webclient plugin. These will handle all the selection change events. You simply need to specify how the panel is loaded, based on the selected object(s) and what objects are supported. The plugin will be disabled when non-supported objects are selected.
Below is a simple example of their usage. More detailed documentation available in the plugin options section below.
Center Panel Plugin
<script>
$(function() {
// Initialise the center panel plugin, on our specified element
$("#auto_tag_panel").omeroweb_center_plugin({
// To support single item selection, we can specify the types like this.
// Tab will only be enabled when a single dataset is selected
supported_obj_types: ['dataset'],
load_plugin_content: function(selected, dtype, oid){
// since we currently limit our dtype to 'dataset', oid will be dataset ID
// Use the 'index' of your app as base for your URL
var auto_tag_url = '{% url 'webtagging_index' %}auto_tag/dataset/'+oid+'/';
$(this).load(auto_tag_url);
}
});
});
</script>
Right Tab Plugin
<script>
$(function() {
// Initialise the right tab plugin, on our specified tab element
$("#image_roi_tab").omeroweb_right_plugin({
// Tab will only be enabled when a single image is selected
supported_obj_types: ['image'],
// This will get called when tab is displayed or selected objects change
load_plugin_content: function(selected, obj_dtype, obj_id) {
// since we only support single images, the obj_id will be an image ID
// Generate url based on a template-generated url
var url = '{% url 'webtest_index' %}image_rois/' + obj_id + '/';
// Simply load the tab
$(this).load(url);
},
});
});
</script>
Now you need to add your plugin to the appropriate plugin list, stating the displayed name of the plugin, the path/to/js_snippet.html and the ID of the plugin element. Plugin lists are:
Use the OMERO command line interface to add the plugin to the appropriate list.
$ bin/omero config append omero.web.ui.center_plugins
'["Auto Tag", "webtagging/auto_tag_init.js.html", "auto_tag_panel"]'
The right_plugins list includes the Acquisition tab and Preview tab by default. If you want to append the OMERO.webtest ROI plugin or your own plugin to the list, you can simply do:
$ bin/omero config append omero.web.ui.right_plugins
'["ROIs", "omero_webtest/webclient_plugins/right_plugin.rois.js.html", "image_roi_tab"]'
If you want to replace existing plugins and display only your own single plugin, you can simply do:
$ bin/omero config set omero.web.ui.right_plugins
'[["ROIs", "omero_webtest/webclient_plugins/right_plugin.rois.js.html", "image_roi_tab"]]'
Stop and restart your web server, then refresh the webclient UI. You should see your plugin appear in the webclient UI in the specified location. You should only be able to select the plugin from the drop-down menu or tab if the supported data type is selected, e.g. ‘image’. When you select your plugin, the load content method you specified above will be called and you should see your plugin loaded.
If you now edit the views.py or HTML template for your plugin and want to refresh the plugin within the webclient, all you need to do is to select a different object (e.g. dataset, image etc.). If you select an object that is not supported by your plugin, then nothing will be displayed, and for the right-tab plugin, the tab selection will change to the first tab.
supported_obj_types: If your plugin displays data from single objects, such as a single Image or Dataset, you can specify that here, using a list of types:
supported_obj_types: ['dataset', 'image'],
This will ensure that the plugin is only enabled when a single Dataset or Image is selected. To support multiple objects, see ‘tab_enabled’.
plugin_enabled: This function allows you to specify whether a plugin is enabled or not when specified objects are selected. It is only used if you have NOT defined ‘supported_obj_types’. The function is passed a single argument:
The function should return true if the plugin should be enabled. For example, if you want the center plugin to support multiple images, or a single dataset:
plugin_enabled: function(selected){
if (selected.length == 0) return false;
var dtype = selected[0]['id'].split('-')[0];
if (selected.length > 1) {
return (dtype == "image");
} else {
return ($.inArray(dtype, ["image", "dataset"]) > -1);
}
}
load_plugin_content / load_tab_content: This function will be called when the plugin/tab content needs to be refreshed, either because the plugin is displayed for the first time, or because the selected object changes. The function will be passed 3 arguments:
If an OMERO 5 plugin also needs to work for OMERO 4.4.x installations, there are three things to consider:
The url tag has changed in Django 1.8 from {% url myview %} to {% url ‘myview’ %}. In order for your OMERO 4.4.x install to understand the new syntax, it is simply a matter of adding {% load url from future %} to the top of the template file. By using the new-style syntax and the {% load url from future %} the template will be valid in both OMERO 4.4.x and OMERO 5. The {% load url from future %} line does no harm when used on Django 1.8.
The import statement required to get the URL and patterns objects in the plugin’s urls.py has changed as well. The following import can be used to import from the correct place depending on which Django version is present.
import django
if django.VERSION < (1, 6):
from django.conf.urls.defaults import *
else:
from django.conf.urls import *
In OMERO 4.4.x (with the older Django) it was possible to manipulate settings in the plugin’s settings.py like so:
from django.conf import settings
# We can directly manipulate the settings
# E.g. add plugins to CENTER_PLUGINS list
settings.CENTER_PLUGINS.append(
["Auto Tag", "webtagging/auto_tag_init.js.html", "auto_tag_panel"]
)
This is no longer possible in OMERO 5 with Django 1.8 and it is necessary to use omero config set to change this setting as documented here: Plugin Installation.
In order to preserve the old functionality on OMERO 4.4.x servers, the plugin’s settings.py can be changed to:
import django
if django.VERSION < (1, 6):
from django.conf import settings
# We can directly manipulate the settings
# E.g. add plugins to CENTER_PLUGINS list
settings.CENTER_PLUGINS.append(
["Auto Tag", "webtagging/auto_tag_init.js.html", "auto_tag_panel"]
)
This will only take effect on OMERO 4.4.x servers so remember to document that with OMERO 5 the config will need to be modified by the person doing the installation.