rhtmlTemplate

An R HTMLWidget project template.

Installation in R

1. library(devtools)
2. install_github('Displayr/rhtmlTemplate', auth_token='????????????????????')

Simplest Example to verify installation:

rhtmlTemplate::template()

Local Installation to Develop/Contribute

Prerequisites - For help installing prerequisites see the Prequisite Installation Help section below

1. nodejs >= 6.0
2. python 2.7 - one of the nodejs libraries needs python during the installation process

Installing the rhtmlTemplate code

1. On windows open git shell (or install it first). On OSX open terminal
   1. Tim note : Type enter when prompted for a passphrase when opening git shell
2. Change directory to the place where you put git projects
   1. Tim note : Do not use a Dropbox synced directory. There will be 1000's of files created by npm install and your computer will catch fire
3. type git clone [email protected]:Displayr/rhtmlTemplate.git ENTER
4. type cd rhtmlTemplate ENTER
5. type npm install ENTER
   1. npm install is noisy and will print several warnings about UNMET and DEPRECATED. Ignore these and only make note of errors. If it fails, try running it again.
6. type gulp serve ENTER
   1. If gulp serve does not work try ./node_modules/.bin/gulp serve. To correct this and to make your nodejs life easier you should add ./node_modules/.bin to your PATH. Consult the Internet for instructions on how to do so on your OS of choice.

If this worked, then the gulp serve command opened your browser and you are looking at http://localhost:9000. You should see a page listing a bunch of links to examples, each example shows the simple 4 square widget template. These examples are defined in the internal www content directory.

Choose an example or add another example to the content area by following the instructions here. When changes to any file in ./theSrc are saved, the browser will automatically reload.

Prerequisite Installation Help

Install nodejs on OSX

1. Install brew by following instructions here : http://brew.sh/
2. Install nvm (node version manager) by running brew install nvm
3. Install node by running nvm install 6.1.0 on the terminal

Install nodejs on Windows

1. Setup nodist. https://github.com/marcelklehr/nodist and find the link to the official installer.
2. Open the command prompt. Type: nodist v6.1.0
3. Type node -v and verify the version is correct

Python on OSX - it should come installed. If not

1. Install brew (if not done already) by following instructions here : http://brew.sh/
2. Install python by running brew install python on the terminal - make sure you get 2.7

Python on Windows

1. Download version 2.7 from https://www.python.org/downloads/

Developing and Contributing

See docs on the htmlwidget_build_system to understand what gulp tasks are available and to understand the role of each file in the project. Here are a few important notes (both detailed in the htmlwidget_build_system docs) you must keep in mind:

1. The last thing you do before committing is run gulp build to ensure all the autogenerated files are up to date.
2. (With some exceptions) ONLY EDIT THINGS IN these directories: theSrc, and docs !! Many of the other files are auto generated based on the contents of theSrc. As an example, if you edit R/rhtmlTemplate.R and then run gulp build your changes will be DELETED FOREVER!, because R/rhtmlTemplate.R is just a copy of theSrc/R/htmlwidget.R. See htmlwidget_build_system for more details.

Contributing to rhtmlTemplate

1. Do not work in master, as the master branch of rhtmlTemplate is used to verify the R server build process.
2. Create a branch, make some changes, add test for your changes, update the docs if necessary, push your branch, and create a pull request on github.

Docs

Doc manifest

• htmlwidget build system - gulp task descriptions and file role breakdown
• extending the template - instructions on using the template to create a new htmlwidget project
• how the code works - a walkthrough of how the rhtmlTemplate and its successors actually work
• visual regression testing and the internal web server - a walkthrough of the internal web server and how to run and create visual regression tests

R docs

The R file has inline documentation that is compiled into an Rd file. This documentation can be accessed from R using the following sequence:

install_github("Displayr/rhtmlTemplate")
library(rhtmlTemplate)
help(template)

R Examples

There are example widget use in R in the examples directory, which is autogenerated based on the content in the internal web content directory.

Next Steps / TODO / Known Issues

Time permitting here is what I would do next to the template next:

• (Known Issue) The build steps makeDocs, and makeExample dont appear to work on Windows. This is likely a path issue.
• Produce a script that automates as much as possible of the extending the template steps, including creating the git repo.