widgetframe and knitr

Potential Issues

Unless you are working on small one-off Rmd document, it is never a good idea to have self_contained set to its default value TRUE. It results in large HTML documents which are slow to load in the browser. Secondly by inlining dependencies you lose the ability to share common dependencies across different HTMLs. Lastly you also limit the browser’s ability to cache HTML dependencies across sessions.

Even if you were to externalize the dependencies by setting sefl_contained=FALSE, there are still two potential issues…

• Different htmlwidgets may depend on different versions of the same Javascript/CSS dependency. But when the final document is produced only a single version of the said dependency is used. This may cause certain widgets to not display, or work incorrectly.
• The styling rules (CSS) of the widget may be overridden by those of the output format. This will again result in the widget not displaying properly in the final document.

These problems typically don’t occur when knitting one-off HTML documents using the rmarkdown::html_document format. But they do occur once you start outputting documents in the bookdown, blogdown, rmarkdown websites, xaringan and other HTML based output formats. And this is where widgetframe comes in.

widgetfram_self_contained

This option is similar to the self_contained argument of the rmarkdown::html_document() output format. The reason we need a separate chucnk option is because …

1. As explained above knitr_print.widgetframe() has no way of knowing what the output format is and what arguments were passed to it.

2. Unlike self_contained which defaults to TRUE, widgetframe_self_contained defaults to FALSE. That is to say that by default when using widgetframe the dependencies of the target htmlwidgets instance are kept in a separate directory.

There is very little reason to set this option to TRUE. If however you do set it to TRUE the HTML file for the wrapped widget will have its dependencies inlined, resulting in a single large HTML file. Note that this is not the same as your final output HTML. This is just the HTML for the widget which is displayed inside an iframe in the final HTML document. Wheter the final HTML document has inlined dependencies depends on the self_contaied argument of your output format e.g. rmarkdown::html_document().

widgetframe_isolate_widgets

Defaults to TRUE, and when TRUE, isolates HTML dependencies (CSS/JS) of htmlwidgets of different types. This avoids compatibility issues when htmlwidgets of different types depend on the same dependency(ies) but on different versions. For example if you are using some leaflet, and some DT htmlwdigets in your document (doesn’t matter how many), then the dependencies of leaflet widgets will be stored separately from dependencies of DT widgets and any other widget other than leaflet. So leaflet can depend on version ‘X’ of jQuery and DT can depend on version ‘Y’ and both will work correctly. Note that multiple widgets of the same type will share the same set of dependencies in order to avoid unnecessary duplication. There is very little reason to set this option to FALSE.

widgetframe_widgets_dir

This option, if provided, determines where the HTML code for the wrapped htmlwidgets instance is written. Before discussing more we should note that knitr_print.htmlwidgets() never actually creates any files/directories or touches the file-system in any way. It merely returns a R list which then used by the output format to embed the widget’s HTML (and dependencies) in the final document. However, knitr_print.widgetframe() does create HTML file/s and dependencies directories for the wrapped widget. It needs to, so that the final document can embed the widget’s HTML which is saved separately, inside an iframe. This may not be important to know from a user perspective but a must know, if you want to extend or contribute to widgetframe.

For almost all output formats except bookdown, this option should not be set and it will default to file.path(knitr::opts_chunk$get('fig.path'),'widgets'). That is a widgets directory inside the directory knitr::opts_chunk$get('fig.path'). This is done this way because as noted knitr_print has no way of knowing the arguments of the output format including the final destination directory of the document. However it does have access to the fig.path knitr chunk option. Refer to this Github issue for a discussion around this. See the bookdown section below for a use case where this value needs to be explicitly set.

Another scenario where you may need to set this option is when your RMarkdown output format has self_contained=TRUE (Note: This is the self_contained argument of your HTML output format e.g. rmarkdown::html_document and not the widgetframe_self_contained chunk argument described above).

Chunk Options and Output

To understand how each of the three knitr chunk options affect the wrapped widget’s HTML document, see the code and the table below.

```{r leaflet-01}
library(leaflet)
library(widgetframe)
l <- leaflet() %>% addTiles() %>% setView(0,0,1)
frameWidget(l, width='90%')
```

```{r dygraph-01}
library(dygraphs)
ts <- dygraph(nhtemp, main = "New Haven Temperatures")
frameWidget(ts, height = 350, width = '95%')
```

I’ve ommitted the widgetframe_ prefix for each of the 3 options below to conserve space.

†: Default Value.

By default the widget HTML + dependencies (JS/CSS files) are located inside widgets directory, which is created inside wherever knitr::opts_chunk$get('fig.path') points too. However if widgetframe_widgets_dir is set then the widget HTML + dependencies are placed inside a directory whose name is the value of this option, and the path is resolved relative to the current working directory (getwd()) while knitting.