Writing page templates in OMERO.web
===================================
This page documents the various base templates that are used by the
webclient and describes how to extend these to create your own pages
with the OMERO.web look and feel.
.. figure:: /images/webtest-base-header.png
:align: center
:alt: Base header
The ``base_header.html`` template extended in OMERO.webtest with dummy
content
You can use these templates in a number of ways, but there are 2 general
scenarios that are detailed below:
- You want a page header to look like the webclient, but you do not need any
data or connection to an OMERO server.
- You want a page that looks and behaves like it is part of the webclient
application, including data from the OMERO server.
Django templates
----------------
We use Django templates for the OMERO.web pages. See docs here:
:djangodoc:`templates <ref/templates/>`.
We have designed a number of OMERO.web base templates that you can
extend. The base templates live in the 'webgateway' app under
omeroweb/webgateway/templates/webgateway/base. You can use these to make pages
that do not require an OMERO login (e.g. public home page) etc.
If you want your pages to extend the webclient application, you can use
templates from
`omeroweb/webclient/templates/webclient/base <https://github.com/ome/omero-web/tree/master/omeroweb/webclient/templates/webclient/base>`_.
These templates are described in more detail below.
Getting Started
---------------
Within your :doc:`OMERO.web app <CreateApp>`, create a new page template and
add this line at the top:
::
{% extends "webgateway/base/base_header.html" %}
Now add the page content in a 'content' block like this:
::
{% block content %}
Your page content goes here
{% endblock %}
You can now save this template and view the page. It should look something
like the screen-shot above. You could add a 'title' block to set the page
<title>
::
{% block title %}
My OMERO.web app page
{% endblock %}
Additional blocks can be used to customize the page further. See below for
more details.
Using Webclient templates
-------------------------
Webclient templates can be used in exactly the same way, for example try using
this at the top of the page you created above:
::
{% extends "webclient/base/base_container.html" %}
However, this template will need various pieces of data to be in the page
context that Django uses to render the page. You will need to use the
``@login_required()`` and ``@render_response()`` decorators on your views.py
methods in order to retrieve this info and pass it to the template. See
:doc:`WritingViews` for more details.
If you have used the 'content' block on this page (as described above) you
will see that your page content fills the whole area under the header.
However, if you want to use the same 3 column layout as the webclient, you can
replace your 'content' block with:
::
{% block left %}
Left column content
{% endblock %}
{% block center %}
Center content
{% endblock %}
{% block right %}
Right column content
{% endblock %}
This should give you something like the screen-shot below.
.. figure:: /images/webclient-base_container.png
:align: center
:alt: Webclient Base container
The ``webclient/base/base_container.html`` template extended in
OMERO.webtest with dummy content
Extending templates
-------------------
You should aim to create a small number of your own base templates,
extending the OMERO.web webgateway or webclient templates as required. If
you extend all of your own pages from a small number of your own base
templates, then you will find it easier to change things in future. For
example, any changes in our 'webgateway' templates will only require you to
edit your own base templates.
Here is a full list of the templates under
``omeroweb/webgateway/templates/webgateway/base`` with more details below:
- **base\_html.html** - This provides the base <html> template with
blocks for 'link'(for CSS) 'title' 'script' and 'body'. It is
extended by every other template. Usage:
``{% extends "webgateway/base/base_html.html" %}``
- **base\_frame.html** - This adds jQuery and jQuery-ui libraries to a
blank page. Used for popup windows etc. Usage:
``{% extends "webgateway/base/base_frame.html" %}``
- **base\_header.html** - This also extends base\_html.html adding all
the header and footer components that are used by the webclient. See
screen-shot above. More details below.
- **base\_main.html** - This adds jQuery and jQuery-ui libraries to the
base\_header.html template. Used for popup windows etc. Usage:
``{% extends "webgateway/base/base_main.html" %}``
- **container2.html, container3.html** - These templates extend the
base\_header.html template, adding a 2 or 3 column layout in the main
body of the page. container3.html is used by the webclient for the
base_container example above.
Webtest examples
^^^^^^^^^^^^^^^^
You can find examples of how to extend the base templates in the
`OMERO.webtest <https://github.com/ome/omero-webtest/>`_
repository within the ``omero_webtest/templates/webtest/webgateway``
directory. If you install the OMERO.webtest app, you can view the template
examples live at <your-server-name>/webtest/webgateway_templates/base_header/>
The link is to an example that extends base\_header.html and
contains links to all the other webtest examples. These pages indicate
the names of the various template "blocks" that have been used to add
content to different parts of the page (also see below for block names).
Content blocks
--------------
These blocks can be used to add content to specific points in the page.
.. note::
It is important to consider using ``{{ block.super }}`` if you
want to include the content from the parent template. This is critical
for the "link" and "script" blocks, which are used to add <link> and
<script> elements to the head of the page. If you forget to use
`` {{ block.super }} `` then you will remove all the CSS and JavaScript
links required by the parent template.
See `base_header.html <https://github.com/ome/omero-web/blob/master/omeroweb/webgateway/templates/webgateway/base/base_header.html>`_
for full template details.
- link: used to add CSS with <link> blocks to the page head e.g.
::
{% block link %}
{{ block.super }}
<link rel="stylesheet" type="text/css"
href="{% static "webgateway/css/ome.body.css" %}"/>
{% endblock %}
- script - used to add JavaScript with <script> blocks to the page head
- title - add text here for the page <title>.
- head - another block for any extra head elements
- middle\_header\_right - add content to the right of the main header
- middle\_header\_left - add content to the left of the main header
- content - main page content.
container2.html, container3.html
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These templates have all the same blocks as base\_header.html since they
extent it (see above). In addition, they also add the following blocks:
- left: The left column (NOT in container2.html)
- center: The middle column
- right: The right column
See
`container3.html <https://github.com/ome/omero-web/blob/master/omeroweb/webgateway/templates/webgateway/base/container3.html>`_
for full template details.