Creating New Data View Types¶
There are currently only rather general data view types available in CATMAID. If these don’t suit your needs, you can just add your own. A data view can then configure your new data view type and be used as a CATMAID front page.
To add a new data view type, you basically need to define two things:
A Django template that defines the internals of your view type and
an entry in the
data_view_type
table to link data views to it.
In the following both steps will be discussed. Details about how to use data views can be found in the section Using Data Views.
A new Django template¶
Data view types are written in the
Django template language.
To make a new template accessible to CATMAID, put it in the
django/templates/catmaid
directory. There reside the templates
for the already available data view types as well. Obviously, it
is good practice to choose a template name that has something to
do with what it does. E.g., the Project List data view template is
called project_list_data_view.html
.
Data view templates get passed a context in which they live. There
you have access to the variables data_view
, projects
and
config
. With data_view
the template gets access to the
current DataView
model for which it is the data view type. A
list of all projects is available in the projects
variable. If
you have a look at the existing templates you can see that this
list is usually walked (e.g. with a for
tag) to render each
project and its stacks. Also, you need not to deal with the sort
option yourself. This is already dealt with in the Django view.
Therefore, projects
is already sorted when requested. In the
config
variable one gets access to the already parsed
configuration for the data view to render. This will keep the
options defined for a data view.
A template can now do whatever it wants with these variables. The available templates start with these lines:
{% load data_view_config %}
{% include "catmaid/common_data_view_header.html" %}
The first thing is to load custom template tags and filters to make
e.g. option handling easier. The file lives in the folder
django/applications/catmaid/templatetags/
and you might want to
have a look at it.
Next, another template (common_data_view_header.html
) is included.
This just prints a simple CATMAID header text.
The available templates then start with option parsing, e.g:
{% with opt1=config|get_or_none:"opt1"|default_if_none:0 %}
{% with opt2=config|get_or_none:"opt2"|default_if_none:"center" %}
...
{% endwith %}
{% endwith %}
There is made use of Django’s template filters and a custom one
(get_or_none
) to get a configuration option or a default.
Let’s take the first line as an example: within this with
-block
a new variable variable is assigned: opt1
. It’s value is created
as follows: Use config
(see above) as the input for the get_or_none
filter, parametrized with "opt1"
. This filter checks if its
argument (opt1
) exists in the input dictionary (config
) and
returns its value if that is the case. If is not found, None
is
returned. This result is then passed to the default_if_none
filter
which in turn is parametrized with the option’s default value (0
in that case). It checks if the input is none and if, this is the
case, returns the parameter, otherwise the input.
Note: By default, Django doesn’t support the Python keywords None, True and False in templates. Therefore, you might use 0 as False and 1 as True.
Within those with
-blocks you can then write your actual presentation
logic. Have a look at the existing templates to get an idea how this could
be done.
A new table entry¶
If your template is ready, you can make it known to CATMAID and
thereby usable by data views. To do so you need to add an entry to the
table data_view_type
. This is currently not available from within
the Django admin interface, so you have to do it manually.
A data view type needs basically three things there:
Name it, give it a
title
, e.g. “Filtering data view type”.It needs a so called
code_type
. This is the template name without file extension, e.g. “filtering_data_view”.Also, provide a descriptive help text that explains what this view type does, what options it has and maybe provide an example. Put this into the
comment
field.
As an example, in the following the entry in the data_view_type
table of the Project List data view type is shown:
title
:
Project list view
code_type
:
project_list_data_view
comment
:
A simple adjustable list of all projects and their stacks.
This view is rendered server side and supports the display
of sample images. The following options are available:
"sample_images": [true|false], "sample_stack": ["first"|"last"],
"sample_slice": [slice number|"first"|"center"|"last"]. By
default projects are sorted. Use "sort":false to turn this
off. Thus, a valid sample configuration could look like:
{"sample_images":true,"sample_stack":"last","sample_slice":"center"}
Having done this, a data view should then be able to use your data_view_type (also from within Django admin).