Merge branch 'main' into 546-fix-verdepcheck@main

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: teal.reporter
 Title: Reporting Tools for 'shiny' Modules
-Version: 0.3.1.9006
-Date: 2024-05-16
+Version: 0.3.1.9007
+Date: 2024-05-24
 Authors@R: c(
     person("Dawid", "Kaledkowski", , "dawid.kaledkowski@roche.com", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0001-9533-457X")),

NEWS.md

@@ -1,4 +1,4 @@
-# teal.reporter 0.3.1.9006
+# teal.reporter 0.3.1.9007
 
 ### Enhancements
 

R/ReportCard.R

@@ -6,6 +6,9 @@
 #' This `R6` class that supports creating a report card containing text, plot, table and
 #' metadata blocks that can be appended and rendered to form a report output from a `shiny` app.
 #'
+#' For more information about the various blocks, refer to the vignette:
+#' `vignette("teal-reporter-blocks-overview", "teal.reporter")`.
+#'
 #' @export
 #'
 ReportCard <- R6::R6Class( # nolint: object_name_linter.

vignettes/_setup.Rmd

@@ -0,0 +1,10 @@
+
+```{css, echo=FALSE}
+pre.mermaid {
+  background: transparent;
+}
+```
+
+```{r, echo=FALSE}
+shiny::tags$script(type = "module", "import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/+esm'")
+```

vignettes/teal-reporter-blocks-overview.Rmd

@@ -0,0 +1,120 @@
+---
+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:
+```{r, child="_setup.Rmd"}
+```
+```{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}
+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()
+```