MARS Engine Reporting Module

The Reporting module in MARS Engine enables you to programmatically generate rich documents (PDF, ODT, XLSX, CSV) from templates and dynamic data.

Overview

The report API supports:

• PDF (from ODT templates)
• ODT (from ODT templates)
• XLSX (from XLSX templates)
• CSV (from data arrays)

For ODT-based outputs (PDF, ODT), templates MUST be in ODT format.
XLSX and CSV don't require ODT templates.

Main Functions

report

Base function for generating a PDF from an ODT template:

const data = {
  text_1: "lorem ipsum",
  text_2: "I am thrilled that you'll be joining our team. Each and every day, we serve our customers exceptional food"
}

report("link to, or binary data of the ODT file", data)
// generates and writes out a PDF file

Customize headers before calling report() to change the filename or disposition.

report.odt()

Generates and returns an ODT document.

const odt_file = report.odt("Link to ODT file or binary", user_data);
write(odt_file);

report.pdf()

Generates and returns a PDF.

const pdf_file = report.pdf("Link to ODT file or binary", user_data);
write(pdf_file);

report.xlsx()

Generates and returns an XLSX document from a template, combining multiple sheets.

const sheet1 = report.sheet('Sheet_1');
sheet1.set('A1', 'Name');
sheet1.set('B1', 'Age');
sheet1.set('A2', 'Alice');
sheet1.set('B2', 30);

const sheet2 = report.sheet('Sheet_2');
for (let i = 0; i < 100; i++) {
  sheet2.set('D' + i, i);
}

const file = report.xlsx('link to file or binary data', sheet1, sheet2);
response.header('Content-Disposition', 'attachment; filename="Report_name.xlsx"');
write(file);

report.sheet()

Creates a sheet object to be added to XLSX files.

const sheet = report.sheet('My_Sheet');
sheet.set('A1', 'Header');
sheet.set('B1', 'Value');

report.csv()

Generates a CSV file from an array of arrays.

const res = db.query('SELECT email, subscribed FROM newsletter');
const arr = [];
arr.push(Object.keys(res[0]));
for (let row of res) {
  arr.push(Object.values(row));
}

const csv = report.csv(arr);
response.header('content-disposition', 'attachment; filename="newsletter.csv"');
write(csv);

CSV is the only format that doesn't require a template file.

Template Requirements

• ODT templates must include variables in single curly braces: {variable}.
• Images can be replaced by placeholders named with variables.
• Repeating sections can use arrays in the data.
• XLSX templates can be blank or partially filled.

Example Data for ODT

const data = {
  text_1: "Welcome!",
  text_2: "Thanks for joining.",
  img_1: 'binary image data',
  items: [
    { name: "Item A", price: 10 },
    { name: "Item B", price: 20 }
  ]
}

In the document:

{text_1}
{img_1}
{items.name} {items.price}

📚 See Also - Document Formatting

• Document Formatting Guide for ODT details.