Getting Started

Hanami is a specialized scripting language designed to help you create beautiful reports using dynamic data. This guide will help you get started with Hanami and show you how to create your first report.

Before you begin, you'll need to download and install the Hanami application and CLI. Visit our downloads page to get the latest version for your operating system.

Basic Syntax

Hanami uses a clean, intuitive syntax that's easy to learn. Here are the basic elements of the Hanami language:

Variables

Variables are declared using the let keyword:

let global_endpoint = "api.com"
let httpheaders = { a: b, c: d }

Document Structure

Every Hanami report starts with a document declaration, which serves as the entry point for your report (similar to a main() function in other languages):

document main {
    author "John Doe"
    date "2025-01-01"
    
    Content goes here
}

The document can include metadata such as the author and date, followed by the content of your report.

Sections

Sections are the building blocks of a Hanami report. They can contain various elements such as titles, subtitles, tables, charts, and lists:

let testsection = section {
    title "New Title"
    subtitle "Test Subtitle"
    table {
        headers ["a", "b", "c"]
        rows [
            ["a", "b", "c"],
            ["d", "e", "f"]
        ]
    }
}

Sections can be defined separately and then included in the document using the spread operator (...):

document main {
    author "John Doe"
    date "2025-01-01"
    
    ...testsection    
}

Tables

Tables are a common way to present data in Hanami. They consist of headers and rows:

let secondsection = section {
    title "Second Section"
    subtitle "Test Subtitle"
    table {
        headers ["a", "b", "c"]
        rows [
            ["a", "b", "c"],
            ["d", "e", "f"],
            ["g", "h", "i"],
            ["j", "k", "l"],
            ["m", "n", "o"]
        ]
    }
}

Tables can be included in sections and will be rendered with proper formatting in the final report.

Charts

Hanami supports creating charts from data. You can define chart data and then use it in a section:

let barChart = section {
    title "Sales by Quarter"
    chart {
        type "bar"
        labels ["Q1", "Q2", "Q3", "Q4"]
        data [10000, 15000, 12000, 18000]
    }
}

let pieChart = section {
    title "Revenue Distribution"
    chart {
        type "pie"
        labels ["Product A", "Product B", "Product C"]
        data [45, 30, 25]
    }
}

document main {
    ...barChart
    ...pieChart
}

Charts can be customized with different types, labels, and data values. Hanami supports various chart types including bar, line, pie, and more.

Images

Hanami provides several ways to include images in your reports:

coverimage("https://picsum.photos/id/237/200/300", 100, 200)

embeddedimage("local", "https://picsum.photos/id/237/200/300", 100, 200)

embeddedimage("http", "https://picsum.photos/id/237/200/300", 100, 200)

The coverimage function adds a cover image to your report, while embeddedimage embeds an image within the report content. Both functions take parameters for the image source and dimensions.

Lists

Bullet lists can be created within sections:

let bulletlist = section {
    title "Bullet List"
    subtitle "Test Subtitle"
    bullet_list [
        "Item 1",
        "Item 2",
        "Item 3"
    ]
}

The bullet_list function takes an array of strings and renders them as a bulleted list in the report.

Variables

Variables in Hanami can store various types of data, including strings, numbers, objects, and more complex data structures:

let global_endpoint = "api.com"

let httpheaders = { a: b, c: d }

let testsection = section {
    title "New Title"
    subtitle "Test Subtitle"
}

Variables can be used throughout your Hanami script to store and reuse data, sections, and other elements.

Pipelines

Pipelines in Hanami allow you to process data and return a result:

let processedData = pipeline {
    let sales = [
        { product: "A", amount: 100 },
        { product: "B", amount: 200 },
        { product: "C", amount: 300 }
    ]
    
    let total = sales[0].amount + sales[1].amount + sales[2].amount
    
    let average = total / 3
    
    return {
        data: sales,
        total: total,
        average: average,
        highest: sales[2].amount,
        lowest: sales[0].amount
    }
}

let dataSection = section {
    title "Sales Analysis"
    body "Total Sales: {processedData.total}"
    body "Average Sale: {processedData.average}"
    body "Highest Sale: {processedData.highest}"
}

Pipelines can contain variable declarations, calculations, and must end with a return statement that specifies the data to be returned. They are useful for data transformation and preparation before visualization.

SQL Integration

Hanami can connect to databases and execute SQL queries to fetch data for your reports:

Supported Databases

• Postgres
• DB2 (in development)

Configuration

Database credentials can be provided through environment variables:

Bash/Shell

export DB_USERNAME=""
export DB_PASSWORD=""
export DB_PORT=""
export DB_TYPE=""
export DB_HOST=""
export DB_NAME=""
export DB_SCHEMA=""
export DB_SSL_MODE="require"

PowerShell

$env:DB_USERNAME=""
$env:DB_PASSWORD=""
$env:DB_PORT=""
$env:DB_TYPE=""
$env:DB_HOST=""
$env:DB_NAME=""
$env:DB_SCHEMA=""
$env:DB_SSL_MODE="require"

Using SQL in Reports

SQL queries can be executed directly within a section:

section newSection {
    title "SQL Query Results"
    body "This SQL statement below will query the database and return a table with headers and rows of the database."
    sql("select * from ...")
}

document test {
    ...newSection
}

The sql() function executes the SQL query and renders the results as a table in your report.