---
title: "teal.reporter blocks overview"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{teal.reporter blocks overview}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## 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 load_mermaid, echo=FALSE}
shiny::tags$script(type = "module", "import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/+esm'")
```

```{r actors_mermaid2, echo=FALSE}
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:
```{r}
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:

```{r, eval=requireNamespace("ggplot2")}
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()
```