Vignettes

[m7pr]

Extends teal vignettes with new reporting features in teal.

[gogonzo]

1. "Adding Support for Reporting to Custom Modules" uses old solution with reporter arg in the $server
2. "getting started with teal" has very short subsections which links to longer documentations. Reporter here adds extra 100 lines which changes look of the vignette so much. IMO describing possible values of init(reporter) can be shorter just bullet-points instead of sections. Maybe we should change "Adding Support for Reporting to Custom Modules" to "Creating reproducible reports" (name tbd) and describe everything related to report there?

[m7pr]

@gogonzo about

Maybe we should change "Adding Support for Reporting to Custom Modules" to "Creating reproducible reports" (name tbd) and describe everything related to report there?

Do you think this should be a document in teal or in teal.reporter? I also have a feeling that this needs a special document that covers only reporting, which is now very extensive : )

[gogonzo]

@gogonzo about

Maybe we should change "Adding Support for Reporting to Custom Modules" to "Creating reproducible reports" (name tbd) and describe everything related to report there?

Do you think this should be a document in teal or in teal.reporter? I also have a feeling that this needs a special document that covers only reporting, which is now very extensive : )

We can do this:

• change a content "Adding Support for Reporting to Custom Modules" to fit a new design. This vignette is also linked in "Creating custom modules", so I guess it is ok to keep it, but update the content
• Create a new vignette called "Managing Reproducible Report Documents in Teal" where we describe:
  a. init(reporter) to control initial state of the reporter
  b. Managing teal_module(s) report cards (with disable_report and after)

[m7pr]

@gogonzo make sense!
Do we need special vignette to cover teal_report? Or can it be included in "Adding Support for Reporting to Custom Modules"?

[gogonzo]

@gogonzo make sense! Do we need special vignette to cover teal_report? Or can it be included in "Adding Support for Reporting to Custom Modules"?

We for sure need teal_report vignette in teal.report. I don't know where in teal should we mention teal_report. Maybe in "Include Data in Teal Application"? I wouldn't spend too much time about teal_report as it serves the same role as teal_data and also it should be possible to specify init(data = <teal_report>).

[m7pr]

Ok, I:

• simplified and shortened teal_report Class in teal.reporter
• simplified and shortened Getting started with teal.modules.general in teal
• updated Adding Support for Reporting to Custom Modules in teal
• created Managing Reproducible Report Documents in teal in teal

Left 3 TODO in Managing Reproducible Report Documents in teal in teal

[m7pr]

This is nasty. c removes all classes and attributes. We can substitute this example to use edit_teal_card.
So it's

custom_reporter_template$set_template(
  function(card) {
    edit_teal_card(card, append = "Templated information", after = 0)
  }
)

[gogonzo]

You should use append(card, <something to add>, after = 0) - then it doesn't loose a class because a first argument is a card

[m7pr]

Yes, I think I'll go with this one

[m7pr]

@gogonzo append doesn't loose the class, but it looses metadata attribute, so there is no name to be displayed in Reporter previewer.

> custom_card <- teal_card()
> metadata(custom_card, "title") <- "The title"
> custom_card
An object of class "teal_card"
Slot "metadata":
Slot "metadata":$title
[1] "The title"

> append(custom_card, "x")
[[1]]
[1] "x"

> append(custom_card, teal_card("x"))
[[1]]
[1] "x"

attr(,"class")
[1] "teal_card"
> metadata(append(custom_card, teal_card("x")))
list()

What do you think about exposing append.teal_card method that also keeps attributes?
We can actually just change edit_teal_card to append.teal_card and remove the part used to modify

[gogonzo]

This module returns unmodified data while output shows the selected dataset.

[m7pr]

Thanks @gogonzo for pointing this out. I wanted to keep the example easy, so we just show that it is enough to return(data) to turn reporting on.

We can extend this example module by adding

rdata <- reactive({
  eval_code(
    data(), 
    substitute(head(dataname), env = list(dataname = as.name(input$dataname))), 
    keep_output = TRUE
  )
})
return(rdata)

or

rdata <- reactive({
  req(input$dataname)
  obj <- data()
  teal_card(obj) <- c(teal_card(obj), "## Glimpse of the dataset", head(obj[[input$dataname]]))
  obj
})

return(rdata)

depending on whether we would like to build the report with eval_code or with teal_card.
I think eval_code is more appropriate here, even though we have substitute usage in it (that I think is advanced for regular R users). We can also extend this example by explaining the keep_output = TRUE

[m7pr]

However this very same code is added in the next section Add content to the report card

So maybe keep Modify the body of the server function as it is, and extend Add content to the report card to use eval_code

[gogonzo]

I don't know if this vignette needs to have two examples. Previously adding reporter was more complicated now Reporter is supported by default as teal_report is passed to the teal_module's server. Only thing which user has to do is return(<teal_report>). I'd just mention keep_output and add one markdown-heading element.

[m7pr]

Ok, I think I can remove the whole first example and just use the last one

[m7pr]

I simplified adding-support-for-reporting.Rmd vignette 2cca04b

[gogonzo]

Can you show some practical information, like setting a Rmd template or adding some header/footer etc.?

[m7pr]

I was rather thinking about setting some templated text for disclaimers, data sources, data privacy information, etc as an information added on top or at the bottom of the card. This sentence can also be added to this example.

The Rmd template could be useful, if we create some text that can be interpreted as rmarkdown. Maybe including a logo that is taken from the web?

[gogonzo]

You should use append(card, <something to add>, after = 0) - then it doesn't loose a class because a first argument is a card

[gogonzo]

Both, after and disable_report can control module's report. After is more powerful and it doesn't restrict to the report only but to the whole teal_report/teal_data object. We can showcase how to modify the report using after

Suggested change

	While the `reporter` parameter controls reporting globally, you can also disable reporting for specific modules using `disable_report()`. This allows you to have fine-grained control over which modules support reporting:
	While the `reporter` parameter controls reporting globally, you can also manage a report document for a specific module using `after()` `disable_report()`:

[m7pr]

@gogonzo there is a section following this sentence that presents the usage of after:
Using the after Function to Customize Module Report Cards

Do you think it's enough? It shows that you can adjust the teal_card of teal_report, but we can apply join_keys modifications as well, and also an eval_code to show that the whole teal_data/teal_report can be changed in any direction, not only the @teal_report field.