update news; keep improving docs

Author: cpsievert

NEWS.md

@@ -5,8 +5,9 @@
 * Upgraded to plotly.js v1.38.1. A _huge_ amount of features and improvements have been made since v1.29.2 (i.e., the version included in the last CRAN release of the R package - v4.7.1). Highlights include a complete re-write of `scattergl` to make it nearly feature complete with `scatter`, localization of text rendering (i.e., international translations), and two new trace types (`violin` & `table`). Read more about the v1.32.0 release [here](https://codeburst.io/notes-from-the-latest-plotly-js-release-b035a5b43e21) and the complete list of changes [here](https://github.com/plotly/plotly.js/releases).
 * Support for **sf** (simple feature) data structures was added to `plot_ly()`, `plot_mapbox()`, and `plot_geo()` (via the new `add_sf()` function). See [this blog post](https://blog.cpsievert.me/2018/03/30/visualizing-geo-spatial-data-with-sf-and-plotly) for an overview.
 * New "special arguments" `stroke`, `strokes`, `alpha_stroke`, `span`, and `spans` were added for easier control over the stroke (i.e., outline) appearance of various (filled) graphical marks. For an overview, see the **sf** blog post linked to in the bullet point above and the new package demos (list all demos with `demo(package = "plotly")`).
-* One may now inform `ggplotly()` about the relevant **shiny** output size via `session$clientData`. This ensures `ggplotly()` sizing is closer to **ggplot2** sizing, even on window resize. For an example, run `plotly_example("shiny", "ggplotly_sizing")`.
 * The selection (i.e., linked-brushing) mode can now switch from 'transient' to 'persistent' by holding the 'shift' key. It's still possible to _force_ persistent selection by setting `persistent = TRUE` in `highlight()`, but `persistent = FALSE` (the default) is now recommended since it allows one to switch between [persistent/transient selection](https://plotly-book.cpsievert.me/linking-views-without-shiny.html#transient-versus-persistent-selection) in the browser, rather than at the command line.
+* The new `partial_bundle()` function makes it easy to leverage [partial bundles of plotly.js](https://github.com/plotly/plotly.js#partial-bundles) for reduced file sizes and faster render times.
+* One may now inform `ggplotly()` about the relevant **shiny** output size via `session$clientData`. This ensures `ggplotly()` sizing is closer to **ggplot2** sizing, even on window resize. For an example, run `plotly_example("shiny", "ggplotly_sizing")`.
 * Instead of an error, `ggplotly(NULL, "message")` and `plotly_build(NULL, "message")` now returns `htmltools::div("message")`, making it easier to relay messages in shiny when data isn't yet ready to plot (see #1116)
 * The `animation_button()` function gains a `label` argument, making it easier to control the label of an animation button generated through the `frame` API (see #1205).
 

R/partial_bundles.R

@@ -2,34 +2,59 @@
 #'
 #' Leveraging plotly.js' partial bundles can lead to smaller file sizes 
 #' and faster rendering. The full list of available bundles, and the
-#' trace types that they support, are available [here](https://github.com/plotly/plotly.js/blob/master/dist/README.md) 
+#' trace types that they support, are available 
+#' [here](https://github.com/plotly/plotly.js/blob/master/dist/README.md#partial-bundles) 
+#' 
+#' @details WARNING: use this function with caution when rendering multiple 
+#' plotly graphs on a single website. That's because, if multiple plotly.js 
+#' bundles are used, the most recent bundle will override the other bundles.
+#' See the examples section for an example.
 #'
 #' @param p a plotly object.
 #' @param type name of the (partial) bundle. The default, `'auto'`, attempts to  
-#' find the smallest single bundle that can render `p`. If no single partial bundle,
+#' find the smallest single bundle that can render `p`. If no single partial bundle
 #' can render `p`, then the full bundle is used.
 #' @param local whether or not to download the partial bundle so that it can be
 #' viewed later without an internet connection.
 #' @param minified whether or not to use a minified js file (non-minified file can be useful for debugging plotly.js)
 #' @author Carson Sievert
 #' @export
 #' @examples
+#' 
+#' # ----------------------------------------------------------------------
+#' # This function is always safe to use when rendering a single 
+#' # plotly graph. In this case, we get a 3x file reduction.
+#' # ----------------------------------------------------------------------
 #'
 #' library(plotly)
-#' p1 <- plot_ly(x = 1:10, y = 1:10) %>% add_markers()
-#' p2 <- partial_bundle(p1)
-#' f1 <- tempfile(fileext = ".html")
-#' f2 <- tempfile(fileext = ".html")
-#'
+#' p <- plot_ly(x = 1:10, y = 1:10) %>% add_markers()
 #' save_widget <- function(p, f) {
 #'   owd <- setwd(dirname(f))
 #'   on.exit(setwd(owd))
 #'   htmlwidgets::saveWidget(p, f)
 #'   mb <- round(file.info(f)$size / 1e6, 3)
 #'   message("File is: ", mb," MB")
 #' }
-#' save_widget(p1, f1)
-#' save_widget(p2, f2)
+#' f1 <- tempfile(fileext = ".html")
+#' f2 <- tempfile(fileext = ".html")
+#' save_widget(p, f1)
+#' save_widget(partial_bundle(p), f2)
+#' 
+#' # ----------------------------------------------------------------------
+#' # But, since plotly.js bundles override one another, 
+#' # be careful when putting multiple graphs in a larger document!
+#' # Note how the surface (part of the gl3d bundle) renders, but the 
+#' # heatmap (part of the cartesian bundle) doesn't...
+#' # ----------------------------------------------------------------------
+#' 
+#' library(htmltools)
+#' p1 <- plot_ly(z = ~volcano) %>% 
+#'   add_heatmap() %>%
+#'   partial_bundle()
+#' p2 <- plot_ly(z = ~volcano) %>% 
+#'   add_surface() %>%
+#'   partial_bundle()
+#' browsable(tagList(p1, p2))
 #'