Creating an app
===============

The Django web site has a very good :djangodoc:`tutorial <intro/tutorial01/>`
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.

Getting set up
--------------

In order to deploy OMERO.web in a development or testing environment please 
follow the instructions under :doc:`Deployment`.

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.:

-  `http://localhost:4080/webclient/ <http://localhost:4080/webclient/>`_

When you edit and save your app, Django will automatically detect this and you
only need to refresh your browser to see the changes.

If you want to make changes to the OMERO.web code itself, you should see
:doc:`/developers/Web/EditingOmeroWeb`.

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

Creating an app
---------------

We suggest you use `GitHub <https://github.com/>`_ (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 <https://github.com/MicronOxford/webtagging>`_.
If you do not want to use GitHub, simply ignore the steps related to GitHub.

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


Add your app to your PYTHONPATH
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Your app needs to be within a directory that is on your :envvar:`PYTHONPATH`.
We usually create a new container for a new app, and add it to the
:envvar:`PYTHONPATH`.

::

    $ mkdir PARENT-APP-DIR
    $ cd PARENT-APP-DIR
    $ export PYTHONPATH=$PYTHONPATH:/path/to/PARENT-APP-DIR


OR you could simply choose an existing location:

::

    $ cd /somewhere/on/your/pythonpath/


Create and check out 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 a description and choose to add a
   README.

-  Check out your new repository (into a new directory)

   ::

       $ git clone git@github.com:<your-name>/<your-app>.git


-  OR: If you have not used git to create your app directory above, then

   ::

        $ mkdir <your-app>

-  In either case, you should now have a directory called ``your-app`` within
   a directory that is on your :envvar:`PYTHONPATH`.


Add the essential files to your app
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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

   ::

       from django.conf.urls import *
       from <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 :file:`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!")

For more details on how to write views, forms, using templates, etc. check the
:djangodoc:`Django documentation <intro/tutorial03/#write-your-first-view>`.


Add your app to OMERO.web
^^^^^^^^^^^^^^^^^^^^^^^^^

:property:`omero.web.apps` adds your custom application to the ``INSTALLED_APPS``,
so that URLs are registered etc.

.. note::

    Here we use single quotes around double quotes, since we are
    passing a double-quoted string as a json object.

::

    $ bin/omero config append omero.web.apps '"<your-app>"'


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/ <http://localhost:4080/>`_\ <your-app>/
OR `http://localhost:8000/ <http://localhost:8000/>`_\ <your-app>/
and you 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 :file:`urls.py`, :file:`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).

The following example can be found in the `webtest <https://github.com/openmicroscopy/webtest/>`_ app.

-  **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


       @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(request, '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 the ``webgateway`` to handle the image rendering using a URL
auto-generated by Django - see :doc:`/developers/Web/WebGateway`.

Resources for writing your own code
-----------------------------------

The `webtest <https://github.com/openmicroscopy/webtest/>`_ app
has a number of examples. Once installed, you can go to the webtest
homepage e.g. `<http://localhost:4080/webtest>`_ and you will
see an introduction to some of them. This page tries to find random
images and datasets from your OMERO server to use in the webtest examples.


.. _jquery_and_jquery_ui:

Using jQuery and jQuery UI from OMERO.web
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

OMERO.web uses the `jQuery <https://jquery.com/>`_ and `jQuery UI <https://jqueryui.com/>`_ 
javascript libraries extensively.
If you need these libraries, you can include the OMERO.web versions of
these libraries in your own pages. The alternative is to provide a specific
version of jQuery or jQuery UI in your own app if, for example, you think
that a version change may cause problems in your code.
If you need to make use of these resources in your own pages, you can
add the following statements to the ``<head>`` of your page templates:

::

    <!-- jQuery -->
    {% include "webgateway/base/includes/script_src_jquery.html" %}

    <!-- jQuery UI - includes js and css -->
    {% include "webgateway/base/includes/jquery-ui.html" %}

The OMERO 5.1.0 release included an upgrade to jQuery 1.11.1 and
jQuery UI 1.10.4. We have added jQuery-migrate library (1.2.1) to reduce the
effects of this upgrade. You should inspect the javascript console
during development to observe any warning messages.

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 :doc:`/developers/Web/WritingTemplates` 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.
The list of ``CUSTOM_SETTINGS_MAPPINGS`` in
:sourcedir:`components/tools/OmeroWeb/omeroweb/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 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 top links
^^^^^^^^^^^^^^^^^^^

You can configure :property:`omero.web.ui.top_links` to add links to the list
of links at the top of the webclient main pages.

-  **Name your URL in urls.py** (optional). Preferably we use URL names to
   refer to URLs.
   For example, the homepage of your app might be named like this in yourapp/urls.py.

   ::

       url( r'^$', views.index, name='figure_index' ),


   You can then refer to the link defined above using this ``name``, or you can simply use a full URL for external links.


-  **Update configuration** Use the OMERO command line interface to append the link to the ``top_links`` list.

   Links use the format ``["Label", "URL_name"]`` or you can follow this example:

   ::

       $ bin/omero config append omero.web.ui.top_links '["Figure", "figure_index"]'

   From OMERO 5.1, you can add additional attributes to links using the format ``['Link Text', 'link', attrs]``.
   This can be used to add tool-tips and to open the link in a new "target" tab. For example:

   ::

       $ bin/omero config append omero.web.ui.top_links '["Homepage", "http://myhome.com", {"title": "Homepage", "target": "new"}]'


Custom image viewer
^^^^^^^^^^^^^^^^^^^

If you have created your own image viewer and would like to have it replace the existing image viewer in the
webclient, this can be configured using :property:`omero.web.viewer.view`.

You will need your :file:`views.py` method to take an Image ID with a parameter named ``iid``. For example, see
``channel_overlay_viewer`` from the `webtest <https://github.com/openmicroscopy/webtest/>`_ app:

::

    @login_required()
    def channel_overlay_viewer(request, iid, conn=None, **kwargs):

You can then configure the webclient to use this viewer by providing the full path name to this view method.
For example, if you have webtest installed you can use the ``channel_overlay_viewer``:

::

    $ bin/omero config set omero.web.viewer.view webtest.views.channel_overlay_viewer

This will now direct the image viewer url at ``webclient/img_detail/<iid>/`` to this viewer.
However, the existing viewer will still be available under webgateway at ``webgateway/img_detail/<iid>/``.

If you want to use a different viewer for different images, you can conditionally redirect to
the webgateway viewer or elsewhere.
For example:

::

    if image.getSizeC() == 1:
        return HttpResponseRedirect(reverse("webgateway.views.full_viewer", args=(iid,)))


OMERO.web plugins
-----------------

If you want to display content from your app within the webclient UI, please see :doc:`/developers/Web/WebclientPlugin`.