RStudio IDE

Extending RStudio with the Viewer Pane

Overview

RStudio includes a Viewer pane that can be used to view local web content. For example, web graphics generated using packages like googleVis and rCharts, or even a local web application created using Shiny, Rook, or OpenCPU.

Note that the Viewer pane can only be used for local web content. This content can either be static HTML files written to the session temporary directory (i.e. files with paths generated by the tempfile function) or a locally run web application. For example, to display generated HTML content you would use code like this:

htmlFile <- tempfile(fileext=".html")
# (code to write some content to the file)
rstudio::viewer(htmlFile)

To display a local web application you would use code like this:

rstudio::viewer("http://localhost:8100")

Invoking the Viewer

Local web content is displayed in the Viewer pane using one of two mechanisms:

  1. By calling the rstudio::viewer function (as was done in the examples above); or
  2. By calling the same function but accessing its definition via getOption("viewer")

The latter approach is strongly preferred because it is front-end agnostic (other IDEs could define this option for alternative implementations of an internal viewer) and allows the user to override the default behavior if need be. For example, a package could use the following code to show content in the viewer when it's available but default back to the system browser when it's not:

viewer <- getOption("viewer")
if (!is.null(viewer))
  viewer("http://localhost:8100")
else
  utils::browseURL("http://localhost:8100")

Viewer Pane Height

If the web content or application you are displaying benefits from a minimum height (or would even like to occupy as much height as possible) then you can use the optional height parameter of the viewerfunction to request a given height. The default behavior if no height is requested is use the existing height of the Viewer pane. For example, to request a minimum height of 500 pixels you could use code like this:

viewer("http://localhost:8100", height = 500)

When requesting a minimum height there are a couple of considerations to keep in mind:

  • The request may or may not be satisfied. This is because RStudio applies the constraint that the resizing of the Viewer pane doesn't leave any other panes with a height of less than 160 pixels.
  • You should be very conservative when requesting a minimum height, as leaving users in control of pane layout is in general a better experience. When it doubt it's better to request less height unless your content absolutely requires more vertical space.

Viewer Detection

When a page is displayed within the Viewer it's possible that the user will choose to pop it out into a standalone browser window. When rendering inside a standard browser you may want to make different choices about how content is laid out or scaled. Web pages can detect that they are running inside the Viewer pane by looking for the viewer_pane query parameter, which is automatically injected into URLs when they are shown in the Viewer. For example, the following URL:

http://localhost:8100

When rendered in the Viewer pane is transformed to:

http://localhost:8100?viewer_pane=1

To provide a good user experience it's strongly recommended that callers take advantage of this to automatically scale their content to the current size of the Viewer pane. For example, re-rendering a JavaScript plot with new dimensions when the size of the pane changes.

Running Shiny Applications

It's possible to run Shiny applications within the Viewer pane by using the launch.browser parameter to the Shiny runApp function. Note however this will only work with the very latest versions of the shiny (0.8) and httpuv (1.2) packages. To install the latest versions of these packages:

install.packages("httpuv")
install.packages("devtools"); devtools::install_github("shiny", "rstudio")

Once you've ensured that you are running the latest versions of these packages you can run a Shiny application within the Viewer pane with code like this:

runApp("MyAppDir", launch.browser = rstudio::viewer)