Add sharing argument and deprecate world_readable. Fixes #332

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: plotly
 Title: Create Interactive Web Graphics via Plotly's JavaScript Graphing Library
-Version: 2.2.4
+Version: 2.3.0
 Authors@R: c(person("Carson", "Sievert", role = c("aut", "cre"),
     email = "cpsievert1@gmail.com"),
     person("Chris", "Parmer", role = c("aut", "cph"),

NEWS

@@ -1,3 +1,7 @@
+2.3.0 -- 19 Jan 2015
+
+Add sharing argument and deprecate world_readable. Fixes #332
+
 2.2.4 -- 18 Jan 2015
 
 Fix for error in embed_notebook(). See #409.

R/plotly_POST.R

@@ -4,15 +4,26 @@
 #' \url{https://plot.ly/rest/}
 #'
 #' @param x either a ggplot object, a plotly object, or a list.
-#' @param filename character string describing the name of the plot in your plotly account. 
-#' Use / to specify directories. If a directory path does not exist it will be created.
-#' If this argument is not specified and the title of the plot exists,
-#' that will be used for the filename.
-#' @param fileopt character string describing whether to create a "new" plotly, "overwrite" an existing plotly, 
-#' "append" data to existing plotly, or "extend" it.
-#' @param world_readable logical. If \code{TRUE}, the graph is viewable 
-#' by anyone who has the link and in the owner's plotly account.
-#' If \code{FALSE}, graph is only viewable in the owner's plotly account.
+#' @param filename character string describing the name of the plot in your 
+#' plotly account. Use / to specify directories. If a directory path does not 
+#' exist it will be created. If this argument is not specified and the title 
+#' of the plot exists, that will be used for the filename.
+#' @param fileopt character string describing whether to create a "new" plotly, 
+#' "overwrite" an existing plotly, "append" data to existing plotly, 
+#' or "extend" it.
+#' @param sharing If 'public', anyone can view this graph. It will appear in 
+#' your profile and can appear in search engines. You do not need to be
+#' logged in to Plotly to view this chart.
+#' If 'private', only you can view this plot. It will not appear in the
+#' Plotly feed, your profile, or search engines. You must be logged in to 
+#' Plotly to view this graph. You can privately share this graph with other 
+#' Plotly users in your online Plotly account and they will need to be logged 
+#' in to view this plot.
+#' If 'secret', anyone with this secret link can view this chart. It will
+#' not appear in the Plotly feed, your profile, or search engines. 
+#' If it is embedded inside a webpage or an IPython notebook, anybody who is 
+#' viewing that page will be able to view the graph. 
+#' You do not need to be logged in to view this plot.
 #' @export
 #' @seealso \link{plot_ly}, \link{signup}
 #' @return An R object created by mapping the JSON content of the plotly API
@@ -24,7 +35,8 @@
 #' plotly_POST(p, filename = "mtcars-bar-plot")
 #' }
 
-plotly_POST <- function(x, filename, fileopt = "new", world_readable = TRUE) {
+plotly_POST <- function(x, filename, fileopt = "new", 
+                        sharing = c("public", "private", "secret")) {
   x <- plotly_build(x)
   x$filename <- if (!missing(filename)) { 
     filename
@@ -34,12 +46,17 @@ plotly_POST <- function(x, filename, fileopt = "new", world_readable = TRUE) {
       paste(c(x$layout$xaxis$title, x$layout$yaxis$title, x$layout$zaxis$title), 
             collapse = " vs. ") %||% "plot from api" 
   }
-  if (!is.null(x$fileopt)) 
-    warning("fileopt was specified in the wrong place. Please specify in plotly_POST()")
+  if (!is.null(x$fileopt)) {
+    warning("fileopt was specified in the wrong place.",
+            "Please specify in plotly_POST()")
+  }
   x$fileopt <- fileopt
-  if (!is.null(x$world_readable)) 
-    warning("world_readable was specified in the wrong place. Please specify in plotly_POST()")
-  x$world_readable <- world_readable
+  if (!is.null(x$world_readable)) {
+    warning("world_readable was specified in the wrong place.",
+            "Please use the sharing argument in plotly_POST()")
+  }
+  x$world_readable <- if (sharing[1] == "public") TRUE else FALSE
+
   # plotly server has trouble with empty properties
   x <- x[sapply(x, length) > 0]
   # construct body of message to plotly server
@@ -55,6 +72,14 @@ plotly_POST <- function(x, filename, fileopt = "new", world_readable = TRUE) {
   base_url <- file.path(get_domain(), "clientresp")
   resp <- httr::POST(base_url, body = bod)
   con <- process(struct(resp, "clientresp"))
+  if (sharing[1] == "secret") {
+    bits <- strsplit(con$url, "/")[[1]]
+    plot_id <- bits[length(bits)]
+    url <- paste0(get_domain("v2"), "files/", verify("username"), ":", plot_id)
+    bod <- list(share_key_enabled = TRUE)
+    con2 <- httr::PATCH(url, plotly_headers("v2"), body = bod, encode = "json")
+    con$url <- paste0(con$url, "?share_key=", content(con2)$share_key)
+  }
   msg <- switch(x$fileopt %||% "new",
                 new = "Success! Created a new plotly here -> ",
                 overwrite = "Success! Modified your plotly here -> ")