---
title: "Creating bespoke reports"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Creating bespoke reports}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

This vignette introduces the essentials of how to add visualisations from the
`mantis` package into your own bespoke html reports. It will be assumed that you
already 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 before proceeding.

Note: Currently, `mantis` uses `rmarkdown` to generate its content and reports,
and so the visualisations may not render as expected if added to a Quarto
report. In future there will be more support for generating/adding to Quarto
reports.


## Overview 

The standard `mantis_report()` is designed for quick and simple review of time
series that can be stored in a single data frame. If you like the `mantis`
visualisations but want to build a more complex report, e.g. to display data
from multiple data frames, display `mantis` content alongside other (non-`mantis`)
content, or to add your own branding, you can create your own html report
using existing `rmarkdown` functionality, and then insert `mantis` content
and/or tabs into your report as desired.

The easiest way to get started with this is to clone the
[mantis-templates](https://github.com/phuongquan/mantis-templates) project to
see it in action, then choose a template Rmd file that you can copy from/adapt.

## Adding `mantis` content

`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:**

````{verbatim}
```{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'`.

````{verbatim}
```{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.

````{verbatim}
```{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(); }
```
````