8a : Getting started with custom reports

Documentation rédigée le 06/11/2025 par Shannon Bruderer mise à jour le 05/12/2025 par Shannon Bruderer

---

What is a Custom Report ? :

A Custom Report is a template that structures your database records into various output formats such as HTML (for web display), plain text (for transfers without formatting), CSV (for spreadsheet work, e.g. in Excel or Open Office), JSON (for data feeds), or XML (for tagged data exchange).

Note however that CSV, JSON and XML are handled much more easily in the Export tab in Explore unless some very specialised formatting is required.

The development of custom reports can be quite a slow process, so it is best to plan well what reports you need and apply good naming conventions. Some level of simple HTML will be required, and knowledge of CSS will allow for much greater control of the output. PHP and JS functions can also be included (optional). :::

Custom Reports are useful when you need to extract and format specific data for further analysis or publication. They are particualrly useful in settingformatting updata to appear in web pages (see chapter 9). They can also be used to download formatted information or set up feeds of data for other purposes. 

ForThey example,are ifalso youuseful wantfor displaying a single record in Record View, a popup on the map, or wherever data needs to workbe only with female individuals storeddisplayed in yourresponse database,to youselection can:

of

1. Searchone or createmore a Saved Filter that selects all female persons.
2. Build your Custom Report based on this selection.
3. Export your data in the desired format for your analysis.

records.

Tip : Before creating your Custom Report, define clearly what kindsort of analysisdisplay you plan to do. Your analyticalformatting goal will determine both the data you select and the exportway you format youthe choose. :::output.

Reports are built using Smarty, a templating language that combines standard HTML with Smarty tags to dynamically insert data from Heurist.

---

How to start :

:::warningIn the Explore →menu ① you can also focus on a specific record type (Explore > Entities) and select the record type from the list ②

You may wish to perform a more flexible, either by entering it in the Filter →field Report③ →or Customusing Reportthe :::

Filter

Tobuilder begin,just clickbelow on [Explore]. ①

Perform a searchit, or use a [Saved Filter] from the Filters ection ② that returns the records you want to include in your report. ①

You can also focus on a specific record type by clicking on [Entities] and selecting My Record Types, either by Favorites or by Usage. ②

The selected datarecords will appear in the middle section of your screen. ③④

To work with Custom Reports, click on the [Report] attab the top left of your screen. ④⑤

The Custom Report template for your filtered data will appear below the [Report] button. ⑤

The Toolbar

In the upper part of the Custom Report view,tab, you’ll see a toolbar:

Edit Tool

Click [Edit] to open the template editor and start writing your Custom Report with Smarty. The editor is split into three panels:

• Right – Actions pane ① : insert
  
  Insert fields, loops, and conditions via dropdown helpers ②, and browse record types ③ to quickly add the correct field ④
  
• Middle – Editor pane ⑤ : write and edit your HTML + Smarty template here.

  • 
    In the editor, you’ll see the default starter message/template:

  template (note that this template may chage through time as we improve on it, but it will contain a basic loop for records and some instructions to get started). 
  

  {* This is a simple Smarty report template which you can edit into something more sophisticated.
     It should give basic output for any database, as it uses the standard record types which are part of all databases.
     Enter html for web pages or other text format. Use tree on right to insert fields, loops and tests.
     Use this format to include comments in your file, use <!-- --> for output of html comments.
     Smarty help describes many functions you can apply, loop counting/summing, custom functions etc. *}

Below, we will go deeper into Smarty syntax — see X. Smarty Syntax in Heurist.

• Left – Preview pane ⑨ : shows the output when you click [Test] ⑧ . 
  
  You can choose to truncate the preview to n records ⑥ and select how to handle debug messages, warnings, and errors ⑦.

:::info Tips :

• Click [Test] to preview ! Nothing is saved when testing.

• 
  Use [Save] (or [Save As]) to store your template and keep versions.
• 
  Use Ctrl+Z / Cmd+Z to undo recent edits. :::

You can undo a lot of edits by repeating this.

We strongly recommend making only one or two changes at a time and clickign Test to see the results. If somethign doesn't work, you can immediately undo it and try an alternative. 

Don't get tempted to write a lot of code and then test it because then you will have trouble finding the problem.

Create a new template

The [Create a new templat]template] works similarly to the [Edit] tool. It opens the same editor interface where you can create a new Custom Report template from scratch.

Use it when you want to start a fresh layout instead of editing an existing one.

Below, we will go deeper into Smarty syntax — see X. Smarty Syntax in Heurist.

Delete the Selected Template

The [Deleat]Delete] tool allows you to delete the currently selected template.

When clicked, a warning message will pop up asking for confirmation.

It will display the name of your template ① like name_file_.tpl . As here for exemple "Basic (inital record types).tpl"

Click [Proceed] to confirm deletion, or [Cancel] to abort the action.

Import and Export Templates

The Import ← and Export → tools allow you to share and reuse Custom Report templates. 

• For this we have developed a 'global template' format (,gpl) which uses Heurist's unique Concept IDs so that the template can be usd by any database that includes those concepts (definitions of record types, fields and terms). Template files stored in the Heurist database are the same as global files except that they use local codes rather than the unique global concept IDs.

  Templates can only be exported from a registered database to ensure that there are Concept IDs for any definitions used in the template. If the database is not registered you will see the following message.

  

  Import lets you upload an existing global template file (.gpl) and convert it to a local template file (.tpl)

  from your computer into Heurist.

• Export lets you download your customized template as a .tplgpl file, so you can back it up or share it with others.

[🔧COME BACK TO EXPLAIN PERMISSIONS SETTINGS][🔧COME BACK TO EXPLAIN PERMISSIONS SETTINGS]

Obtain JavaScript to embed a report, and set a publishing schedule

The [Publish] option lets you : (a)

• embed a Custom Report in an external website (e.g.,in WordPress)another (b)CMS 
• schedule periodic regeneration with caching for faster load times on large/complex reports.

How to publish (embed)

SetSetting up a scheduled (cached) report

Pros/cons of scheduling

:::success Much faster for large tables, complex calculations, or media-heavy pages. :::

:::danger

Content is a snapshot at the last generation time (not strictly real-time)., :::so frequency of update needs to be approriately set

Download

This allows the download of a plain text file without html formatting (assumng you did nopt use html tags in the report format)

Print

Finally, something super easy and super useful for good documentation and data archiving!

The [Print] buttom simply generates a PDF of the output from your current Custom Report template. It’s a quick and convenient way to export information in aan easy readable, shareable,readable and archivableshareable format.

:::info Tip: Don’t hesitate to use this feature to:

 

•   Enrich your Data Management Plan (DMP),
• 
      Keep track of specific datasets, or
• 
      Share information with colleagues who may not be comfortable navigating Heurist or other “sophisticated” data formats. :::

Refresh

Click on the [Refresh] buttom to update the data used by your Custom Report template.

If your database has been modified (new records, edits, deletions) but the output of your report does not reflect these changes, simply hit Refresh to reload the most recent data and ensure your preview is accurate.