OMERO

Downloads
Feature List
Licensing

Page Contents

Previous topic

OMERO.web framework

Next topic

Webclient Plugins

This Page

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. One major feature of Django that we do not use in OmeroWeb is the Django database mapping, since all data comes from the OMERO server and is saved back there. You will notice that the models.py files in each app are empty.

Note

Since OMERO 5.0, the web framework uses Django 1.6 instead of Django 1.3. One important change is the syntax of the url template tag, which now requires quotes, and will need to be updated for OMERO 4.4 web apps moving to OMERO 5.0.

Getting set up

You will need to have an OMERO server running that you can connect to. This will typically be on your own machine, although it does not necessarily have to be. If you want to connect to another server (not localhost) you can edit the server list as described on the OMERO.web deployment page (see Unix or Windows version) and choose that server when you log in. That page also describes how to set debug to ‘True’ which is important when developing with OMERO.web and you should also be using the Django ‘development’ server.

$ bin/omero web start
Starting django development webserver...
Validating models...

0 errors found
December 09, 2013 - 14:34:10
Django version 1.6, using settings 'omeroweb.settings'
Starting development server at http://127.0.0.1:4080/
Quit the server with CONTROL-C.

Note

Port number is 4080

You should make sure that you can access the webclient and webadmin on your local machine before starting to develop your own code. Be sure to use the correct port number, E.g:

When you edit and save your app, Django will automatically detect this and you only need to refresh your browser to see the changes. You can see this in the OMERO.web intro movie.

If you want to run OMERO.web from source code, see Editing OMERO.web.

You can place your app anywhere on your PYTHONPATH, as long as it can be imported by OMERO.web.

Note

OMERO 5 uses Django 1.6 which has a different project layout from OMERO 4.4. If you are upgrading your app from 4.4.x you may need to update some import statements. E.g. from omeroweb import webgateway will become import webgateway.

Creating an app

We suggest you use github (as we do) since it is much easier for us to help you with any problems you have if we can see your code. The steps below describe how to create a stand-alone git repository for your app, similar to webtagging. If you do not want to use github, simply ignore the github steps below.

The steps below describe setting up a new app. You should choose an appropriate name for your app and use it in place of <your-app> in the examples below:

