Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

164 Add the list of all possible methods (blocks) for ReportCard #272

Merged
merged 15 commits into from
May 24, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions R/ReportCard.R
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
3 changes: 3 additions & 0 deletions man/ReportCard.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

10 changes: 10 additions & 0 deletions vignettes/_setup.Rmd
Original file line number Diff line number Diff line change
@@ -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'")
```
120 changes: 120 additions & 0 deletions vignettes/teal-reporter-blocks-overview.Rmd
Original file line number Diff line number Diff line change
@@ -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** |
kartikeyakirar marked this conversation as resolved.
Show resolved Hide resolved
|----------------|----------------|-------------------|
| **`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()
```
Loading