garrick
/
frappeCharts


			
							```{r setup, include=FALSE}
knitr::opts_chunk$set(eval = FALSE)
```

## Setup R Package

Create a package for this HTML widget.
We're not going to publish this, so you can call it whatever you want

```{r create-package}
usethis::create_package("frappeCharts")
```

Add a dev script for notes

```{r dev}
dir.create("dev")
file.create("dev/dev.R")
rstudioapi::navigateToFile("dev/dev.R")
```

## Setup npm package

Same process again, but this time for npm.

```bash
npm init

# or

npm init -y
```

Open `package.json` and take a look

```json
{
  "name": "frappecharts",
  "version": "0.0.1",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "MIT"
}
```

From Frappe Charts [docs#installation](https://frappe.io/charts/docs#installation):

```bash
npm install frappe-charts
```

We now have a dependency in `package.json` and there's a `package-lock.json` file.

```json
"dependencies": {
  "frappe-charts": "^1.3.0"
}
```

## Ignore node_modules but add package-lock

There's also a `node_modules/` folder with `frappe-charts/` inside.
Add `node_modules` to `.Rbuildignore` and `.gitignore`.
(BTW, you can and are supposed to commit `package-lock.json`.)

```{r ignore-node-module}
usethis::use_build_ignore("node_modules")
usethis::use_build_ignore("package.json")
usethis::use_build_ignore("package-lock.json")
usethis::use_git_ignore("node_modules")
```

## Scaffold the HTML widget

```{r htmlwidgets-scaffold}
htmlwidgets::scaffoldWidget("frappeChart")
```

This adds files in `inst/htmlwidgets`

```
inst
└── htmlwidgets
    ├── frappeChart.js    #<< R <-> JS code
    └── frappeChart.yaml  #<< list of dependencies
```

and creates a file `R/frappeChart.R` with the functions

- `frappeChart()`
- `frappeChartOutput()` (for shiny)
- `renderFrappeChart()` (for shiny)

## Use `npm` to get our dependencies in the right place

`htmlwidgets` load dependencies in a way that's exactly the same as using a
`<script>` tag in the HTML `<head>`.
Look at the documentation on Frappe Charts and decide which file we should use.

Here's the block from their docs

```
<script src="https://cdn.jsdelivr.net/npm/frappe-charts@1.2.4/dist/frappe-charts.min.iife.js"></script>
<!-- or -->
<script src="https://unpkg.com/frappe-charts@1.2.4/dist/frappe-charts.min.iife.js"></script>
```

We need to get our dependecy into a subfolder of `inst/htmlwidgets`.
Convention is `inst/htmlwidgets/lib/<dependency_name>`.
Rather than creating the directoy and copying over, etc.,
we can have an `npm` build script do this for us.

To avoid issues with mac/windows,
we'll add a dev dependency on [`cpy-cli`](https://github.com/sindresorhus/cpy-cli)

```bash
npm install cpy-cli --save-dev
```

and

```{r create-lib-dir}
dir.create("inst/htmlwidets/lib/frappe-charts", recursive = TRUE)
```

and then edit `package.json` to add copy tasks

```
"scripts": {
  "copy-js": "cpy 'node_modules/frappe-charts/dist/frappe-charts.min.iife*' inst/htmlwidgets/lib/frappe-charts/",
  "build": "npm run copy-js"
}
```

## Create a demo html_document_plain()

```{r create-demo-html}
dir.create("dev/demo")
js4shiny::js4shiny_rmd(path = "dev/demo/demo.Rmd")
```

Use the example in the [Frappe Charts Docs](https://frappe.io/charts/docs).

```{r}
tagList(
  div(id = "chart"),
  htmltools::htmlDependency(
    name = "frappe-charts",
    version = "1.3.0",
    package = "frappeCharts",
    src = "htmlwidgets/lib/frappe-charts",
    script = "frappe-charts.min.iife.js",
    all_files = TRUE
  )
)
```

And copy the JS into a javascript chunk.

`r emo::ji("warning")` The dependencies won't be found until you build/install.

```{r build-install}
devtools::document()
devtools::install()
```

If you get a path not found error

```
Error: path for html_dependency not found: inst/htmlwidgets/lib/frappe-charts
```

it's most likely because

```
src = "inst/htmlwidgets/lib/frappe-charts"
```

## Replace the example data with another data set and example

The first demo mixes chart types and we don't want to do that.
Use the example from
[Basic Chart](https://frappe.io/charts/docs/basic/basic_chart#adding-more-datasets).

```js
const data = {
    labels: ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
    datasets: [
      { name: "R", values: [18, 40, 30, 35, 8, 52, 17, -4] },
      { name: "Python", values: [30, 50, -10, 15, 18, 32, 27, 14] }
    ]
}
```

Then re-create this data in an R chunk:

```{r data-in-r}
data <- list(
  labels = c("Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"),
  datasets = list(
    list(name = "R", values = c(18, 40, 30, 35, 8, 52, 17, -4)),
    list(name = "Python", values = c(30, 50, -10, 15, 18, 32, 27, 14))
  )
)
```

To get the data out of R and make it available in the document,
`htmlwidgets` embeds the data in a `<script type="application/json">...</script>`
element in the page.
Embed the data from the R chunk in a `<script>` tag with an ID 
so that we can find it later.

```{r embed-r-data-in-script}
tags$script(
  id = "data",
  type = "application/json",
  htmlwidgets:::toJSON(data)
)
```

Change to `js4shiny::html_document_js()` so that we can see the `console.log()`
from JavaScript just like R code.
And then find the `<script>` tag and get it's `.textContent`.

```{js find-r-data-script}
let rData = document.getElementById('data')
rData.textContent
```

Use `JSON.parse()` to turn the data into a JS object
and replace the data used in the chart.

```{js find-r-data-script}
let rData = document.getElementById('data')
rData = JSON.parse(rData.textContent)
```

Switch between `data` and `rData` and it should be the same!

Change the values of the data in the R side to be random
so that each re-run gives a new plot.

~~Delete the `data` in the JS side.~~
Comment out the `data` on the JS side (but we'll want to see the structure later).

## Augment data to set options for the chart

Embed `data` in another list `opts` that will carry additional options, 
such as `title`, `type` and `colors`.

Parse the embedded `<script>` and pass the whole object to `frappe.Chart()`.

Change the colors to 

- `#466683` (dark blue)
- `#44bc96` (green)
- `#d33f49` (red)
- `#993d70` (purple)

## Learn about other options for line charts

Read <https://frappe.io/charts/docs/basic/trends_regions>
and add and test additional line options.

Goal: shaded area chart with lines only.

Make the `labels` one week and repeat 4 times.
Generate `runif(7 * 4)` random numbers.

```r
rep(c("Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"), 4)
```

Find and implement an option to reduce the number of labels on the x-axis.

## Turn on dots again and make navigable

```{r}
opts <- list(
  title = "My AwesomeR Chart",
  type = "bar",
  height = 250,
  colors = c("#466683", "#44bc96"),
  data = data,
  axisOptions = list(xIsSeries = TRUE),
  isNavigable = TRUE
)
```

## Add a real data source

Using the `babynames` package, pick two names to compare.

```{r babynames}
library(dplyr)
library(babynames)


data <-
  babynames %>% 
  filter(
    name %in% c("Ruth", "August"),
    year >= 1980
  ) %>% 
  group_by(year, name) %>% 
  summarize(n = sum(n)) %>% 
  ungroup() %>% 
  pivot_wider(year, name, values_from = n)
```

At this point the chart won't work,
but you can use the browser dev console 
to find the right steps to reformat the data into the expected format.

We'll make the **strong** assumption that the tibble in R
should always be formatted with the columns

1. `labels`
2. first data set...
3. second data set...
4. etc.

`repl_example("reformat-r2js-data")`

<details><summary>Answer</summary>

```js
const chartData = {labels: [], datasets: []}

// Get keys of data, assume that first entry is for labels, the rest are data
let labelColumn = Object.keys(x.data)[0]
let columns = Object.keys(x.data).slice(1)

// First column in x.data is the labels
chartData.labels = x.data[labelColumn]

// Create an appropriate object for each column, reformat data and add to chartData
columns.forEach(function(col) {
  chartData.datasets.push({name: col, values: x.data[col]})
})

x.data = chartData
```

</details>


## This is basically what `htmlwidgets` does, just inside a framework

We now have all of the pieces of an `htmlwidget`,
it's just a bit less coordinated.

1. `htmlwidgets` gives us a slightly nicer way of specifying dependencies
   in `inst/htmlwidgets/frappeChart.yaml`. We'll have to update that file.
   
2. When we started we added a `div(id = "chart")`. 
   It would be annoying to have to make sure that each `id` is always unique.
   `htmlwidgets` will add this `div` for us and give each one a unique id.
   We won't have to write any code for this, it just happens.
   
3. We'll write an R function that will take input data and options and format
   it into a list, like the `opts` we've been using.
   Then we hand the data to `htmlwidgets` and it embeds it in a `<script>` tag
   for us.
   It will also find that data automatically and make it available on the JS side.
   
4. Finally, we wrote some code in JavaScript to initialize the chart.
   In the same way, we'll write some code in `inst/htmlwidgets/frappeChart.js`
   which is where we'll reformat the data and options passed from the R world
   by htmlwidgets. We also need to instantiate the chart object. For advanced
   usage, this is also where we'll put code that would let us update the
   widget in place without having to re-render the whole chart.
   
To create the htmlwidget,
we're going to work through each of these pieces
and put them in the right places.

# Make it an htmlwidget

## Declare dependencies

**FILE:** `inst/htmlwidgets/frappeChart.yaml`

Take the `htmltools::htmlDependency()` and 
turn it into `inst/htmlwidgets/frappeChart.yaml`.

```{r}
rstudioapi::navigateToFile("inst/htmlwidgets/frappeChart.yaml")
```

Note: keep `htmlwidgets` in `src`!

## Write the R function

**FILE:** `R/frappeChart.r`

Add appropriate arguments to `frappeChart()`.

* [title](https://frappe.io/charts/docs/reference/configuration#title)
* [type](https://frappe.io/charts/docs/reference/configuration#type)
* [colors](https://frappe.io/charts/docs/reference/configuration#colors)?
* [is_navigable](https://frappe.io/charts/docs/reference/configuration#isnavigable)

Structure the argumets into `x` and pass `...` for the "extra bits".

Rebuild the package,
then create a new R markdown document:
`js4shiny::js4shiny_doc()`.
 
Move the code loading `dplyr`, `tidyr`, `babynames`
and formatting the data.
Then call `frappeCharts::frappeChart()`.

Render and open dev tools in the browser to see that it "works".
Meaning that the data and dependencies are included,
but the chart won't.
Point out the random ID.
Then go back and change it so we can find the element better.

## Write JavaScript binding

**FILE:** `inst/htmlwidgets/frappeChart.js`

The final step is to move the Javascript we wrote before into the js binding.

* Just put in `console.log(x)`, rebuild, rerender
* Verify that this `x` looks the same as our `opts` from before
* Copy all of the JS we wrote to reconfigure the data into the widget
* Use `el` instead of `#chart`
* Rebuild, rerender
* it works!
* Try adding other options

### Writing JavaScript in R

The [tooltips](https://frappe.io/charts/docs/basic/annotations#tooltips)
can be formatted using the `tooltipOptions` property:

```
tooltipOptions: {
    formatTooltipX: d => (d + '').toUpperCase(),
    formatTooltipY: d => d + ' pts',
}
```

To write this in R (add to `widget_demo.R`)

```r
tooltipOptions = list(
  formatTooltipX = htmlwidgets::JS("d => 'Year: ' + d"),
  formatTooltipY = htmlwidgets::JS("d => d + ' babies'")
)
```