Creating an app

The Django web site has a very good tutorial to get you familiar with the Django framework. The more you know about Django, the easier you will find it working with the OmeroWeb framework.

All official OMERO applications can be installed from PyPI.

Getting set up

In order to deploy OMERO.web in a development or testing environment, you can use Docker as described below or follow the install instructions under OMERO.web installation for developers.

If you want to make changes to the OMERO.web code itself, go to Editing OMERO.web.

Clone the examples repository

To get started quickly, we are going to use the omero web apps examples repository which contains two sample OMERO.web apps. Clone the repo to a location of your choice:

$ git clone git@github.com:ome/omero-web-apps-examples.git

We will run the simplest example app from the repo. This is called minimal_webapp.

Run your app with locally-installed OMERO.web

If you have installed omero-web locally in a virtual environment as described in OMERO.web installation for developers, you can simply install the minimal-webapp example via pip:

$ cd omero-web-apps-examples/minimal-webapp
$ pip install -e .

This installs the source code directly, allowing you to work on the installed code.

You also need to add your app to the omero.web.apps setting:

Note

Here we use single quotes around double quotes.

$ omero config append omero.web.apps '"minimal_webapp"'

Now you can restart your omero-web server and go to http://localhost:4080/minimal_webapp/ in your browser. You should be redirected to the login screen and then back to the minimal_webapp page which will display your Name and list your Projects.

Run your app with OMERO.web in a Docker container

The following walk-through uses omero-web-docker to run the app. Here we add minimal_webapp to the installed apps and map the app directory to the site-packages directory in the Docker instance so that python can import our minimal_webapp module.

# You need to be in the project directory for this to work.
# cd omero-web-apps-examples/

# The OMERO server we want to connect to.
$ host=demo.openmicroscopy.org

# Path to the python module for the app.
$ appdir=$(pwd)/minimal-webapp/minimal_webapp

# Location within Docker instance we want to link the app, so it can be imported.
$ docker_appdir=/opt/omero/web/venv3/lib/python3.6/site-packages/minimal_webapp

# This example config file installs "minimal_webapp". See the file for more details.
$ config=$(pwd)/config.omero

# Location within Docker instance we want to mount the config.
$ docker_config=/opt/omero/web/config/config.omero

# Run docker container.
$ docker run -it --rm -e OMEROHOST=$host -p 4080:4080 -v $appdir:$docker_appdir -v $config:$docker_config openmicroscopy/omero-web-standalone

This will run Docker in the foreground, showing the output in your terminal and allowing you to kill the container with Ctrl-C. You should see the following lines in the output, indicating that OMERO.web is starting and the static files from your app are being included.

...
Copying '/opt/omero/web/venv3/lib/python3.6/site-packages/minimal_webapp/static/minimal_webapp/app.css'
Copying '/opt/omero/web/venv3/lib/python3.6/site-packages/minimal_webapp/static/minimal_webapp/app.js'
...
Starting OMERO.web...

Now go to http://localhost:4080/minimal_webapp/ in your browser. You should be redirected to the login screen and then back to the minimal_webapp page which will display your Name and list your Projects.

Exploring the app

The minimal_webapp code is well-documented to explain how the app is working. Briefly, the app supports a single URL defined in minimal_webapp/urls.py which maps to the index function within minimal_webapp/views.py. This uses the connection to OMERO, conn to load the current user’s name and passes this to the index.html template to render the page.

This page also includes the static app.js and app.css files. JavaScript is used to load Projects from the JSON API and display them on the page.

Create an app from the template example

If you want to create your own app, you can use the example as a template.

Go to the template repository omero-web-apps-examples. Click ‘Use this template’ as described here and choose a name for your new repo, for example my_app.

Go to the directory where you want your app to live and clone it. Then run as above with Docker or locally-installed OMERO.web, making sure that your app can be imported as before.

$ git clone https://github.com/<username>/my_app
$ cd my_app

# Then run as above...

App settings

You can add settings to your app that allow configuration via the command line in the same way as for the base OMERO.web. The list of CUSTOM_SETTINGS_MAPPINGS in settings.py is a good source for examples of the different data types and parsers you can use.

For example, if you want to create a user-defined setting appname.foo, that contains a dictionary of key-value pairs, you can add to CUSTOM_SETTINGS_MAPPINGS in appname/settings.py:

import json
CUSTOM_SETTINGS_MAPPINGS = {
    "omero.web.appname.foo": ["FOO", '{"key": "val"}', json.loads]
}

From somewhere else in your app, you can then access the settings:

from appname import settings

print(settings.FOO)

Users can then configure this on the command line as follows:

$ omero config set omero.web.appname.foo '{"userkey": "userval"}'

Linking from Webclient

If you want to add links to your app from the webclient, a number of options are described on Linking from Webclient.

Releasing your app

The Release an app page has some useful steps to take when you are preparing to release your app.