2.10 HTML widgets
install_phantomjs() works for Windows, OS X, and Linux. You may also choose to download and install PhantomJS by yourself, if you are familiar with modifying the system environment variable
When knitr detects an HTML widget object in a code chunk, it either renders the widget normally when the current output format is HTML, or saves the widget as an HTML page and calls webshot to capture the screen of the HTML page when the output format is not HTML. Here is an example of a table created from the DT package (Xie, Cheng, and Tan 2018):
If you are reading this book as web pages now, you should see an interactive table generated from the above code chunk, e.g., you may sort the columns and search in the table. If you are reading a non-HTML version of this book, you should see a screenshot of the table. The screenshot may look a little different with the actual widget rendered in the web browser, due to the difference between a real web browser and PhantomJS’s virtual browser.
There are a number of knitr chunk options related to screen-capturing. First, if you are not satisfied with the quality of the automatic screenshots, or want a screenshot of the widget of a particular state (e.g., after you click and sort a certain column of a table), you may capture the screen manually, and provide your own screenshot via the chunk option
screenshot.alt (alternative screenshots). This option takes the paths of images. If you have multiple widgets in a chunk, you can provide a vector of image paths. When this option is present, knitr will no longer call webshot to take automatic screenshots.
Second, sometimes you may want to force knitr to use static screenshots instead of rendering the actual widgets even on HTML pages. In this case, you can set the chunk option
screenshot.force = TRUE, and widgets will always be rendered as static images. Note that you can still choose to use automatic or custom screenshots.
Third, webshot has some options to control the automatic screenshots, and you may specify these options via the chunk option
screenshot.opts, which takes a list like
list(delay = 2, cliprect = 'viewport'). See the help page
?webshot::webshot for the full list of possible options, and the package vignette
vignette('intro', package = 'webshot') illustrates the effect of these options. Here the
delay option can be important for widgets that take long time to render:
delay specifies the number of seconds to wait before PhantomJS takes the screenshot. If you see an incomplete screenshot, you may want to specify a longer delay (the default is 0.2 seconds).
Fourth, if you feel it is slow to capture the screenshots, or do not want to do it every time the code chunk is executed, you may use the chunk option
cache = TRUE to cache the chunk. Caching works for both HTML and non-HTML output formats.
Screenshots behave like normal R plots in the sense that many chunk options related to figures also apply to screenshots, including
fig.cap, and so on. So you can specify the size of screenshots in the output document, and assign figure captions to them as well. The image format of the automatic screenshots can be specified via the chunk option
dev, and possible values are
jpeg. The default for PDF output is
png for other types of output. Note that
png: sometimes there are certain elements on an HTML page that fail to render to the PDF screenshot, so you may want to use
dev = 'png' even for PDF output. It depends on specific cases of HTML widgets, and you can try both
jpeg) before deciding which format is more desirable.
Vaidyanathan, Ramnath, Yihui Xie, JJ Allaire, Joe Cheng, and Kenton Russell. 2018. Htmlwidgets: HTML Widgets for R. https://CRAN.R-project.org/package=htmlwidgets.
Chang, Winston. 2018. Webshot: Take Screenshots of Web Pages. https://CRAN.R-project.org/package=webshot.