Docs
Reports
Customising reports

What is a report?

A Report, in Hybiscus terms, is a collection of components defined through the schema. For a quick example, refer to the Creating a report section, where you can see a report is simply a schema in which you add a number of components that populate your report.

Components

Components are the various elements that make up your report, such as images, tables, cards, sections, etc. They are also defined through a simple schema, which you add as a series of objects to your report's JSON definition.

Configuration

The Report schema takes two configuration keys, options and config. The options key is an object which specifies content for some of the fields in the report. The config key is another object for specifying various configuration parameters.

Example JSON

 
{
    "type": "Report",
    "options": {
        "report_title": "The report",
        "report_byline": "Yet another byline",
        "version_number": "0.1b",
        "logo_url": "https://hybiscus.dev/public/public/docs/Wordmark.svg"
    },
    "config": {
        "enable_multi_page": true,
        "color_theme": "default",
        "typography_theme": "default"
    },
    "components": []
}

Options

The following options can be specified in the options object. The options in the options key generally specify content that appears in the actual PDF.

KeyDescription
options.report_titleThe title of the report which appears at the top.
options.logo_urlURL to an image to use as a logo in place of the report title. Please note this is only supported on premium plans. See here for more details.
options.report_bylineOptional. A smaller byline which appears underneath the report title. Defaults to Report byline.
options.version_numberOptional. A version number which can be placed on the report.
options.enable_headerOptional. Whether to include the header at the top of the PDF. Defaults to true. Please note this is only supported on premium plans. See here for more details.
options.footer_textOptional. Text to place in the footer of every page. HTML formatting is suported.
options.vertical_marginOptional. The vertical margin applied to all pages (except the cover page), in millimetres. Defaults to 5.
options.horizontal_marginOptional. The horizontal margin applied to all pages (except the cover page), in millimetres. Defaults to 5.

Configuration

The following options can be set in the config object, they typically control configuration of the report but not specifying actual content that appears in the PDF.

KeyDescription
config.landscapeOptional. Whether to generate landscape PDFs. Defaults to false.
config.color_theme / config.colour_themeOptional. The color palette theme to apply to the report. See Themes for more details.
config.typography_themeOptional. The typography theme to apply to the report. See Themes for more details.
config.google_fontsOptional. Configuration for Google Fonts. See Themes for more details.
config.n_pagesDeprecated. The number of pages expected in your report. Please note the Free trial only supports single-page PDF reports. This option is deprecated. Please use config.enable_multi_page instead.
config.enable_multi_pageOptional. Set this to true to build multi-page PDF reports. Defaults to false. Please note the Free trial only supports single-page PDF reports. See here for more details.
config.enable_paginationOptional. Enables pagination at the bottom of the pages. Only applicable to multi-page PDF reports. Defaults to false.
config.cloud_storage.s3Optional. Pre-signed AWS S3 URL for uploading PDF directly to. Please note this is only supported on premium plans. See here for more details.
config.cloud_storage.azure_blob_storageOptional. Pre-signed Azure Blob Storage URL for uploading PDF directly to. Please note this is only supported on premium plans. See here for more details.
config.cloud_storage.google_cloud_storageOptional. Pre-signed Google Cloud Storage URL for uploading PDF directly to. Please note this is only supported on premium plans. See here for more details.
config.webhooksOptional. See the webhooks page for more details.

The report title text can be replaced with a custom logo, that is provided by a publically accessible URL. This URL should point towards an image of format JPG, PNG, or SVG. When the options.logo_url key is set, the options.report_title option is ignored.

Setting a custom logo is only supported with a paid plan. See here for more details.

Cloud storage upload

For more details on uploading your PDF report directly to a cloud storage provider, see here.

Multi-page PDF reports

In cases where you need to add more components that can fit in a single page, you will need to set config.enable_multi_page to true. To generate multi-page PDF reports, you will need a premium plan. The number of pages that will be generated in a single PDF report will be automatically limited by your plan.

Previously, users needed to set config.n_pages to a value greater than 1. This config option still exists, however it is no longer required.

For multi-page PDF reports, you can also enable pagination at the bottom using the config.enable_pagination option.

Missing something?

Hybiscus is continuously improving and adding new features. If you think we are missing a critical feature, please do not hesitate to contact us and offer your feedback at support@hybiscus.dev