A little-known feature in rbokeh is a function that will save an htmlwidget (including rbokeh figures of course) to a github gist and share it, along with its source code, through services like bl.ocks.org or allow it to be embedded in a web-based document or presentation.

Github gists can be a useful way to share code snippets that generate interesting plots. An rbokeh function, widget2gist(), provides a way to do this easily with any htmlwidget.

If you want to try this function, since rbokeh is on CRAN now, you can simply install it with

install.packages("rbokeh")

Suppose, for example, we want to share how to make a canonical plot example with rbokeh:

library(rbokeh)

figure(data = ggplot2::mpg, legend_location = "top_left") %>%
  ly_bar(class, color = drv)

We can create a gist for this by simply providing the code as a string and passing it to widget2gist() with a name.

p <- '
library(rbokeh)

figure(data = ggplot2::mpg, legend_location = "top_left") %>%
  ly_bar(class, color = drv)
'
widget2gist(p, name = "blog post example")

This creates the plot and sends the R code and the html that generates the widget to a new github gist in your account.

The output of the function provides some information for how you can access and share the gist:

* Browse this gist on github:
   https://gist.github.com/389bf8b993e73c13f1f5
* View or share this gist on bl.ocks.org:
   http://bl.ocks.org/hafen/389bf8b993e73c13f1f5
* Embed in an iframe:
   <iframe width="500" height="540" frameBorder="0" webkitallowfullscreen="" mozallowfullscreen="" allowfullscreen="" sandbox="allow-forms allow-scripts allow-popups allow-same-origin allow-pointer-lock" src="https://cdn.rawgit.com/hafen/389bf8b993e73c13f1f5/raw/5463453d8321070f8ec4cd4344842e4d2b610e3c/index.html"></iframe>

It also opens up the gist on bl.ocks.org:

As you can see, this provides have a nice way to share htmlwidgets snippets with others with the associated interactive live output shown in a nicely formatted page on bl.ocks.org. Note that it is a good practice to make your code as reproducible as possible if this is your goal, such as ensuring that your code loads appropriate libraries and provides any necessary data.

I also often use htmlwidget gist outputs as a way to embed htmlwidgets in online presentations and documents using the iframe snippet. This can be nice when you don’t have the option of knitr/rmarkdown.

widget2gist() assumes you have a github account and that you have an authentication token set up for pushing gists to your account. Scott Chamberlain’s gistr package is used behind the scenes.

Things to do / think about

  • It would be nice to be able to pass an R expression to widget2gist() instead of a string. However, expressions do not preserve the original formatting, comments, etc. and these would therefore be lost in the code listing in the README.
  • It would be nice if bl.ocks.org could be made to do R syntax highlighting.
  • Ideally this and other htmlwidget utility functions such as saving a raster image of an htmlwidget (which by the way can be done with rbokeh::widget2png()) should be in their own package or be made part of the htmlwidgets package, but since I use these frequently with rbokeh they are fine here for now.
  • While we can save raster images of rbokeh plots as thumbnails using rbokeh::widget2png(), I haven’t figured out how to send these thumbnails to the gist that is being created so that there is a nice thumbnail accompanying the bl.ocks.org listing. This would be really nice.
  • The index.html files created for htmlwidgets can get quite large since they are self-contained. It would be nice if htmlwidgets could optionally specify CDN resources for javascript dependencies (if they exist) and use these instead of embedding it all into the page.