Report Headers

All pre-defined header classes are located in classes/headers/ and extend HeaderBase. Additional user defined headers can be placed in classes/local/.

See how to Create a Custom Report Header

Headers appear as comments at the top of a report file. The specific comment format depends on the report type.

-- This is a SQL report
-- HEADER: value

//This is a javascript (MongoDB) report
//HEADER: value

<?php
//This is a PHP report
//HEADER: value

All headers support the following JSON format:

HEADERNAME: {
    "param1": "value1",
    "param2": { 
        "nested": true 
    }
}

Many headers also have a shortcut syntax for one or more common use cases.

*note Although it is recommended to only use valid JSON, javascript style declarations are also possible with single quoted values and unquoted or single quoted keys.

Here's an example SQL report:

-- This is the report name
-- HEADERNAME: {
--	"param1": "value1"
-- }
-- HEADERNAME2: shortcut, syntax

SELECT * FROM ...

VariableHeader

Used to prompt a user for a value before running a report.

JSON Format

name required The name of the variable. Should only include alphanumeric characters and underscores.
display The display name of the variable. Can contain any characters. Defaults to name
description Will display after the input field in the variable form
type The type of variable. Possible values are:
- "text" (the default)
- "select" (dropdown list)
- "textarea"
- "date" (will be parsed with strtotime)
- "daterange" (will contain start and end date)
format If type is "date" or "daterange", this specifies the date format to convert to. It defaults to "YYYY-MM-DD HH:MM:SS".
options If the type is "select", this should be an array of choices.
default The default value for the variable.
empty If set to true, the report will run even if the value is empty.
multiple If set to true, multiple values can be chosen.
- If type is "select", it will be a multiselect box.
- If type is "textarea", the value will be split by line breaks.
modifier_options An array of choices for a modifier drop down menu. Common values: ["=","!=",">","<"] or ["starts with","ends with","contains"]. Modifiers are passed into the report as {{name}}_modifer where "{{name}}" is the variable name.
database_options If type is "select", this tells the framework to populate the drop down list from a database table. It is an object with the following properties:
- table The database table to select from
- column The column to select
- where An optional WHERE clause
- all If set to true, an additional option named "ALL" will be added to the top of the list.

Examples

VARIABLE: {"name": "date_start", "display": "Start Date", "type": "date"}

VARIABLE: {
    "name": "type",
    "default": "food"
}

VARIABLE: {
    "name": "category",
    "type": "select",
    "database_options": {
        "table": "categories",
        "column": "CategoryName",
        "where": "CategoryStatus = 'active'"
    }
}

VARIABLE: {
    "name": "range",
    "type": "daterange",
    "default": {
        "start": "-1 week",
        "end": "now"
    }
}

Shortcut syntax

Basic "text" variable

VARIABLE: varname, Display Name

VARIABLE: {
    "name": "varname",
    "display": "Display Name",
    "type": "text"
}

A "select" type variable with defined options

VARIABLE: varname, Display Name, option 1|option 2|option 3

VARIABLE: {
    "name": "varname",
    "display": "Display Name",
    "type": "select",
    "options": ["option 1", "option 2", "option 3"]
}

A few other shortcut formats are supported for legacy reasons, but they are not user friendly and difficult to debug. Anything more than these basic options should use JSON.

IncludeHeader

Includes another report in the currently running one.

The included report's headers are parsed and the report contents are prepended to the current report before running.

Possible uses include:

Creating a temp table for a set of MySQL reports
Defining helper functions for MongoDB or PHP reports
Setting up an API connection for a PHP report

JSON Format

report required The path to a report to include. If it starts with "/", it will be relative to the root report directory. Otherwise, it will be relative to the currently running report.

Examples

INCLUDE: {"report": "relative/to/current/report.sql"}

