Updates to R docs

_posts/r/2015-07-30-embedding-in-html.Rmd

@@ -1,6 +1,6 @@
 ---
-title: Embedding Plotly Graphs in HTML with KnitR
-name: Text and Annotations
+title: Embed Graphs in HTML
+name: Embed Graphs in HTML
 permalink: r/embedding-plotly-graphs-in-HTML
 description: How to embed Plotly graphs in HTML pages with Plotly's R API
 layout: base
@@ -11,35 +11,29 @@ has_thumbnail: false
 display_as: layout_opt
 ---
 
-# Embedding Plotly Graphs in HTML
-
-If you have a plotly account, printing plotly objects in the R console will create a new plotly figure (via plotly's REST API). If you're using knitr/R Markdown with HTML output, printing not only creates the plot, but also embeds it as an HTML iframe.
+# Embed Graphs in HTML
 
 ```{r, echo = FALSE, message=FALSE}
 knitr::opts_chunk$set(message = FALSE)
 Sys.setenv("plotly_username"="RPlotBot")
 Sys.setenv("plotly_api_key"="q0lz6r5efr")
 ```
 
-```{r, message=FALSE}
+As of version 2.0, plotly's R package utilizes the [htmlwidgets](http://www.htmlwidgets.org/) framework. As a result, printing objects of class "plotly" in [rmarkdown/knitr HTML documents](http://rmarkdown.rstudio.com/html_document_format.html) will embed the necessary HTML/JavaScript to create the client-side visualization (via [plotly.js](http://plot.ly/javascript)).
+
+```{r}
 library(plotly)
-p <- plot_ly(iris, x = Petal.Length, y = Petal.Width,
-        color = Species, mode = "markers", filename="r-docs/example-plot")
+p <- plot_ly(midwest, x = percollege, color = state, type = "box")
+class(p)
 p
 ```
 
-Plotly graphs hosted on [https://plot.ly](https://plot.ly) can be embedded in webpages as iframes or images. Just add `.embed` or `.png` to the end of the graph URL.
-
-```html
-<iframe src="https://plot.ly/~RPlotBot/501.embed"
-		height="600" width="100%"
-		scrolling="no" seamless="seamless"
-		frameBorder="0">
-</iframe>
-```
+You can also post your figure to a plotly server with `plotly_POST()`. This function returns an object of class figure. When you print a figure object in an rmarkdown/knitr document, it embeds the figure as an iframe (pointing to your figure).
 
-```html
-<img src="https://plot.ly/~RPlotBot/501.png">
+```{r}
+f <- plotly_POST(p, filename = "r-docs/midwest-boxplots")
+class(f)
+f
 ```
 
-[Learn more about embedding graphs in HTML pages, blogs, and websites in our tutorial](http://help.plot.ly/embed-graphs-in-websites/).
+If you want more control over embedding graphs hosted on <https://plot.ly>, [learn how to embed plotly graphs with HTML iframes](http://help.plot.ly/embed-graphs-in-websites/)

_posts/r/2015-07-30-filenames.Rmd

@@ -18,49 +18,26 @@ Sys.setenv("plotly_username"="RPlotBot")
 Sys.setenv("plotly_api_key"="q0lz6r5efr")
 ```
 
-```{r, message=FALSE}
+To create a plotly figure on a plotly server, use `plotly_POST()`.
+
+```{r}
 library(plotly)
+p <- plot_ly(x = c(1, 2), y = c(1, 2))
+plotly_POST(p)
 ```
 
-By default, if you don't specify a filename,
-printing `plot_ly` will create a new plot in your online plotly account.
-
-```{r, message=FALSE}
-plot_ly(x = c(1, 2), y = c(1, 2))
-```
 <br>
-If you want to overwrite the plot and keep the graph served from the same plotly URL, specify a filename.
-This implicitly overwrites your plotly graph.
-View your Plotly graphs at [https://plot.ly/organize](https://plot.ly/organize).
-
-```{r, message=FALSE}
-plot_ly(x = c(1, 2), y = c(1, 2), filename="name-of-my-plotly-file")
-```
 
-Overwriting your graph works a bit differently when using ```subplots```.
-To update a graph with ```subplots``` use ```plotly_build()``` and then assign the ```filename```.
+If you don't include a filename, a new plot will be made on your online plotly account. If you want to overwrite a plot (i.e., keep the graph served from the same plotly URL), specify a filename. This implicitly overwrites your plotly graph.
 
-```{r, message=FALSE}
-p <- plotly_build(subplot(
-	plot_ly(x = c(1, 2), y = c(1, 2)),
-	plot_ly(x = c(1, 2), y = c(2, 1)),
-	margin = 0.05
-	)
-)
-p$filename <- "overwrite_subplots"
+```{r}
+plotly_POST(p, filename = "name-of-my-plotly-file")
 ```
 
-Add modifications then see the updated graph at the same plotly URL:
-
-```{r, message=FALSE}
-p <- layout(showlegend = FALSE, title = "Overwrite Subplots")
-p$filename <- "overwrite_subplots"
-p
-```
-
-<br>
 If the filename contains "/", it will automatically create a plotly folder.
 
-```{r, message=FALSE}
-plot_ly(x = c(1, 2), y = c(1, 2), filename="r-docs/name-of-my-plotly-file")
+```{r}
+plotly_POST(p, filename="r-docs/name-of-my-plotly-file")
 ```
+
+View your Plotly graphs at [https://plot.ly/organize](https://plot.ly/organize).

_posts/r/2015-07-30-get-requests.Rmd

@@ -19,25 +19,25 @@ Sys.setenv("plotly_username"="RPlotBot")
 Sys.setenv("plotly_api_key"="q0lz6r5efr")
 ```
 
-Download Plotly figures directly into R with `get_figure`. This takes the `username` and the `plot_id` as arguments.
+Download Plotly figures directly into R with `get_figure()`. This takes the `username` and the `plot_id` as arguments.
 
 For example, to download [https://plot.ly/~cpsievert/559](https://plot.ly/~cpsievert/559) into R, call:
 
-```{r, message=FALSE}
+```{r}
 library(plotly)
 fig <- get_figure("cpsievert", "559")
 ```
 
 <br>
 Once the figure is downloaded, you can edit it like any plotly object. This will create a new figure unless you specify the same filename as the figure that you downloaded.
 
-```{r, message=FALSE}
+```{r}
 layout(fig, title = paste("Modified on ", Sys.time()))
 ```
 
-### Adding Traces with `get_figure` and `subplot`.
+### Adding Traces with `get_figure()` and `subplot()`.
 
-After downloading a figure with subplots, use `plotly_build` to build the figure. 
+After downloading a figure with subplots, use `plotly_build()` to build the figure. 
 
 ```{r, message=FALSE}
 fig <- get_figure("chelsea_lyn", "6343")

_posts/r/2015-07-30-getting-started.Rmd

@@ -16,22 +16,26 @@ Sys.setenv("plotly_api_key"="q0lz6r5efr")
 
 # Plotly for R
 
-Plotly is R package for creating interactive web-based graphs via [plotly](https://plot.ly/)'s JavaScript graphing library, `plotly.js`.
+Plotly is R package for creating interactive web-based graphs via [plotly.js](http://plot.ly/javascript).
 
 <a href="https://travis-ci.org/ropensci/plotly">
     <img alt="Build Status" style="margin: 0;" src="https://travis-ci.org/ropensci/plotly.png?branch=master">
 </a>
 
 #### Installation
 
-__plotly__ is not (yet) available on CRAN, but you can install it via [devtools](http://cran.r-project.org/web/packages/devtools/):
+__plotly__ is now available on CRAN!
 
 ```r
-install.packages("viridis") # dependency
-install.packages("devtools")
-devtools::install_github("ropensci/plotly")
+install.packages("plotly")
 ```
 
+You can also install the latest development version ([on GitHub](https://github.com/ropensci/plotly)) via [devtools](http://cran.r-project.org/web/packages/devtools/):
+
+```r
+# install.packages("devtools")
+devtools::install_github("ropensci/plotly")
+```
 
 #### Signup
 
@@ -57,7 +61,7 @@ Save these commands in your [.Rprofile](http://www.statmethods.net/interface/cus
 
 #### Special Instructions for Plotly On-Premise Users
 
-Your API key for account on the public cloud will be different than the API key in [Plotly On-Premise](https://plot.ly/product/enterprise/). Visit https://plotly.your-company.com/settings/api/ to find your Plotly On-Premise API key. Remember to replace "your-company.com" with the URL of your Plotly On-Premise server.
+Your API key for account on the public cloud will be different than the API key in [Plotly On-Premise](https://plot.ly/product/enterprise/). Visit <https://plotly.your-company.com/settings/api/> to find your Plotly On-Premise API key. Remember to replace "your-company.com" with the URL of your Plotly On-Premise server.
 
 If your company has a Plotly On-Premise server, change the R API endpoint so that it points to your company's Plotly server instead of Plotly's cloud.
 

_posts/r/2015-07-30-privacy.Rmd

@@ -27,17 +27,11 @@ Sys.setenv("plotly_api_key"="q0lz6r5efr")
 library(plotly)
 
 # public
-plot_ly(x = c(0, 2, 4), y = c(0, 4, 2), filename="r-docs/public-graph")
+p <- plot_ly(x = c(0, 2, 4), y = c(0, 4, 2))
+plotly_POST(p, filename="r-docs/public-graph")
 
 # private
-plot_ly(x = c(0, 2, 4), y = c(0, 4, 2), world_readable = FALSE, filename="r-docs/private-graph")
-
-# another option is to "build" the plot, then tack on these properties
-p <- plot_ly(x = c(0, 2, 4), y = c(0, 4, 2))
-p <- plotly_build(p)
-p$filename <- "r-docs/private-graph"
-p$world_readable <- FALSE
-p
+plotly_POST(p, world_readable = FALSE, filename="r-docs/private-graph")
 ```
 
 Creating public graphs on Plotly is free. To create more than one private graphs, [sign up for a Plotly subscription](https://plot.ly/products/cloud/).

_posts/r/2015-07-30-shiny.Rmd

@@ -16,25 +16,21 @@ display_as: get_request
 ---
 
 ```{r, echo = FALSE, message=FALSE}
-knitr::opts_chunk$set(message = FALSE)
-Sys.setenv("plotly_username"="RPlotBot")
-Sys.setenv("plotly_api_key"="q0lz6r5efr")
+knitr::opts_chunk$set(eval = FALSE)
 ```
 
 # Plotly Graphs in Shiny
 
-Plotly works with Shiny entirely *client-side* either through [plotly.js](https://plot.ly/javascript) or with Plotly's [postMessage API](https://github.com/plotly/postMessage-API). This means that updating the Plotly graphs is *fast* because no external calls are made to a Plotly server. You can export Plotly graphs to your account by clicking the <code>Edit chart</code> link on the bottom right of the chart.
-
-
+As of version 2.0, plotly's R package utilizes the [htmlwidgets](http://www.htmlwidgets.org/) framework. As a result, it's easy to embed plotly graphs in [shiny](http://shiny.rstudio.com/) apps.
 
 <iframe src="https://plotly.shinyapps.io/Movies" width="100%" height=700 scrolling="no" seamless="seamless" style="border: none"></iframe>
 
-
-
 ### Example 1 - Plotly's Native Syntax
 
+The key idea is to pass a plotly object to `renderPlotly()` on the server and place it in the UI with `plotlyOutput()`.
+
 #### `ui.R`
-```{r, message=FALSE}
+```{r}
 
 library(shiny)
 library(plotly)
@@ -51,7 +47,7 @@ shinyUI(fluidPage(
 ```
 
 #### `server.R`
-```{r, message=FALSE}
+```{r}
 library(shiny)
 library(plotly)
 
@@ -77,8 +73,10 @@ shinyServer(function(input, output) {
 
 ### Example 2 - Render `ggplotly`
 
+You can also convert ggplot2 objects to plotly objects with `ggplotly()`
+
 #### `ui.R`
-```{r, message=FALSE}
+```{r}
 library(shiny)
 library(plotly)
 
@@ -94,7 +92,7 @@ shinyUI(fluidPage(
 ```
 
 #### `server.R`
-```{r, message=FALSE}
+```{r}
 library(shiny)
 library(plotly)