Create and checkout a new github repository OR manually create a new directory

  • Login to your github account homepage (E.g. https://github.com/<your-name>/) and click “New repository”

  • Enter the name of <your-app>, add description and choose to add README.

  • Checkout your new repository (into a new directory)

    $ git clone git@github.com:<your-name>/<your-app>.git
  • OR: If you haven’t used git to create your app directory above, then

    $ mkdir <your-app>

Add your app location to your PYTHONPATH

If your app is not in a directory that’s already a module on your PYTHONPATH then you need to add it:

$ export PYTHONPATH=$PYTHONPATH:/path/to/your-app

Add the essential files to your app

  • Create an empty file <your-app>/__init__.py (NB: both double underscores)

  • Create urls.py

    from django.conf.urls.defaults import *
    from omeroweb.<your-app> import views
    
    urlpatterns = patterns('django.views.generic.simple',
    
         # index 'home page' of the <your-app> app
         url( r'^$', views.index, name='<your-app>_index' ),
    
     )
  • Create views.py

    from django.http import HttpResponse
    
    def index(request):
        """
        Just a place-holder while we get started
        """
        return HttpResponse("Welcome to your app home-page!")
    

Add your app to OMERO.web

This will add your app to the INSTALLED_APPS, so that URLs are registered etc.

$ bin/omero config set omero.web.apps '["<your-app>"]'

Note

For releases before 4.4, you need to ‘register’ your app with Django manually by adding it to the INSTALLED_APPS list in omeroweb/settings.py following the pattern of existing apps there. You also need to edit omeroweb/urls.py to add your app’s urls.py file to the list of “urlpatterns”. Again, you should be able to follow the existing examples there. You can also specify at this point the URL under which your app will be found.

Now you can view the home-page we created above (NB: you will need to restart the OMERO.web server for the config settings to take effect)

$ bin/omero web stop
$ bin/omero web start

Go to  http://localhost:4080/<your-app>/ OR  http://localhost:8000/<your-app>/ Should see ‘Welcome’

Commit your code and push to github

$ git status (see new files, plus .pyc files)
$ echo "*.pyc" > .gitignore         # ignore .pyc files
$ echo ".gitignore" >> .gitignore   # ALSO ignore .gitignore

$ git add ./
$ git commit -m "Initial commit of bare-bones OMERO.web app"
$ git push origin master

Connect to OMERO: example

We have got our new app working, but it is not connecting to OMERO yet. Let us create a simple “stack preview” for an Image with multiple Z-sections. We are going to display the image name and 5 planes evenly spaced across the Z-stack. You should be able to add the appropriate code to urls.py, views.py that you created above, and add a template under /omeroweb/<your-app>/templates/<your-app>/

Note

note that /<your-app>/ appears twice in that path (need an extra folder under templates). This example can be found in webtest.

  • urls.py

    url( r'^stack_preview/(?P<imageId>[0-9]+)/$', views.stack_preview,
         name="<your-app>_stack_preview" ),
    
  • views.py Here we are using the @login_required decorator to retrieve a connection to OMERO from the session key in the HTTP request (or provide a login page and redirect here). ‘conn’ is passed to the method arguments. NB: Note a couple of new imports to add at the top of your page.

    from omeroweb.webclient.decorators import login_required
    from django.shortcuts import render_to_response
    
    
    @login_required()
    def stack_preview (request, imageId, conn=None, **kwargs):
        """ Shows a subset of Z-planes for an image """
        image = conn.getObject("Image", imageId)       # Get Image from OMERO
        image_name = image.getName()
        sizeZ = image.getSizeZ()                        # get the Z size
        # 5 Z-planes
        z_indexes = [0, int(sizeZ*0.25),
                 int(sizeZ*0.5), int(sizeZ*0.75), sizeZ-1]
        return render_to_response('webtest/stack_preview.html',
             {'imageId':imageId,
             'image_name':image_name,
             'z_indexes':z_indexes})
    
  • <your-app>/templates/<your-app>/stack_preview.html

    <html>
    <head>
         <title>Stack Preview</title>
    </head>
    <body>
         <h1>{{ image_name }}</h1>
    
         {% for z in z_indexes %}
             <img src="{% url 'webgateway.views.render_image' imageId z 0 %}"
                 style="max-width: 200px; max-height:200px"/>
         {% endfor %}
    </body>
    </html>

Viewing the page at http://localhost:4080/<your-app>/stack_preview/<image-id>/ should give you the image name and 5 planes from the Z stack. You will notice that we are using webgateway to handle the image rendering using a URL auto-generated by Django - see WebGateway.

Resources for writing your own code

The webtest app has a number of examples. If you go to the webtest homepage E.g. http://localhost:8000/webtest you will see an introduction to some of them. This page tries to find random image and dataset from your OMERO server to use in the webtest examples.

Extending templates

We provide several HTML templates in webgateway/templates/webgateway/base. This is a nice way of giving users the feeling that they have not left the webclient, if you are providing additional functionality for webclient users. You may choose not to use this if you are building a ‘stand-alone’ web application. In either case, it is good practice to create your own templates with common components (links, logout etc), so you can make changes to all your pages at once. See Writing page templates in OMERO.web for more info.

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 in omeroweb/settings.py. The list of CUSTOM_SETTINGS_MAPPINGS in omeroweb/settings.py code 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 yourapp.foo, that contains a dictionary of key-value pairs, you can add to CUSTOM_SETTINGS_MAPPINGS in yourapp/settings.py:

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

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

from yourapp import settings

print settings.FOO

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

$ bin/omero config set omero.web.yourapp.foo '{"userkey": "userval"}'

OMERO.web plugins (OMERO 4.4)

If you want to display content from your app within the webclient UI, please see Webclient Plugins.