Pyron

A report template turns the results of a data graph into a finished document, drawing on named values, the choices a report is run with, and a set of helpers that format those values for the page. Those three things are what a template body can reference. To design a template alongside its data, see Report templates.

Slots

A slot is a named value that a data graph produces, dropped into the document wherever it belongs. When a report renders, each slot is filled with the value its data graph worked out.

Every template is bound to one data graph. The data graph gathers and shapes the report's data — totals, lists, and single values — and hands back each result under a name. Every one of those named results is a slot the template body can pull in by that name. In the body, a slot appears as its name wrapped in double braces:

{{ average_response_time }}

Because slots come from the data graph, they change with it. A data graph that produces an average response time, a list of open entries, and a site name gives the template three slots to place. Point a template at a different data graph and its slots change to whatever that graph produces.

A template can also show the report's own reference number. That number exists once the report is generated, so a preview — which saves nothing — shows a stand-in in its place.

Parameters

Parameters are the choices a report is run with. They tell the data graph what to gather — which part of your organisation to cover, and over what stretch of time — and the template body can show them too.

A data graph decides its own parameters, so the exact set depends on how the graph was built. A common set is the part of your tree to cover, a timezone, and a window of time — often given as a start and an end, or as a month and a year. The parameters a person fills in become the report's inputs: the preview inputs you set while building the template, and the fields someone completes when they generate the report on demand or on a schedule.

The body can reference a parameter by name, so a report can state the month it covers or the timezone its times are shown in. A report takes its period from these parameters, not from the clock, so a report run for an earlier month still shows that month.

The timezone parameter does more than fill a heading. The date and time helpers localise their values to it, so a report shows its times in the timezone it was run for. A report without a timezone shows its times in UTC.

Formatting helpers

Helpers shape a raw value for the page. A date arrives as a machine timestamp, a stored choice arrives as high_priority, a column of numbers arrives as a list. A helper turns each into something a reader can take in — a formatted date, readable words, a total. The template body applies them, and when the assistant writes the body it reaches for them for you. In the body, a helper follows the value it works on, after a vertical bar:

{{ generated_at | format_datetime }}

Dates and times

Helper	What it does
`format_date`	Shows a value as a calendar day, in the report's timezone
`format_datetime`	Shows a value as a day and time, in the report's timezone
`format_time`	Shows a value as a time of day, in the report's timezone
`format_datetime_tz`	Shows a day and time in a timezone you name
`format_time_tz`	Shows a time of day in a timezone you name
`calculate_duration`	The gap between two times, in minutes
`ms_to_minutes`	A millisecond figure as whole minutes
`ms_to_minutes_seconds`	A millisecond figure as minutes and seconds
`hours_to_minutes`	An hours figure as whole minutes

Text

Helper	What it does
`title_case`	Turns a stored value like `high_priority` into readable words, keeping acronyms intact
default	Falls back to a value you set when the value is empty
`join_array`	Joins a list into one comma-separated line
`join_array_titled`	Joins a list into a line, tidying each item into readable words
`skip_first_segment`	Drops the first step of a path, such as an organisation name
`relative_path`	Shows a location path relative to a reference point
`lookup_user_names`	Turns people's identifiers into their names

Numbers and lists

Helper	What it does
`sum_field`	Totals a number across a list of items
`avg_field`	Averages a number across a list of items
`count_by`	Counts items by the value of a field
`group_by`	Groups items by the value of a field
`filter_by`	Keeps only the items that match a field value
`get_nested`	Reaches a value nested inside an item by its path

Images and links

Helper	What it does
`static_asset`	Embeds an image, such as a logo, straight into the document
`static_url`	The address of a shared static file

Time helpers

A few helpers stand in for a moment in time, so a document can stamp when it was made.

Helper	What it gives
now()	The moment the report was generated, as a date and time
today()	Today's date
yesterday()	Yesterday's date

Show the period from its parameters

To label the stretch of time a report covers, use its month, year, or window parameters rather than a helper that reads today's date. A report takes its period from the choices it was run with, so a report generated for an earlier month still shows that month.

Report template data