teal.reporter blocks overview
In teal.reporter: Reporting Tools for 'shiny' Modules

Overview of Content Blocks

This document serves as a comprehensive guide to the various types of content blocks available in the teal.reporter. These blocks allow users to structure and customize reports.

Table: Content Blocks in `teal.reporter`

The following table outlines the different blocks that can be included in a ReportCard, along with descriptions and usage examples:

| Block Type | Description | Usage Example | |----------------|----------------|-------------------| | ReportCard | Combines various content blocks into a single card. | report_card <- ReportCard$new() | | ContentBlock | Base class for content blocks, can include any type of content. | report_card$append_content(<ContentBlock>) | | TextBlock | Adds text-based content to the report. | report_card$append_text(<text>) | | RcodeBlock | Embeds R code directly into the report. | report_card$append_rcode(<code text>, echo = FALSE) | | NewpageBlock | Marks a new page in the report for organization purposes. | report_card$append_content(<NewpageBlock>) | | FileBlock | Manages file-based content, ensuring proper file handling. | report_card$append_content(<FileBlock>) | | TableBlock | Holds and displays tabular data. | report_card$append_table(<table>) | | PictureBlock | Contains graphical content from classes like ggplot, grob, trellis, and Heatmap. | report_card$append_plot(<plot>) |

These blocks form the building blocks of a ReportCard, each serving a specific function that contributes to the overall layout and content of the report. The ReportCard object utilizes append_* methods to integrate various blocks such as TextBlock, PictureBlock, RcodeBlock, and TableBlock.

The following diagram illustrates the inheritance relationship between the different blocks:

```{css mermaid, echo=FALSE} pre.mermaid { background: transparent; }

```r
shiny::tags$script(type = "module", "import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/+esm'")

shiny::pre(
  class = "mermaid",
  "
%% This is a mermaid diagram, if you see this the plot failed to render. Sorry.
classDiagram
    class ReportCard{
      +append_content()
      +append_text()
      +append_table()
      +append_plot()
      +append_rcode()
      +append_metadata()
    }

    ReportCard <.. FileBlock: utilizes
    ReportCard <.. ContentBlock: utilizes
    ReportCard <.. TextBlock: utilizes
    ReportCard <.. NewpageBlock: utilizes
    ReportCard <.. RcodeBlock: utilizes
    ReportCard <.. PictureBlock: utilizes
    ReportCard <.. TableBlock: utilizes

    ContentBlock <|-- TextBlock
    ContentBlock <|-- NewpageBlock
    ContentBlock <|-- RcodeBlock
    ContentBlock <|-- FileBlock
    FileBlock <|-- PictureBlock
    FileBlock <|-- TableBlock


    namespace Blocks {
      class ContentBlock
      class FileBlock
      class TextBlock
      class NewpageBlock
      class RcodeBlock
      class PictureBlock
      class TableBlock
    }

style ContentBlock fill:lightpurple
style FileBlock fill: lightgreen
style TextBlock fill: pink
style NewpageBlock fill: pink
style RcodeBlock fill: pink
style PictureBlock fill: gold
style TableBlock fill:gold
style ReportCard fill:lightblue
"
)

Global `knitr` Options

To ensure consistency and control over the rendering of markdown elements within reports, teal.reporter adheres to the following default global knitr options:

To access the default values for the global_knitr defaults include: echo: displays the code along with its output (echo = TRUE). tidy: formats the R code for readability using the formatR package if installed (tidy = TRUE), otherwise set to FALSE. * width cutoff: sets the maximum number of characters per line in the code output (tidy.opts = list(width.cutoff = 60)).

You can access and modify these settings as follows:

library(teal.reporter)
getOption("teal.reporter.global_knitr")

Example Report Using Multiple Content Blocks

Below is a complete example demonstrating how to create a report combining various content blocks:

library(ggplot2)

report_card <- ReportCard$new()

report_card$append_text("Header 2 text", "header2")
report_card$append_text("A paragraph of default text")
report_card$append_plot(
  ggplot(airquality, aes(x = Ozone, y = Solar.R)) +
    geom_line(na.rm = TRUE)
)
report_card$append_table(airquality)
report_card$append_rcode("airquality_new <- airquality", echo = FALSE)
report_card$append_metadata(key = "lm", value = lm(Ozone ~ Solar.R, airquality))
report_card$get_content()