widgetcard/vignettes/creating-interactive-player-cards.Rmd

---
title: "Creating Interactive Twitter Player Cards"
author: "Bob Rudis"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Creating Interactive Twitter Player Cards}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "##"
)
```

Twitter supports [player cards](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/player-card.html) which means you can use R-generated `htmlwidgets` as fully 
interactrive pieces in Tweets. You don't absolutely need this package to make these cards, but
hopefully this removes much of the friction. Here's an example workflow.

First, make a plot!

```{r fake-libs, eval=FALSE}
library(ssh)
library(plotly)
library(ggplot2)
library(widgetcard)

ggplot(mtcars, aes(wt, mpg)) +
  geom_point() -> gg

gg
```
```{r real-libs, echo=FALSE, eval=TRUE, message=FALSE, warning=FALSE}
library(plotly)
library(ggplot2)
library(widgetcard)

ggplot(mtcars, aes(wt, mpg)) +
  geom_point() -> gg

gg
```

Now, we create a local preview image for the plot we just made since we need one for the card:

```{r preview, eval=FALSE}
preview <- gg_preview(gg)
```

NOTE that you can use _any_ image you want. This streamlines the process for plotly plots
created from ggplot2 plots.

Now, we convert our ggplot2 object to a plotly object and create the Twitter Player card. 
Note that Twitter really doesn't like standalone widgets being used as Twitter Player card
links due to their heavyweight size. Therefore, `card_widget()` creats a non-standalone
widget but bundles everything up into a single directory and deployable archive.

```{r card-it, eval=FALSE}
ggplotly(gg) %>% 
  card_widget(
    output_dir = "~/widgets/tc",
    name_prefix = "tc",
    preview_img = preview,
    html_title = "A way better title",
    card_twitter_handle = "@hrbrmstr",
    card_title = "Basic ggplot2 example",
    card_description = "This is a sample caRd demonstrating card_widget()",
    card_image_url_prefix = "https://rud.is/vis/tc/",
    card_player_url_prefix = "https://rud.is/vis/tc/",
    card_player_width = 480,
    card_player_height = 480
  ) -> arch_fil
```

Here's what the resulting directory structure looks like:

```
tc
├── tc.html
├── tc.png
└── tc_files
    ├── crosstalk-1.0.0
    │   ├── css
    │   │   └── crosstalk.css
    │   └── js
    │       ├── crosstalk.js
    │       ├── crosstalk.js.map
    │       ├── crosstalk.min.js
    │       └── crosstalk.min.js.map
    ├── htmlwidgets-1.3
    │   └── htmlwidgets.js
    ├── jquery-1.11.3
    │   ├── jquery-AUTHORS.txt
    │   ├── jquery.js
    │   ├── jquery.min.js
    │   └── jquery.min.map
    ├── plotly-binding-4.8.0
    │   └── plotly.js
    ├── plotly-htmlwidgets-css-1.39.2
    │   └── plotly-htmlwidgets.css
    ├── plotly-main-1.39.2
    │   └── plotly-latest.min.js
    ├── pymjs-1.3.2
    │   ├── pym.v1.js
    │   └── pym.v1.min.js
    └── typedarray-0.1
        └── typedarray.min.js
```

(There's also a `tc.tgz` at the same level as the `tc` directory.)

The widget is `iframe`d using `widgetframe` and then saved out using `htmlwidgets::saveWidget()`.

Now, for deploying this to a web server, one could use a method like this to `scp` the
deployable archive:

```{r deploy, eval=FALSE}
sess <- ssh_connect(Sys.getenv("SSH_HOST"))

invisible(scp_upload(
  sess, files = arch_fil, Sys.getenv("REMOTE_VIS_DIR"), verbose = FALSE
))

ssh_exec_wait(
  sess,
  command = c(
    sprintf("cd %s", Sys.getenv("REMOTE_VIS_DIR")),
    sprintf("tar -xzf %s", basename(arch_fil))
  )
)
```

Alternatively, you can use other workflows to transfer and expand the archive _or_ copy 
output to your static blog host.

Don't forget to use Twitter's [validator](https://cards-dev.twitter.com/validator) to make sure
your interactive player widget works before posting it in a Tweet!