Merge branch 'master' of https://github.com/ropensci/plotly into fix/build

Author: cpsievert

CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing to plotly.js
+
+## Opening issues
+
+Search for existing and closed issues. If your problem or idea is not addressed yet, [please open a new issue](https://github.com/ropensci/plotly/issues/new)
+
+Bug reports __must__ have a [reproducible example](http://adv-r.had.co.nz/Reproducibility.html) and include the output of `devtools::session_info()` (instead of `sessionInfo()`).
+
+GitHub issues are great for reporting bugs and requesting new features, but implementation questions are better suited for Stack Overflow (tagged
+[`plotly`](https://stackoverflow.com/questions/tagged/plotly)) or on
+community.plot.ly (tagged [`plotly-js`](http://community.plot.ly/c/plotly-js)).
+
+## Development guidelines
+
+If you'd like to contribute changes to plotly, we use [the GitHub flow](https://guides.github.com/introduction/flow/index.html) for proposing, submitting, reviewing, and accepting changes. If you haven't done this before, Hadley Wickham provides a nice overview of git (<http://r-pkgs.had.co.nz/git.html>), as well as best practices for submitting pull requests (<http://r-pkgs.had.co.nz/git.html#pr-make>). We also recommend using his style guide when writing code (<http://adv-r.had.co.nz/Style.html>).
+
+If your pull request fixes a bug, or implements a new feature, it's a good idea to write a test (<http://r-pkgs.had.co.nz/tests.html>) to demonstrate it's working. If you'd like to closely simulate the tests that run when you submit your pull request, open R under your local plotly git repo, then do the following:
+
+```r
+# the pull request number is arbitrary when running locally
+Sys.setenv('TRAVIS_PULL_REQUEST' = '1')
+Sys.setenv('TRAVIS_COMMIT' = substr(system('git rev-parse HEAD', intern = T), 1, 7))
+devtools::load_all(); source('tests/testthat.R', chdir = TRUE)
+```
+
+You can also build a ggplot2/plotly comparison table:
+
+```r
+Sys.setenv('PLOTLY_TEST' = 'TRUE')
+devtools::load_all(); source('tests/testthat.R', chdir = TRUE)
+```
+
+## Code of Conduct
+
+We want to encourage a warm, welcoming, and safe environment for contributing to this project. See the [code of conduct](https://github.com/ropensci/plotly/blob/master/CONDUCT.md) for more information.

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: plotly
 Title: Create Interactive Web Graphics via Plotly's JavaScript Graphing Library
-Version: 2.0.18
+Version: 2.0.19
 Authors@R: c(person("Carson", "Sievert", role = c("aut", "cre"),
     email = "[email protected]"),
     person("Chris", "Parmer", role = c("aut", "cph"),

NAMESPACE

@@ -4,6 +4,7 @@ S3method(print,figure)
 S3method(print,plotly)
 export("%>%")
 export(add_trace)
+export(as.widget)
 export(config)
 export(embed_notebook)
 export(get_figure)

NEWS

@@ -1,3 +1,7 @@
+2.0.19 -- 23 Dec 2015
+
+Added as.widget() function for conveniency in converting plotly object to htmlwidget objects. See #294.
+
 2.0.18 -- 22 Dec 2015
 
 Fix #365

R/print.R

@@ -1,33 +1,37 @@
 #' Print a plotly object
 #' 
 #' @param x a plotly object
-#' @param ... additional arguments (currently ignored)
+#' @param ... additional arguments
 #' @export
 #' @importFrom htmlwidgets createWidget
 #' @importFrom htmlwidgets sizingPolicy
 print.plotly <- function(x, ...) {
-  w <- toWidget(x)
-  get("print.htmlwidget", envir = asNamespace("htmlwidgets"))(w)
+  if (!inherits(x, "htmlwidget")) x <- as.widget(x)
+  get("print.htmlwidget", envir = asNamespace("htmlwidgets"))(x, ...)
 }
 
 #' Print a plotly object in a knitr doc
 #' 
 #' @param x a plotly object
 #' @param options knitr options.
-#' @param ... additional arguments (currently ignored)
+#' @param ... additional arguments
 #' @export
 knit_print.plotly <- function(x, options, ...) {
-  w <- toWidget(x)
-  get("knit_print.htmlwidget", envir = asNamespace("htmlwidgets"))(w, options = options)
+  if (!inherits(x, "htmlwidget")) x <- as.widget(x)
+  get("knit_print.htmlwidget", envir = asNamespace("htmlwidgets"))(x, options = options, ...)
 }
 
 #' Convert a plotly object to an htmlwidget object
 #' 
-#' Users shouldn't need to use this function. It's exported for internal reasons.
-#' 
 #' @param x a plotly object.
+#' @param ... other options passed onto \code{htmlwidgets::createWidget}
+#' @export
+#' @examples \dontrun{
+#' p <- plot_ly(mtcars, x = mpg, y = disp, mode = "markers")
+#' htmlwidgets::saveWidget(as.widget(p), "index.html")
+#' }
 #' 
-toWidget <- function(x) {
+as.widget <- function(x, ...) {
   p <- plotly_build(x)
   # set some margin defaults if none are provided
   p$layout$margin <- modifyList(
@@ -41,13 +45,17 @@ toWidget <- function(x) {
     x = p,
     width = p$width,
     height = p$height,
-    htmlwidgets::sizingPolicy(
+    sizingPolicy = htmlwidgets::sizingPolicy(
       padding = 5, 
       browser.fill = TRUE
-    )
+    ),
+    ...
   )
 }
 
+# for legacy reasons
+toWidget <- as.widget
+
 #' Print a plotly figure object
 #' 
 #' @param x a plotly figure object

R/shiny.R

@@ -26,6 +26,6 @@ plotlyOutput <- function(outputId, width = "100%", height = "400px") {
 renderPlotly <- function(expr, env = parent.frame(), quoted = FALSE) {
   if (!quoted) { expr <- substitute(expr) } # force quoted
   # https://github.com/ramnathv/htmlwidgets/issues/166#issuecomment-153000306
-  expr <- as.call(list(call(":::", quote("plotly"), quote("toWidget")), expr))
+  expr <- call("as.widget", expr)
   shinyRenderWidget(expr, plotlyOutput, env, quoted = TRUE)
 }

README.md

@@ -20,7 +20,7 @@ devtools::install_github("ropensci/plotly")
 
 ## Introduction
 
-If you use [ggplot2](http://cran.r-project.org/package=ggplot2), simply call `ggplotly()` to convert your ggplot to an interactive, web-based version!
+If you use [ggplot2](http://cran.r-project.org/package=ggplot2), use `ggplotly()` to convert your ggplot to an interactive, web-based version!
 
 ```r
 library(plotly)
@@ -50,19 +50,15 @@ The `ggplotly()` function converts a ggplot object to a plotly object, so if you
 layout(gg, hovermode = "closest")
 ```
 
-## Learn more
+## Documentation
 
-* [An overview of plotly's R API](https://cdn.rawgit.com/ropensci/plotly/master/vignettes/intro.html)
-* Peruse the examples on plotly's [R homepage](https://plot.ly/r) and [ggplot2 homepage](https://plot.ly/ggplot2)
+* [An introduction to plotly's R API](https://cran.r-project.org/web/packages/plotly/vignettes/intro.html)
+* Examples and vignettes on plotly's R homepage - <https://plot.ly/r>
+* The complete figure reference guide - <https://plot.ly/r/reference>
 
 ## Contributing
 
-- We love collaboration! See the [wiki](https://github.com/ropensci/plotly/wiki/Development-guidelines) and the [code of conduct](https://github.com/ropensci/plotly/blob/master/CONDUCT.md) for more information.
-
-## Stay in touch
-
-- <[email protected]>
-- [@plotlygraphs](https://twitter.com/plotlygraphs)
+Please read through our [contributing guidelines](https://github.com/ropensci/plotly/blob/master/CONTRIBUTING.md). Included are directions for opening issues, asking questions, contributing changes to plotly, and our code of conduct. 
 
 ---