# The OMERO.web client application

The webclient Django app provides the main OMERO.web client UI.

Data is retrieved from OMERO using the OMERO Python language bindings and is rendered to HTML using Django templates before being sent to the browser. Additional javascript (jQuery-based) functionality in the browser is used to update the UI in response to user interactions such as browsing or modifying the data. This will often involve AJAX calls to load more data as HTML or JSON objects.

Note

The webclient should NOT be considered as a stable public API. URLs and methods within the app are purely designed to provide internal functionality for the webclient itself and may change in minor releases without warning.

## Top level pages

There are a small number of top level HTML pages that the user will start at. These are all handled by the load_template view:

- / (homepage delegates to /userdata)

- /userdata

- /usertags

- /public

- /history

- /search

These pages contain many different jQuery scripts that run when the page loads, to setup event listeners and to load additional data.

Additional top-level pages are used in popup windows for running scripts and downloading data.

## JsTree

A jsTree is used by the userdata, usertags and public pages to browse hierarchical data. Each time a node is expanded, it uses appropriate AJAX calls to load children as json data. Further POST or DELETE AJAX calls are made to modify the data hierachy by creating or deleting links between objects.

Selection changes in the jsTree and centre panel thumbnails cause events to be triggered by jQuery on the `$("body")` element of the page, allowing other scripts to listen for these events. These are used to load selected data into the centre and right panels. The HTML for these panels contains additional scripts that also run when they load to setup their own event listeners.

There is also a global `update_thumbnails_panel` function that can be called by any script that needs to refresh the centre panel. For example, when the jsTree is used to add or remove Images from a selected Dataset.

## Switching Groups and Users

The current group and user are stored in the HTTP session as `request.session['active_group']` and `request.session['user_id']`. These are used to define the data that is loaded in the main `userdata` and `usertags` pages.

The group and user are switched by the Groups and Users menu, which updates the session and reloads the page.

## Show queries

Data in OMERO can be linked from the webclient with URLs of the form `/webclient/?show=image-23|image-34`

In the load_template view, the first object is queried from OMERO and its parent containers are also loaded. The owner and group of the top container is used to set the `active_group` and `user_id` so that the main page loads the appropriate data hierarchy.

The jsTree does its own lookup from the query string, retrieving json data and using this to expand the appropriate nodes to show the specified objects.

## Javascript code

The majority of javascript code is jQuery-based code that is embedded within the HTML templates and is run when the page loads.

Additional code is in static scripts, with functions generally name-spaced under an `OME` module.

## Reusing OMERO sessions

When integrating other applications with OMERO.web you may want to automatically log in to OMERO.web using an existing OMERO session key. The session can be passed as a query parameter. For example a direct link to image will look as follows:

    https://your_host/webgateway/img_detail/IMAGE_ID/?server=SERVER_ID&bsession=OMERO_SESSION_KEY

This provides full access to OMERO.web, in the same way that logging in with a username and password would. It is therefore unsuited for giving others temporary access to data.

Note

The SERVER_ID should match the index from the list set using `omero.web.server_list` from the server session you created. If your list contains only one server, the index will be 1.

For more details about how to create an OMERO session see server-side session or use the command line interface to create one.