This article addresses the specifics of a Reporter template.
For a general introduction to Liquid, refer to this article.
_Templates are edited in the template editor with live preview. To draw charts, see Charts in reports
- Single vs Multiple issue report templates
- Variables of a template
- Objects and attributes
- Examples
- Custom fields
- CSS styling
- Import a template
Single vs Multiple issue report templates
While preparing a template, the only object you can directly access is either- issue (single issue template) or
- issues (the array of issues included in the report when preparing a multi-issue template).
When preparing a multi-issue template, you can iterate through every issue in the list with:
{% for issue in issues %}
...
(Access contents of each issue)
...
{% endfor %}
Variables of a template
| Template type | Objects you can use |
|---|---|
| Single issue | issue |
| List of issues | issues |
| Time entries | time_entries and issues |
| All types | user (the current user), now (current time), today (current date) and template (the template itself, see custom fields of a template) |
Objects and attributes
The syntax to read an attribute of an object is {{ object.attribute }}. Attributes that hold another object let you go further, for example {{ issue.project.users.size }}. An attribute that has no value prints nothing.
The types are String, Number, Boolean, Date, Time, Array and Hash, or the name of another object below.
issue
An issue. In a single issue template it is available as issue; in a list template take it from issues (see above).
| Attribute | Type | Description |
|---|---|---|
id |
Number | Issue number |
subject |
String | Subject |
description |
String | Description, the raw text |
link |
String | HTML link to the issue with the subject as text |
url |
String | Path to the issue, without the host, for example /issues/42 |
tracker |
String | Name of the tracker |
status |
String | Name of the status |
priority |
String | Name of the priority |
category |
String | Name of the category |
version |
String | Name of the target version |
author |
user | Who created the issue |
assignee |
user | The assignee |
project |
project | The project of the issue |
project_name |
String | Name of the project |
parent |
issue | The parent issue, empty for a top-level issue |
subtasks |
issues | Subtasks |
start_date |
Date | Start date |
due_date |
Date | Due date |
created_on |
Time | Creation time in the time zone of the current user |
updated_on |
Time | Last update time in the time zone of the current user |
closed_on |
Time | Closing time |
done_ratio |
Number | Percent done |
estimated_hours |
Number | Estimated time in hours |
total_estimated_hours |
Number | Estimated time with subtasks |
spent_hours |
Number | Spent time in hours |
total_spent_hours |
Number | Spent time with subtasks |
closed? |
Boolean | The issue is closed |
overdue? |
Boolean | The due date has passed |
is_private? |
Boolean | The issue is private |
visible? |
Boolean | The issue is visible to the current user |
time_entries |
time_entries | Time entries of the issue |
journals |
journals | Only the history entries that have a note |
notes |
Array of String | Texts of the notes, oldest first |
attachments |
Array of attachment | Attached files |
images |
images | Image attachments of the issue, for printing pictures |
watchers |
users | Watchers |
relations_from |
relations | Relations that start in this issue; only the visible issues |
relations_to |
relations | Relations that end in this issue; only the visible issues |
time_in_status |
Array of Hash | How long the issue stayed in each status: from_date, to_date, status, duration in minutes and author |
total_time_in_status |
Hash | Minutes per status name |
total_spent_time_by_date |
Hash | Spent hours per date, with subtasks |
available_statuses |
Hash | Status names by id |
tags |
Array of String | Tags (needs the Tags plugin) |
story_points |
Number | Story points (needs the Agile plugin) |
color |
String | Card color (needs the Agile plugin) |
day_in_state |
Number | Days in the current status (needs the Agile plugin) |
checklists |
Array of Hash | Checklist items, see below (needs the Checklists plugin) |
helpdesk_ticket |
Object | The helpdesk ticket of the issue (needs the Helpdesk plugin) |
issues
A list of issues: the whole list of a list template, the subtasks of an issue or the issues of a project.
| Attribute | Type | Description |
|---|---|---|
all |
Array of issue | All issues of the list |
visible |
Array of issue | Only the issues the current user may view |
size |
Number | Number of issues |
spent_time_by_date |
Hash | Spent hours per date for all issues of the list, for charts |
issues[42] |
issue | The issue with the id 42 |
time_entries
A list of time entries.
| Attribute | Type | Description |
|---|---|---|
all |
Array of time_entry | All time entries |
visible |
Array of time_entry | Only the entries the current user may view |
size |
Number | Number of entries |
time_entry
A time entry.
| Attribute | Type | Description |
|---|---|---|
id |
Number | Id |
hours |
Number | Hours |
comments |
String | Comment |
spent_on |
Date | The date the time was spent on |
tyear |
Number | Year of the date |
tmonth |
Number | Month of the date |
tweek |
Number | Week of the date |
activity |
String | Name of the activity |
user |
user | Who spent the time |
issue |
issue | The issue |
created_on |
Time | Creation time |
updated_on |
Time | Last update time |
visible? |
Boolean | The entry is visible to the current user |
journals
A list of the history entries of an issue.
| Attribute | Type | Description |
|---|---|---|
all |
Array of journal | All entries |
visible |
Array of journal | Only the entries the current user may view |
size |
Number | Number of entries |
journal
One entry of the issue history.
| Attribute | Type | Description |
|---|---|---|
id |
Number | Id |
notes |
String | Text of the note, empty for an entry that only changes fields |
created_on |
Time | Time of the entry |
private_notes |
Boolean | The note is private |
user |
user | Who made the entry |
issue |
issue | The issue |
attachments |
Array of attachment | Files attached with the entry |
project
A project.
| Attribute | Type | Description |
|---|---|---|
id |
Number | Id |
identifier |
String | Identifier |
name |
String | Name |
description |
String | Description |
short_description |
String | Short description |
link |
String | HTML link to the project |
url |
String | Path to the project |
is_public |
Boolean | The project is public |
active? |
Boolean | The project is active |
archived? |
Boolean | The project is archived |
visible? |
Boolean | Visible to the current user |
overdue? |
Boolean | The due date has passed |
start_date |
Date | Start date |
due_date |
Date | Due date |
completed_percent |
Number | Percent of completion |
issues |
issues | Issues of the project |
users |
users | Users involved in the project |
subprojects |
projects | Subprojects |
projects
A list of projects.
| Attribute | Type | Description |
|---|---|---|
all |
Array of project | All projects |
active |
Array of project | Active projects |
size |
Number | Number of projects |
projects[identifier] |
project | The project with this identifier |
user
A user. user is also the current user in every template.
| Attribute | Type | Description |
|---|---|---|
id |
Number | Id |
name |
String | Name as shown in Redmine |
firstname |
String | First name |
lastname |
String | Last name |
mail |
String | E-mail address |
language |
String | Language code |
active? |
Boolean | The user is active |
admin? |
Boolean | The user is an administrator |
logged? |
Boolean | The user is signed in |
avatar |
String | HTML of the avatar |
permissions |
Array of String | Permissions the user has through the memberships |
groups |
Array of String | Names of the groups |
projects |
projects | Visible projects the user is a member of |
users
A list of users.
| Attribute | Type | Description |
|---|---|---|
all |
Array of user | All users of the list |
current |
user | The current user |
size |
Number | Number of users |
users[login] |
user | The user with this login |
attachment
An attached file.
| Attribute | Type | Description |
|---|---|---|
id |
Number | Id |
filename |
String | File name |
title |
String | Title |
description |
String | Description |
filesize |
Number | Size in bytes |
content_type |
String | MIME type |
digest |
String | Checksum of the file |
downloads |
Number | Number of downloads |
created_on |
Time | Upload time |
author |
user | Who uploaded the file |
url |
String | Path to download the file |
link |
String | HTML link to the file |
image? |
Boolean | The file is an image |
thumbnailable? |
Boolean | A thumbnail can be made |
is_text? |
Boolean | The file is a text file |
visible? |
Boolean | Visible to the current user |
read |
String | Content of a text file |
to_base64_string |
String | Content encoded in Base64, for embedding |
images
The image attachments of an issue.
| Attribute | Type | Description |
|---|---|---|
all |
Array of image | All images |
size |
Number | Number of images |
images[42] |
image | The image with the id 42 |
image
An image attachment.
| Attribute | Type | Description |
|---|---|---|
id |
Number | Id |
filename |
String | File name |
filesize |
Number | Size in bytes |
description |
String | Description |
created_on |
Time | Upload time |
author |
user | Who uploaded the image |
url |
String | Public path of the image |
full_url |
String | Public address of the image with the host |
link |
String | HTML link to the image |
asset_base64 |
String | Image encoded in Base64, for embedding in a PDF |
relations
Relations of an issue.
| Attribute | Type | Description |
|---|---|---|
all |
Array of relation | All relations |
size |
Number | Number of relations |
relation
One relation between two issues.
| Attribute | Type | Description |
|---|---|---|
relation_type |
String | Type, for example relates or blocks |
delay |
Number | Delay in days for follows and precedes |
issue_from |
issue | The issue where the relation starts |
issue_to |
issue | The issue where the relation ends |
Checklist item
An item of issue.checklists (needs the Checklists plugin).
| Attribute | Type | Description |
|---|---|---|
id_done |
Boolean | The item is checked |
subject |
String | Text of the item |
is_section |
Boolean | The item is a section heading |
FAQ: "How to get days?" Use time_entry.spent_on.
Examples
-
With
{{issue.project.users}}you reference the array of all users involved in the project this issue belongs to. -
To print a list of all issue notes you can use
{% for journal in issue.journals.all %} {% if journal.notes != '' %} <em>{{journal.created_on | date: "%a, %b %d, %y"}} - {{journal.user.name}}</em> {{journal.notes | textilize }} {% endif %} {% endfor %}... producing the following output:Sun, Dec 09, 18 - User One (Comment of User One...) Mon, Dec 10, 18 - User Two (Comment of User Two...) ...
The{% if journal.notes != '' %}check is necessary to select only entries that actually represent a comment and to ignore entries that contain only changes to some issue field. -
With
{{issue.total_spent_hours | round: 2 }}you will display the total spent hours rounded to 2 decimal places. -
With
http://your.redmine.com{{issue.url}}you can print an URL to the issue.
Custom fields
To access the content of a custom field, use
{{issue | custom_field: "custom_field_name"}}.
{% assign custom_fields = issue | custom_fields%}
{% for field in custom_fields %}
<p><b>{{field}}:</b> {{issue | custom_field: field}}</p>
{% endfor %}
Note: 'issue' here is a an object of type issue. When preparing a multi-issue template there is no such object initially, rather the array 'issues'. You can use this loop to refer to each issue separately.
CSS styling
To add CSS styling direct into the template use the <style> tag as you would in an HTML document.
Import a template
Alternatively, you can
a template. You cannot import a template that has the same name as an existing one unless you mark Rewrite existed. In that case, the existing one will be replaced by the import.
Note: You can try out our sample templates. Just download the .yml template file and import it into your Redmine.