bump version; update news/readme; onRender example

Author: cpsievert

DESCRIPTION

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

NEWS

@@ -1,4 +1,10 @@
-3.2.0 -- 8 Mar 2015
+3.2.1 -- 10 Mar 2015
+
+BUGFIX:
+
+* Proper formatting for date tooltips.
+
+3.2.0 -- 10 Mar 2015
 
 CHANGES:
 

README.md

@@ -18,9 +18,11 @@ Or install the latest development version (on GitHub) via devtools:
 devtools::install_github("ropensci/plotly")
 ```
 
-## Introduction
+## Getting Started
 
-If you use [ggplot2](http://cran.r-project.org/package=ggplot2), `ggplotly()` converts your plots to an interactive, web-based version! It also provide sensible tooltips that make it easier to decode values encoded as visual properties in the plot. 
+### ggplot2 converter
+
+If you use [ggplot2](http://cran.r-project.org/package=ggplot2), `ggplotly()` converts your plots to an interactive, web-based version! It also provides sensible tooltips, which can help us decode values encoded as visual properties in the plot. 
 
 ```r
 library(plotly)
@@ -32,25 +34,33 @@ ggplotly(g)
 
 ![https://plot.ly/~cpsievert/9836](http://imgur.com/6G4zv7b)
 
-TODO: mention event stuff
+If you'd like to see how `ggplotly()` does in converting different ggplot2 examples, we host a [plotly version](http://ropensci.github.io/plotly/) of the [official ggplot2 documentation](http://docs.ggplot2.org).
+
+### plotly's custom R interface
 
-__plotly__ also supports certain chart types that ggplot2 doesn't support (such as 3D [surface](https://plot.ly/r/3d-surface-plots/), [point](https://plot.ly/r/3d-scatter-plots/), and [line](https://plot.ly/r/3d-line-plots/) plots). You can easily create these (or any other plotly) charts using the high-level interface. 
+__plotly__ supports some chart types that ggplot2 doesn't (such as 3D [surface](https://plot.ly/r/3d-surface-plots/), [point](https://plot.ly/r/3d-scatter-plots/), and [line](https://plot.ly/r/3d-line-plots/) plots). You can create these (or any other plotly) charts using the high-level interface. 
 
 ```r
 plot_ly(z = volcano, type = "surface")
 ```
 
 ![https://plot.ly/~brnvg/1134](https://plot.ly/~brnvg/1134.png)
 
-The `ggplotly()` function converts a ggplot object to a plotly object, so if you like, you may 'post-process' your ggplot graphs to add custom plotly features, for example:
+For a more detailed overview of this interface, see [here](https://cran.r-project.org/web/packages/plotly/vignettes/intro.html)
 
-```r
-layout(gg, hovermode = "closest")
-```
+### Hooking onto plotly events
+
+[plotly.js](https://github.com/plotly/plotly.js) exposes a number of 'standard' events that work consistently across plot types. It's easy to hook into these events using the `event_data()` function in shiny apps, as these examples demonstrate:
+
+1. [2D events](http://104.131.111.111:3838/plotlyEvents/) ([source](https://github.com/ropensci/plotly/tree/master/inst/examples/plotlyEvents))
+2. [Linked Clicks](http://104.131.111.111:3838/plotlyLinkedClick/) ([source](https://github.com/ropensci/plotly/tree/master/inst/examples/plotlyLinkedClick))
+3. [Linked Brush](http://104.131.111.111:3838/plotlyLinkedBrush/) ([source](https://github.com/ropensci/plotly/tree/master/inst/examples/plotlyLinkedBrush))
+
+
+You can also hook into these events without shiny using `htmlwidgets::onRender()` ([example](https://github.com/ropensci/plotly/tree/master/inst/examples/onRenderHover)). This, however, requires JavaScript knowledge and makes it much harder, if not impossible, to coordinate views between htmlwidgets.
 
 ## Documentation
 
-* [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>
 

inst/examples/onRenderHover/index.Rmd

@@ -0,0 +1,34 @@
+---
+title: "Using plotly with onRender"
+author: "Carson Sievert"
+date: "`r Sys.Date()`"
+output: html_document
+---
+
+```{r, message = FALSE, warning = FALSE}
+library(plotly)
+library(htmlwidgets)
+plot_ly(x = 1:10, y = rnorm(10), marker = list(color = rep("black", 10))) %>% 
+  as.widget() %>% 
+  onRender('
+  function(el, x) { 
+    var graphDiv = document.getElementById(el.id);
+    // color this point red on hover
+    el.on("plotly_hover", function(data) { 
+      var trace = data.points[0].curveNumber;
+      var pt = data.points[0].pointNumber;
+      var marker = x.data[trace].marker;
+      marker.color[pt] = "red";
+      Plotly.restyle(graphDiv, marker, trace)
+    })
+   // color this point black on unhover
+   el.on("plotly_unhover", function(data) { 
+      var trace = data.points[0].curveNumber;
+      var pt = data.points[0].pointNumber;
+      var marker = x.data[trace].marker;
+      marker.color[pt] = "black";
+      Plotly.restyle(graphDiv, marker, trace)
+    })
+  }
+')
+```