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/venv/lib/python2.7/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/venv/lib/python2.7/site-packages/minimal_webapp/static/minimal_webapp/app.css'
Copying '/opt/omero/web/venv/lib/python2.7/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.