A Good htmlwidget

Checklist For A Good htmlwidget

Please note these are my opinions and not necessarily those of the htmlwidget team. Over the last couple months, I have developed some strong opinions on what makes a good htmlwidget, and thought they might be worth sharing as a short checklist (there are of course exceptions).

1. htmlwidgets are designed to be R packages, so what makes a good package also makes a good htmlwidget. Things like filling in all the blanks with thorough documentation, multiple examples, and thoughtful error checking all help distinguish your widget. Here are some resources by far more qualified people than me.
   Hadley Wickham http://r-pkgs.had.co.nz/
   Hilary Parker http://hilaryparker.com/2014/04/29/writing-an-r-package-from-scratch/
   Jeff Leek https://github.com/jtleek/rpackages
   

2. htmlwidgets should work in all contexts. This means that htmlwidgets will work in the most basic R console, in RStudio viewer (unless too big), in the browser, in Shiny as output, in R markdown, and be composable or work smoothly with other widgets and tags from htmltools. Yes, this requires a little extra work and testing, but a robust and consistent experience will make your htmlwidget user very happy and let your widget shine all over.

3. htmlwidgets should enhance the underlying library. I learned very early in my marriage that bad/lazy wrapping can ruin a really good gift, and good wrapping can improve a lousy gift. Similarly, htmlwidgets should serve as good wrapping paper for these amazing Javascript libraries. To be a good wrapper, htmlwidgets should allow R users with absolutely no JS knowledge to easily use them and incorporate them in their typical R workflow. htmlwidget examples and documentation should use R data not JSON from the web. If at all possible, htmlwidgets should offer parallels from widely used R packages, such as ggplot2/lattice for plotting. Ideally, for my own personal workflow, htmlwidgets will work well with both pipeR and magrittr. And above all as tempting as it is please do not do this with your widget mybadwidget <- function(x,...){ x = list(x,...) }. Please provide methods and parameters for all the behaviors that you would like to access from the Javascript library. ... is very, very hard to document, and leaves a R user no clues as to what can be accomplished.

4. htmlwidgets profusely attribute and praise the team that developed the underlying Javascript library. Also, htmlwidget authors do not impose on the JS library author or community to help them with their widget or overcome their JS ignorance. These JS libraries were not designed with widgets in mind nor should they be, so the widget author should be responsible for figuring out ways to hack these into this unique situation. However, extensive testing in different environments can help reveal issues and bugs with the JS libraries. Reporting these nicely, thoroughly, and reproducibly in JS can be a very helpful way to give back to the JS community. Even better, htmlwidget authors can improve, extend, or enhance the behavior, interactivity, etc. of a Javascript library and be a really good citizen of the open source world.

5. htmlwidget authors look for an existing htmlwidget wrapper of the library in question and seek to collaborate before developing their own.

Of course, feel free to break all of these. Please go make some widgets or go make one better.