WIP intro tutorial vignette

Author: alandipert

vignettes/intro_htmlwidgets.Rmd

@@ -30,7 +30,7 @@ We'll start by preparing our machine for React and reactR widget development. Th
 
 In order to develop a reactR widget, you'll need to install R and optionally RStudio. If you're on Windows, you should also install [Rtools](https://cran.r-project.org/bin/windows/Rtools/).
 
-> For an introduction to general R package concepts, please consult the excellent [R packages](http://r-pkgs.had.co.nz/) online book.
+> For an excellent general introduction to R package concepts, check out the [R packages](http://r-pkgs.had.co.nz/) online book.
 
 In addition, you'll need to install the following JavaScript tools on your machine:
 
@@ -43,8 +43,8 @@ Several packages must be installed to continue. You can install them like this:
 
 > QA Note: The necessary version of reactR is not yet available on CRAN. Please install reactR with `devtools::install_github("react-R/reactR@enhancements")`
 
-```{r}
-install.packages(c("shiny", "usethis", "htmlwidgets", "reactR"))
+```{r eval = FALSE}
+install.packages(c("shiny", "devtools", "usethis", "htmlwidgets", "reactR"))
 ```
 
 ## Scaffolding
@@ -56,9 +56,70 @@ To create a new widget you can call `scaffoldReactWidget` to generate the basic
 
 The following R code will create a package and add the `react-sparklines` dependency:
 
-```{r}
-devtools::create("reactSparklines")
+```{r eval = FALSE}
+# Create a directory 'reactSparklines' and populate it with skeletal package
+# If run within RStudio, this will create a new RStudio session
+usethis::create_package("reactSparklines")
+# Set the current working directory to the one that was created unless a new
+# RStudio session has been launched.
 setwd("reactSparklines")
+# Generate skeletal reactR widget code and supporting build configuration
 reactR::scaffoldReactWidget("reactSparklines", c("react-sparklines", "^1.7.0"))
-devtools::install()
+```
+
+At this point, the `reactSparklines` contains a bare-bones widget in a package called `reactSparklines`.
+
+## Building and installing
+
+### Building the JavaScript
+
+The next step is to navigate to the `reactSparklines` directory in your terminal. Then, run the following commands:
+
+```{shell}
+yarn install
+yarn run webpack --mode=development
+```
+
+* `yarn install` downloads all of the dependencies listed in `package.json` and creates a new file, `yarn.lock`. You should add this file to revision control. It will be updated whenever you change dependencies and run `yarn install`. **You only need to run it after modifying package.json**.
+* `yarn run webpack --mode=development` converts the [ES2015](https://babeljs.io/docs/en/learn/) JavaScript source file at `srcjs/reactSparklines.js` into `inst/htmlwidgets/reactSparklines.js`. The difference between the two is that the one in `inst/` bundles all dependencies. It is also compiled in a dialect of JavaScript that will run on a wider variety of old browsers.
+
+For further documentation on `yarn install`, see the [yarn documentation](https://yarnpkg.com/lang/en/docs/cli/install/).
+
+`yarn run webpack` is not strictly a `yarn` command. In fact, `yarn run` simply delegates to the [webpack](https://webpack.js.org/) program. `development` is one of several [webpack modes](https://webpack.js.org/concepts/#mode). webpack's configuration is generated by `scaffoldReactWidget` in the file `webpack.config.js`.
+
+### Building the package
+
+While the JavaScript has been built, the `reactSparklines` package has not. Now that the JavaScript asset has been created, we can build it:
+
+```{r eval = FALSE}
+devtools::document()
+devtools::install(quick = TRUE)
+```
+
+Alternatively, in RStudio, you can use the keyboard shortcuts `Ctrl+Shift+D` and `Ctrl-Shift-B` to document and build the package. (On macOS, the shortcuts are `Cmd+Shift+D` and `Cmd+Shift+B`)
+
+## Run example
+
+Now that the widget's JavaScript has been compiled and the package has been installed, we can run `app.R` to see the widget in action:
+
+```{r eval = FALSE}
+shiny::runApp()
+```
+
+Alternatively, in RStudio, you can open `app.R` and press `Ctrl-Shift-Enter` (`Cmd-Shift-Enter` on macOS). You should see something like the following appear in the Viewer pane:
+
+```{r echo=FALSE}
+knitr::include_graphics('./widget_app.jpg')
+```
+
+## Implement Functionality
+
+At this point, we've scaffolded a widget and built its JavaScript, but we have not implemented any functionality provided by the `react-sparklines` library.
+
+To expose that functionality through our widget, we must modify the JavaScript in `srcjs/reactSparklines.js`. After scaffolding, it looks like this:
+
+```{js eval=FALSE}
+import { reactWidget } from 'reactR';
+
+reactWidget('reactSparklines', 'output', {});
 ```