INCLUDE: {"report": "/relative/to/reportdir/report.sql";

Shortcut Syntax

INCLUDE: relative/path/to/report.sql
INCLUDE: /path/to/report.sql

FilterHeader

The Filter header applies a filter to a column of the report.

Possible uses include:

GeoIP lookup that replaces an IP address with City, State Country
HTML filter that preserves html in that column (row values are escaped by default)
Star Rating filter that replaces a number (1-10) with that many images of stars.
Add a CSS class to a column

Each pre-defined filter has it's own documentation. This is just for the FILTER header itself.

JSON Format

column required The column to apply the filter to. Can be the column number (starting at 1) or the column name.
filter required The filter to apply to the column. Must be a valid filter class. "geoip" maps to "geoipFilter".
params An object containing parameters to pass into the filter class. Each filter class accepts different parameters.

Examples

FILTER: {"column": 1, "filter": "geoip"}

FILTER: {
    "column": "Article", 
    "filter": "link",
    "params": {
        "_blank": true,
        "display": "View Article"
    }
}

Shortcut Syntax

FILTER: 1, geoip

FILTER: {
    "column": 1,
    "filter": "geoip"
}

CacheHeader

The Cache header enables automatic report caching for a specified time.

This is useful for expensive reports where the data doesn't change too often.

JSON Format

ttl The number of seconds to cache the report results for

Examples

CACHE: {"ttl": 3600}

This will cache the results for 1 hour (3600 seconds).

Shortcut Syntax

CACHE: 3600

CAHCE: {
	"ttl": 3600
}

DetailHeader

The Detail header is used to tie reports together and provide drill down links.

An example is a report that shows product categories along with the number of products in the category. Another report shows all the products in a single category. You could make the Number of Products column in the 1st report link to the 2nd report.

JSON Format

column required The column that should be turned into a link. Can either be the column number (starting at 1) or the column name.
report required The report to link to.
- If the report path starts with "/", it will be relative to the root report directory
- Otherwise, it will be relative to the currently running report
macros Macros to pass along to the report being linked to.
- Each key in the macros object is the macro name, each value is either a string or {"column": "ColumnName"}. This 2nd option lets you populate a macro from the row's values.

Examples

DETAIL: {
	"column": "ProductCount",
	"report": "/products/products-in-category.sql",
	"macros": {
		"category": {
			"column": "CategoryName"
		},
		"othermacro": "constant value"
	}
}

The ProductCount column will be turned into a link to the products-in-category report.

In each row, the link will contain 2 macros.
The "category" macro would be equal to the CategoryName column's value in that row.
The "othermacro" value would always be "constant value".

The products-in-category.sql report would need something like the following to read these macros:

VARIABLE: {"name": "category"}
VARIABLE: {"name": "othermacro"}

Shortcut Syntax

DETAIL: ProductCount, /products/products-in-category.sql, category=CategoryName, othermacro="constant value"

ChartHeader

The Chart header is used to display graphs and charts of report data.

This uses the Google Visualization API to display line charts, column/bar charts, timelines, map charts, and/or histograms.

The order and datatype of columns required is determined by the Google API for the selected chart type. For example, line charts require a string or date column followed by one or more number columns. Histograms require a single, numeric column.

JSON Format

columns An array of columns to use in the chart. Columns can be specified by column number (starting at 1) or column name. Defaults to all columns in order.
type The type of chart. Possible values are:
- LineChart (the default)
- GeoChart (map)
- AnnotatedTimeline (similar to Google Finance)
- BarChart
- ColumnChart
title An optional title for the chart
width The width of the chart. Supports any css dimension style (e.g. "400px", "80%", "15em", etc.)
height The height of the chart. Also supports any css dimension style.
colors An array of colors to use for chart elements. Supports any html colors (e.g. "red", "#a5f038"). If omitted, Google's default chart colors will be used.
xhistogram If set to true, a histogram will be constructed.
buckets When used with xhistogram, this defines how many buckets to put the data into.

Examples

CHART: {
	"columns": [1,3,4],
	"type": "LineChart",
	"title": "Shopping Cart Abandonment",
	"width": "600px",
	"height": "400px"
}

Assume the columns are as follows: "Date", "Revenue", "Number of Completed Carts", "Number of Abandoned Carts"

This will display a line chart with Date on the x axis and Number of Completed Carts and Number of Abandoned Carts on the y axis.

CHART: {
	columns: ["Price"],
	'type': "ColumnChart",
	"title": "Product Price",
	"xhistogram": true,
	"buckets": 10
}

This will display a histogram of product prices. Data will be broken up into 10 buckets and displayed as a column chart.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Report Headers

Report Headers

VariableHeader

JSON Format

Examples

Shortcut syntax

IncludeHeader

JSON Format

Examples

Shortcut Syntax

FilterHeader

JSON Format

Examples

Shortcut Syntax

CacheHeader

JSON Format

Examples

Shortcut Syntax

DetailHeader

JSON Format

Examples

Shortcut Syntax

ChartHeader

JSON Format

Examples

Clone this wiki locally