teal.reporter blocks overview

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:

%% 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")

## $echo
## [1] TRUE
## 
## $tidy.opts
## $tidy.opts$width.cutoff
## [1] 60
## 
## 
## $tidy
## [1] TRUE

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()

## [[1]]
## <TextBlock>
##   Inherits from: <ContentBlock>
##   Public:
##     clone: function (deep = FALSE) 
##     from_list: function (x) 
##     get_available_styles: function () 
##     get_content: function () 
##     get_style: function () 
##     initialize: function (content = character(0), style = private$styles[1]) 
##     set_content: function (content) 
##     set_style: function (style) 
##     to_list: function () 
##   Private:
##     content: Header 2 text
##     deep_clone: function (name, value) 
##     style: header2
##     styles: default header2 header3 verbatim
## 
## [[2]]
## <TextBlock>
##   Inherits from: <ContentBlock>
##   Public:
##     clone: function (deep = FALSE) 
##     from_list: function (x) 
##     get_available_styles: function () 
##     get_content: function () 
##     get_style: function () 
##     initialize: function (content = character(0), style = private$styles[1]) 
##     set_content: function (content) 
##     set_style: function (style) 
##     to_list: function () 
##   Private:
##     content: A paragraph of default text
##     deep_clone: function (name, value) 
##     style: default
##     styles: default header2 header3 verbatim
## 
## [[3]]
## <PictureBlock>
##   Inherits from: <FileBlock>
##   Public:
##     clone: function (deep = FALSE) 
##     from_list: function (x, output_dir) 
##     get_content: function () 
##     get_dim: function () 
##     get_title: function () 
##     initialize: function (plot) 
##     set_content: function (content) 
##     set_dim: function (dim) 
##     set_title: function (title) 
##     to_list: function (output_dir) 
##   Private:
##     content: /tmp/Rtmp9uudpO/filea4040df3c4b.png
##     deep_clone: function (name, value) 
##     dim: 800 600
##     finalize: function () 
##     supported_plots: ggplot grob trellis Heatmap
##     title: 
##     type: 
## 
## [[4]]
## <TableBlock>
##   Inherits from: <FileBlock>
##   Public:
##     clone: function (deep = FALSE) 
##     from_list: function (x, output_dir) 
##     get_content: function () 
##     initialize: function (table) 
##     set_content: function (content) 
##     to_list: function (output_dir) 
##   Private:
##     content: /tmp/Rtmp9uudpO/filea406c07889c.rds
##     deep_clone: function (name, value) 
##     finalize: function () 
##     supported_tables: data.frame rtables TableTree ElementaryTable listing_df
## 
## [[5]]
## <RcodeBlock>
##   Inherits from: <ContentBlock>
##   Public:
##     clone: function (deep = FALSE) 
##     from_list: function (x) 
##     get_available_params: function () 
##     get_content: function () 
##     get_params: function () 
##     initialize: function (content = character(0), ...) 
##     set_content: function (content) 
##     set_params: function (params) 
##     to_list: function () 
##   Private:
##     content: airquality_new <- airquality
##     deep_clone: function (name, value) 
##     params: list

Overview of Content Blocks

Table: Content Blocks in teal.reporter

Global knitr Options

Example Report Using Multiple Content Blocks

Table: Content Blocks in `teal.reporter`

Global `knitr` Options