add support for local MathJax; introduce TeX(); closes #375

Author: cpsievert

NAMESPACE

@@ -81,6 +81,7 @@ S3method(to_basic,default)
 S3method(transmute_,plotly)
 S3method(ungroup,plotly)
 export("%>%")
+export(TeX)
 export(add_annotations)
 export(add_area)
 export(add_bars)

R/layout.R

@@ -91,12 +91,13 @@ rangeslider <- function(p, start = NULL, end = NULL, ...) {
 #' @param collaborate include the collaborate mode bar button (unique to the R pkg)?
 #' @param cloud include the send data to cloud button?
 #' @param locale locale to use. See [here](https://github.com/plotly/plotly.js/tree/master/dist#to-include-localization) for more info.
-#' @param mathjax whether or not to add [MathJax rendering support](https://github.com/plotly/plotly.js/tree/master/dist#to-support-mathjax).
-#' Note that plotly uses SVG-based mathjax rendering which won't play nicely with 
-#' HTML-based rendering (e.g., rmarkdown documents). In this case, you may want to 
-#' consider `<iframe>`-ing your plotly graph(s) into the larger document.
-#' Currently mathjax is loaded externally (meaning an internet
-#' connection is needed to view the graph). Future versions may not have this requirement.
+#' @param mathjax add [MathJax rendering support](https://github.com/plotly/plotly.js/tree/master/dist#to-support-mathjax).
+#' If `cdn`, mathjax is loaded externally (meaning an internet connection is needed to 
+#' view the graph). If `local`, mathjax must be available locally. IMPORTANT: plotly uses 
+#' SVG-based mathjax rendering which doesn't play nicely with HTML-based rendering 
+#' (e.g., rmarkdown documents). In this case, you may want to consider `<iframe>`-ing 
+#' your plotly graph(s) into the larger document. 
+#' See [here](https://github.com/ropensci/plotly/blob/master/inst/examples/rmd/MathJax/index.Rmd) for an example.
 #' @author Carson Sievert
 #' @export
 #' @examples
@@ -125,7 +126,7 @@ rangeslider <- function(p, start = NULL, end = NULL, ...) {
 #' config(p, locale = "zh-CN")
 #' 
 
-config <- function(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL, mathjax = FALSE) {
+config <- function(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL, mathjax = NULL) {
 
   if (!is.null(locale)) {
     p$dependencies <- c(
@@ -135,11 +136,19 @@ config <- function(p, ..., collaborate = TRUE, cloud = FALSE, locale = NULL, mat
     p$x$config$locale <- locale
   }
 
-  if (!identical(mathjax, FALSE)) {
-    p$dependencies <- c(
-      list(mathjax_cdn()),
-      p$dependencies
+  if (!is.null(mathjax)) {
+    mj <- switch(
+      match.arg(mathjax, c("cdn", "local")),
+      cdn = mathjax_cdn(),
+      local = mathjax_local()
     )
+    # if mathjax is already supplied overwrite it; otherwise, prepend it
+    depNames <- sapply(p$dependencies, "[[", "name")
+    if (any(idx <- depNames %in% "mathjax")) {
+      p$dependencies[[which(idx)]] <- mathjax
+    } else {
+      p$dependencies <- c(list(mj), p$dependencies)
+    }
   }
 
   p$x$config <- modify_list(p$x$config, list(...))

R/mathjax.R

@@ -1,3 +1,30 @@
+#' Render TeX in a plotly graph using MathJax
+#' 
+#' This function makes it slightly easier to render TeX in a plotly graph --
+#' it ensures that MathJax is included with the final result and also
+#' ensures the provided string is surrounded with `$` (this is what plotly.js
+#' uses to declare a string as TeX).
+#' 
+#' @param x a character vector
+#' @export
+#' @seealso [config]
+#' @examples 
+#' 
+#' plot_ly(x = c(1, 2, 3, 4), y = c(1, 4, 9, 16)) %>%
+#'   layout(title = TeX("\\text{Some mathjax: }\\alpha+\\beta x")) %>%
+#'   config(mathjax = "cdn")
+
+TeX <- function(x) {
+  startsWithDollar <- grepl("^\\$", x)
+  endsWithDollar <- grepl("\\$$", x)
+  x <- paste0(if (!startsWithDollar) "$", x, if (!endsWithDollar) "$")
+  prefix_class(x, "TeX")
+}
+
+is.TeX <- function(x) {
+  inherits(x, "TeX")
+}
+
 mathjax_cdn <- function() {
   htmltools::htmlDependency(
     name = "mathjax",
@@ -7,34 +34,45 @@ mathjax_cdn <- function() {
   )
 }
 
-# TODO: wait until there is a more official way to include query parameters
+# TODO: wait until there is a more official way to include query parameters?
 # https://github.com/rstudio/htmltools/issues/98
 mathjax_local <- function() {
+  path <- mathjax_path()
+  
+  mj <- file.path(path, "MathJax.js")
+  if (!file.exists(mj)) stop("Couldn't locate MathJax.js")
+  
+  # parse the version
+  mathjax <- readLines(mj)
+  pat <- 'MathJax.fileversion="[0-9].[0-9].[0-9]'
+  ver <- regmatches(mathjax, regexpr(pat, mathjax))
+  ver <- sub('"', '', strsplit(ver, "=")[[1]][2])
+  
+  # make sure we have access to the right config
+  config <- file.path(path, "config", "TeX-AMS-MML_SVG.js")
+  if (!file.exists(config)) stop("Couldn't locate necessary MathJax config: TeX-AMS-MML_SVG")
+  
   htmltools::htmlDependency(
-    name = "mathjax",
-    version = "2.7.4",
-    src = c(file = mathjax_path()),
-    script = "MathJax.js?config=TeX-AMS-MML_SVG"
+    name = "mathjax", 
+    version = ver, 
+    src = path,
+    script = c("MathJax.js", "config/TeX-AMS-MML_SVG.js")
   )
 }
 
 
 mathjax_path <- function() {
   path <- Sys.getenv("PLOTLY_MATHJAX_PATH", NA)
+  
   if (!is.na(path)) {
     mj <- file.path(path, "MathJax.js")
     if (!file.exists(mj)) stop("Couldn't find 'MathJax.js' file in local directory")
     return(path)
   }
 
-  if (system.file(package = "rmarkdown") != "") {
-    # Note, this should throw an informative error if the path isn't found
-    return(getFromNamespace("pandoc_mathjax_local_path", "rmarkdown")())
-  } 
-  
   stop(
-    "To use a local version of MathJax with plotly, either set the PLOTLY_MATHJAX_PATH",
-    "environment variable to the location of MathJax or install rmarkdown.",
+    "To use a local version of MathJax with plotly, set the PLOTLY_MATHJAX_PATH",
+    "environment variable to the location of MathJax.",
     call. = FALSE
   )
 }

R/plotly_build.R

@@ -371,6 +371,27 @@ plotly_build.plotly <- function(p, registerFrames = TRUE) {
   # box up 'data_array' attributes where appropriate
   p <- verify_attr_spec(p)
 
+  
+  verify_mathjax <- function(p) {
+    hasMathjax <- "mathjax" %in% sapply(p$dependencies, "[[", "name")
+    if (hasMathjax) return(p)
+    
+    hasTeX <- any(rapply(p$x, is.TeX))
+    if (!hasTeX) return(p)
+    
+    # TODO: it would be much better to add the dependency here, but
+    # htmlwidgets doesn't currently support adding dependencies at print-time!
+    warning(
+      "Detected the use of `TeX()`, but mathjax has not been specified. ",
+      "Try running `config(.Last.value, mathjax = 'cdn')`",
+      call. = FALSE
+    )
+    p
+  }
+  
+  # make sure we're including mathjax (if TeX() is used)
+  p <- verify_mathjax(p)
+  
   # if a partial bundle was specified, make sure it supports the visualization
   p <- verify_partial_bundle(p)
 

inst/examples/rmd/MathJax/index.Rmd

@@ -0,0 +1,33 @@
+---
+title: "Render plotly MathJax inside rmarkdown"
+output: html_document
+---
+
+Some HTML-based MathJax:
+
+$$ \alpha+\beta $$
+
+You _could_ print this this **plotly** graph with SVG-based rendering, but it would break the HTML-based rendering of **rmarkdown**!
+
+```{r message = FALSE}
+library(plotly)
+
+p <- plotly_empty() %>%
+  add_trace(x = 1, y = 1, text = "$\\alpha$", mode = "text", size = I(1000)) %>%
+  config(mathjax = "cdn")
+```
+
+Instead, use something like the **widgetframe** package to create a responsive iframe. This ensures the SVG-based rendering that plotly requires is done in isolation (i.e., independent of **rmarkdown**'s HTML-based rendering).
+
+```{r}
+widgetframe::frameableWidget(p)
+```
+
+Or, do it the old-fashioned way by saving your plotly graph to an HTML file and use an HTML `<iframe>` to 
+
+```{r}
+htmlwidgets::saveWidget(p, "my-plotly-plot.html")
+```
+
+
+<iframe src="my-plotly-plot.html" width="100%" height="400" id="igraph" scrolling="no" seamless="seamless" frameBorder="0"> </iframe>