1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
---
title: Writing new templates
description: Making MultiQC reports your own
---
# Writing New Templates
MultiQC is built around a templating system that uses the
[Jinja](http://jinja.pocoo.org/) python package. This makes it very
easy to create new report templates that fit your needs.
## Core or plugin
If your template could be of use to others, it would be great if you
could add it to the main MultiQC package. You can do this by creating a
fork of the [MultiQC GitHub repository](https://github.com/MultiQC/MultiQC),
adding your template and then creating a pull request to merge your changes
back to the main repository.
If it's very specific template, you can create a new Python package which
acts as a plugin. For more information about this, see the
[plugins documentation](plugins.md).
## Creating a template skeleton
For a new template to be recognised by MultiQC, it must be a python submodule
directory with a `__init__.py` file. This must be referenced in the `setup.py`
installation script as an
[entry point](http://setuptools.readthedocs.io/en/latest/setuptools.html#dynamic-discovery-of-services-and-plugins).
You can see the bundled templates defined in this way:
```python
entry_points = {
'multiqc.templates.v1': [
'default = multiqc.templates.default',
'simple = multiqc.templates.simple',
'geo = multiqc.templates.geo',
]
}
```
Note that these entry points can point to any Python modules, so if you're
writing a plugin module you can specify your module name instead. Just make
sure that `multiqc.templates.v1` is the same.
Once you've added the entry point, remember to install the package again:
```bash
pip install -e .
```
Using `-e` tells `pip` to softlink the plugin files instead of
copying, so changes made whilst editing files will be reflected when you
run MultiQC.
The `__init__.py` files must define two variables - the path to the template
directory and the main jinja template file:
```python
template_dir = os.path.dirname(__file__)
base_fn = 'base.html'
```
## Child templates
The default MultiQC template contains a _lot_ of code. Importantly, it includes
1448 lines of custom JavaScript (at time of writing) which powers the plotting
and dynamic functions in the report. You probably don't want to rewrite all of
this for your template, so to make your life easier you can create a
_child template_.
To do this, add an extra variable to your template's `__init__.py`:
```python
template_parent = 'default'
```
This tells MultiQC to use the template files from the `default` template unless
a file with the same name is found in your child template. For instance, if
you just want to add your own logo in the header of the reports, you can create
your own `header.html` which will overwrite the default header.
Files within the default template have comments at the top explaining what
part of the report they generate.
## Extra init variables
There are a few extra variables that can be added to the `__init__.py` file
to change how the report is generated.
Setting `output_dir` instructs MultiQC to put the report and it's contents
into a subdirectory. Set the string to your desired name. Note that this will
be prefixed if `-p`/`--prefix` is set at run time.
Secondly, you can copy additional files with your report when it is generated.
This is usually used to copy required images or scripts with the report. These
should be a list of file or directory paths, relative to the `__init__.py` file.
Directory contents will be copied recursively.
You can also override config options in the template. For example, setting
the value of `config.plots_force_flat` can force the report to only have
static image plots.
```python
from multiqc.utils import config
output_subdir = 'multiqc_report'
copy_files = ['assets']
config.plots_force_flat = True
```
## Jinja template variables
There are a number of variables that you can use within your Jinja template.
Two namespaces are available - `report` and `config`. You can print these
using the Jinja curly brace syntax, _eg._ `{{ config.version }}`. See the
[Jinja2 documentation](http://jinja.pocoo.org/docs/dev/templates/) for more
information.
The default MultiQC template includes dependencies in the HTML so that the
report is standalone. If you would like to do the same, use the `include_file`
function. For example:
```html
<script>
{
{
include_file("js/jquery.min.js");
}
}
</script>
<img src="data:image/png;base64,{{ include_file('img/logo.png', b64=True) }}" />
```
## Appendices
### Custom plotting functions
If you don't like the default plotting functions built into MultiQC, you
can write your own! If you create a callable variable in a template called
either `bargraph` or `linegraph`, MultiQC will use that instead. For example:
```python
def custom_linegraph(plotdata, pconfig):
return '<h1>Awesome line graph here</h1>'
linegraph = custom_linegraph
def custom_bargraph(plotdata, plotseries, pconfig):
return '<h1>Awesome bar graph here</h1>'
bargraph = custom_bargraph
```
These particular examples don't do very much, but hopefully you get the idea.
Note that you have to set the variable `linegraph` or `bargraph` to your function.
|
