# Creating bespoke reports

This vignette introduces the basics of how to generate a bespoke html report containing tabs and visualisations from the `mantis` package. The easiest way to get started is to clone the mantis-templates project to see it in action, then choose a template Rmd file that you can adapt.

Note: Currently, `mantis` uses `rmarkdown` to generate its reports. In future there should be functionality to create Quarto reports.

## Overview

You can use existing `rmarkdown` functionality to create your own bespoke html report, and insert `mantis` content and/or tabs as desired. At a minimum, you need to know how to generate html documents from a Rmd file, including creating tabsets. If you don’t, take a look at the official documentation and/or the many other online resources available.

`mantis` includes one main function `bespoke_rmd_output()` for creating content for bespoke reports. This function use side-effects to generate the desired markdown, and must be placed inside a `{r, results='asis'}` chunk.

The function can:

- add a single visualisation, with or without creating the container tab, or

- add a set of tabs, each based on the same output specification, with or without creating the parent tab.

The function also includes a few additional parameters not available in the standard `mantis_report()` to allow some extra control over the display.

Example:

    ```{r, results='asis'}
    # create a parent tab with a set of child tabs
    mantis::bespoke_rmd_output(
      df = mantis::example_prescription_numbers,
      inputspec = mantis::inputspec(
        timepoint_col = "PrescriptionDate",
        item_cols = c("Location", "Antibiotic"),
        value_col = "NumberOfPrescriptions",
        tab_col = "Location"
      ),
      outputspec = mantis::outputspec_interactive(
        plot_value_type = "value",
        plot_type = "bar",
        item_labels = c("Antibiotic" = "Antibiotic name"),
        plot_label = "Prescriptions over time",
        sync_axis_range = FALSE,
        item_order = list("Location" = c("SITE3", "SITE2", "SITE1"))
      ),
      timepoint_limits = c(NA, Sys.Date()),
      fill_with_zero = FALSE,
      tab_name = "Group of child tabs",
      tab_level = 1
    )
    ```

## Extra requirements for interactive reports

Due to complexities in the way `dygraphs` widgets are rendered, there are two additional chunks that must be included in the Rmd file, otherwise the graphs can disappear unexpectedly.

Firstly, add the following chunk to the Rmd file to ensure the `dygraphs` plots are initialised. Remember to set the same `plot_type` as the one you are using for the rest of the report. This is best placed at the bottom of the file as it can lead to an extra line space. Note: unlike when creating `mantis` content, this chunk should not include `results='asis'`.

    ```{r}
    # this chunk is necessary when using mantis::outputspec_interactive().
    # it ensures that the dygraphs render when built using `cat()`
    # set the plot_type to the same plot_type as the real output
    mantis::bespoke_rmd_initialise_widgets(plot_type = "bar")
    ```

Secondly, when the browser window is resized, all `dygraphs` plots on inactive tabs disappear. A workaround for this is to redraw them all by reloading the page. To do this, add the following chunk at the top of the Rmd file.

    ```{js}
    // this chunk is necessary when using mantis::outputspec_interactive().
    // when the browser window is resized, all dygraphs on inactive tabs disappear. Reload page to
    // redraw them all.
    window.onresize = function(){ location.reload(); }
    ```