discussion/feedback

[timelyportfolio]

This is great. Let me know how I can help. Only 9 for me? on week 26 :)

[hafen]

@timelyportfolio, you're on top of things! I pushed this out earlier today and didn't have time to comment on it.

I had mentioned this approach a while back, here https://github.com/ramnathv/htmlwidgets/issues/63, building on work by @jpmarindiaz, and finally found a few minutes to play around with the idea yesterday. And then of course as with any diversion I got sucked into trying to get something presentable together today :). Hopefully I'm not duplicating effort with anyone else right now, but I had some ideas and wanted to get things to a state where we can discuss. At this point, @timelyportfolio, @ramnathv, @jjallaire, @jcheng5, @jpmarindiaz, your feedback / help would be great.

Take a look here http://hafen.github.io/htmlwidgetsgallery to see what it's like.

The way I've worked it out here, to submit a widget, the idea would be to simply add the appropriate entry in _config.yml and add a screenshot and send a PR. Whoever the gallery curators are can merge and it's done. This should keep work of curators to a minimum while still allowing for quality control.

In no particular order, here are some things that could use some help and feedback. Would be good to deal with many of these before it's ready for the public:

• any comments on the meta data format (see below)
• add any missing htmlwidgets (I don't know how old the yaml file was that I started from but it didn't have, for example, d3heatmap - and @timelyportfolio, I'm sure a good number of yours are missing :), and I just saw, for example, rflot)
• update any missing / incorrect meta data for current widgets - for example I chose the screenshots and descriptions - maybe some of the authors would prefer something else
• optimize images (small as possible while looking good on retina)
• any feedback or work on the layout of each widget's entry would be great
• What are the criteria for a widget to be admitted to the gallery? Installs without errors? Fully documented? Has examples? Adheres to sizing policies? etc. We should determine what this is and publish it in the README, along with the meta data expectations.
• Should we consider populating any of the meta data automatically from things like DESCRIPTION? I'd really like to stick to a plugin-less jekyll format as it is now - the idea of having to run some daily script on some machine to keep things up to date or to always have to merge and run something locally with each PR doesn't sound like a good idea.
• One of the most tricky issues I've been dealing with is how to dynamically get github stars. I tried several things with different badge services, but they always embed in an iframe and you can't access the data inside the iframe. I also tried a way that gets the stars dynamically with javascript using the github api, but you get rate limited on your first view of the page. Any brilliant ideas here would be great. There's got to be some jekyll hack to grab from the github api but probably not without a plugin.

If you have issues with this approach in general, let me know. If this approach is the way to go, here are some questions:

• Is this an htmlwidgets sanctioned site or 3rd party?
• Who maintains it?
• Where will it ultimately reside?

Finally, here are the meta data entries and what they are supposed to contain, as it is now:

• name: the actual name of the R package (required)
• thumbnail: location of the thumbnail (standard is images/ghuser-ghrepo.png) - this should be required but defaults to a blank thumbnail
• url: url to the desired landing page you'd like people to first see for the widget (the widget's home page, a vignette, or as a final resort, if not specified, the widget's github page)
• jslibs: a comma separated list of javascript library names that the widget depends on, with markdown links to the home pages of the libraries
• ghuser: the github user/org where the github repository for the widget resides (required)
• ghrepo: the github repository name where the widget resides (required)
• stars: the number of github stars (need to move away from hard coding this)
• tags: comma separated list (with no spaces) of tags that describe the widget
• cran_url: if on cran, the cran url
• release: this came from the previous yaml - stable/alpha
• examples: url or list of urls of examples (blog posts, gists, vignettes)
• ghauthor: the github handle for the primary author of the widget
• short: a short (preferably one sentence) description of the package that will be displayed in limited space under the widget thumbnail in the gallery - ideally should be more than "An htmlwidget interface to library x" as that is obvious from jslib, etc. - instead, should describe what you can do with the widget using library x
• description: a longer form description

What else or is some of this unneccessary? JS lib authors? Author's full name?

[hafen]

Oh and I should mention that the purpose of this particular site is a gallery of htmlwidget packages, for widget discovery, etc. Perhaps gallery isn't the right term. The idea of a gallery of plots, etc. created with htmlwidgets, that's a cool idea too, but not what I'm doing here.

[jjallaire]

Fantastic!!!!!

Some quick feedback:

1. I think we should make the thumbnail itself be a click target to navigate to the web page for the widget (the link we have now is too subtle) . The extra metadata could be in a "More info" or other chevron style link in the footer.

2. The biggest concern I have about an unfiltered list of every widget we've ever heard of is that many, many widgets represent a few days work and then are abandoned. We need to find a way to distinguish between "production" widgets and ones "in the lab".

Some suggested attributes to look for to promote widgets to higher prominence: on CRAN, actively maintained (recent commits, resolved issues, etc.), pass R CMD check --as-cran, have a website documenting their use, handle dynamic sizing correctly, etc.).

We could probably get away with just two categories ("labs" being for less complete work) whereby a few of us informally agree that if 3 of us give the thumbs up something can go into the "production" bin.

On Sat, Jul 11, 2015 at 1:29 AM, hafen [email protected] wrote:

Oh and I should mention that the purpose of this particular site is a gallery of htmlwidget packages, for widget discovery, etc. Perhaps gallery isn't the right term. The idea of a gallery of plots, etc. created with htmlwidgets, that's a cool idea too, but not what I'm doing here.

— Reply to this email directly or view it on GitHub https://github.com/hafen/htmlwidgetsgallery/issues/1#issuecomment-120575847 .

[jpmarindiaz]

@hafen Awesome!

Some comments:

• Show summary like how many total widgets there are.
• The production/lab comment from @jjallaire is totally necessary that was the idea behind stable/alpha. I think users should be able to filter by this meta info as well in the top search/filters. This "status" should be shown in the box for each widget.
• It would be great to add multiple thumbnails to a widget. Some widgets simply do one thing and others do might do a lot of different graphs or stuff. So looking at different thumbnails might give a broad view on the capabilities of the widget without having to go deep into each js lib documentation.

Great work, happy to be a curator/maintainer

[timelyportfolio]

Perhaps,this registry/gallery for biojs http://biojs.io/ will give us some ideas. @hafen, I believe it automatically pulls in forks/stars from Github.

[ramnathv]

This is looking great @hafen ! I would think about going beyond the gallery by adding the following components:

1. A gallery of plots created using htmlwidgets with reproducible code.
2. A blog that allows widget authors to write about their widgets.
3. A google spreadsheet or similar mechanism where authors can report widgets they are working on.

I have some suggestions on the gallery itself and will post them shortly.

[hafen]

Thanks for the feedback. @jjallaire @jpmarindiaz, good idea about the production / lab categorization. I didn't realize that was the purpose of "status" so that makes sense now. Instead of status: stable/alpha, it should probably be production: true/false or incubator: true/false. The initial view of the page would omit the non-production widgets.

Metrics for giving prominence are great. I wonder if to capture all of these in an automated way we will have to move to something more customized than jekyll updating the page for us with each PR.

@jjallaire, I wonder if we could come up with a quantitative approach for what is required for moving to the production bin - if we can agree on some rules and spell it out, we can avoid having to deal with people thinking we are playing favorites or something.

[ramnathv]

@hafen I think being on CRAN and having a well documented website should be enough to start with. The simpler we keep the tagging guidelines, the easier it is for us to avoid controversies.

[jjallaire]

I agree. On CRAN + dedicated website with enough simple examples to get users started should be the criteria.

On Mon, Jul 13, 2015 at 10:57 AM, Ramnath Vaidyanathan < [email protected]> wrote:

@hafen https://github.com/hafen I think being on CRAN and having a well documented website should be enough to start with. The simpler we keep the tagging guidelines, the easier it is for us to avoid controversies.

— Reply to this email directly or view it on GitHub https://github.com/hafen/htmlwidgetsgallery/issues/1#issuecomment-120957921 .

[hafen]

@ramnathv, adding a gallery of reproducible plots would be a great complementary addition - and would be a good piece of data to display as a link in the widget registry (how many examples the widget has and a link to them in the gallery). This might address @jpmarindiaz's issue with one thumbnail not being sufficient.

To do this, something along the lines of bl.ocks.org would be good. I recall @timelyportfolio has done some stuff with this with htmlwidgets before. We might even be able to use bl.ocks.org itself. In general, publishing a gist of R code along with all the html/js necessary to make the plot would be sufficient. An additional htmlwidgets R function (probably in a different package) to publish to such a gallery would make this very easy and make it easier for the gallery to be quickly populated.

By the way, putting something like this together would probably require an offline build system / server for the gallery.

[hafen]

@ramnathv @jjallaire how many htmlwidgets are currently on CRAN? I'd assume it's not a large number.

[jcheng5]

@hafen Looks like 12 or 13 (reverse imports/suggests): http://cran.r-project.org/web/packages/htmlwidgets/index.html

[timelyportfolio]

Also, I think it would be nice to use some of the htmlwidgets to draw networks of htmlwidgets using meta-information such as JavaScript dependencies, co-authorship, tags that @hafen has included.

@hafen perhaps you are thinking about loryR for multi-image carousels or something similar as the htmwidget thumbnail.

Selfishly I'm not crazy about the CRAN-requirement, but I can't think of any other ways to filter/qualify, I currently view all htmlwidgets as experimental and would say few are production quality in the traditional sense (hopefully I'm not offending anyone).

[ramnathv]

@hafen I had put together a bl.ocks equivalent for rCharts along with a custom publishing function that used a git backend. I could revive that in the htmlwidgets context. It it important to have a custom viewer, since our focus is the R code and not the index.html. I will send a PR to htmlwidgets that wraps up this feature.

[jjallaire]

I think the CRAN requirement is a helpful filter because it indicates commitment (of both time and ongoing support/enhancement) and quality (all the things required to pass R CMD check). We don't have anything else nearly as objective and cut and dried and clearly we need some criteria to avoid htmlwidgets gaining the reputation of being incomplete, buggy, etc.

On Mon, Jul 13, 2015 at 4:31 PM, timelyportfolio [email protected] wrote:

Also, I think it would be nice to use some of the htmlwidgets to draw networks of htmlwidgets using meta-information such as JavaScript dependencies, co-authorship, tags.

@jcheng5 https://github.com/jcheng5 perhaps you are thinking about loryR http://www.buildingwidgets.com/blog/2015/5/14/week-19-loryr-slider for multi-image carousels or something similar as the htmwidget thumbnail.

Selfishly I'm not crazy about the CRAN-requirement, but I can't think of any other ways to filter/qualify, I currently view all htmlwidgets as experimental and would say few are production quality in the traditional sense (hopefully I'm not offending anyone).

— Reply to this email directly or view it on GitHub https://github.com/hafen/htmlwidgetsgallery/issues/1#issuecomment-121047564 .

[ramnathv]

I would agree with @jjallaire. While all htmlwidgets are at some level experimental, passing R CMD CHECK ensures that the package author has spent time taking care of some basic stuff at the very least.

[timelyportfolio]

Yes, R CMD CHECK helps filter out some junk, but it is fairly easy to pass R CMD CHECK and still be junk on the JavaScript side. Very little of the code/effort in many of my htmlwidgets is R. Perhaps, we can come up with some checklist such as this Wiki A Good htmlwidget that could help insure quality.

[ramnathv]

I see your point @klr. R CMD CHECK only ensures that the R code works and has been documented appropriately. It is very well possible for the JS code to be buggy and I think we should be careful on that front.

One way to circumvent this issue is to only tag the gallery with facts like On CRAN, 30+ Stars etc. This way, we will let the end-user be the judge of what widgets they way to use. While we could come up with a complicated checklist of what the widget should satisfy, I think it is very hard for us to systematically and objectively evaluate each widget against it.

Hence, I suggest that we restrict gallery tags to fact based ones and let the user be the judge. In my mind the gallery is mainly for widget discovery and shared code and NOT an endorsement of any of the widgets.

[timelyportfolio]

Much prefer @ramnathv suggestion of facts-based system On Cran rather than arbitrary potentially opinionated labels, such as production, experimental, dead. I believe much of the quality, attentiveness of the developer, functionality, etc. will shine through rather quickly in the gallery.

[hafen]

Fact based sounds good. But then perhaps to avoid htmlwidgets getting a reputation of being sloppy, there could be a default filtering when the page is viewed that shows the widgets with the "best" facts. An example of this is what I did with sorting by github stars by default. This is something I did not want to do, but otherwise some of the less complete widgets showed up at the top which isn't good.

If we go fact based, we could still do QC on the end of whether a package even makes it into the registry. I think at a minimum passing R CMD CHECK should be a requirement there (to make sure documentation is there, etc.).

[jjallaire]

Based on this discussion I think we should do the following:

1. Two categories, CRAN and "Under Development" (or whatever other term seems appropriate)

2. Order both categories by GitHub stars.

3. Whomever is running the registry reserves the right to exclude a widget from either category if it's really shoddy. Obviously this would only occur for situations of really poor quality widgets (whether on CRAN or not).

#3 might be controversial, but is really implicit in any public list of widgets (whoever manages the list can include/exclude whatever they wish). As long as we explain to a widget author why they are excluded I think it can still be a process that is fair to all.

On Mon, Jul 13, 2015 at 5:25 PM, hafen [email protected] wrote:

Fact based sounds good. But then perhaps to avoid htmlwidgets getting a reputation of being sloppy, there could be a default filtering when the page is viewed that shows the widgets with the "best" facts. An example of this is what I did with sorting by github stars by default. This is something I did not want to do, but otherwise some of the less complete widgets showed up at the top which isn't good.

If we go fact based, we could still do QC on the end of whether a package even makes it into the registry. I think at a minimum passing R CMD CHECK should be a requirement there (to make sure documentation is there, etc.).

— Reply to this email directly or view it on GitHub https://github.com/hafen/htmlwidgetsgallery/issues/1#issuecomment-121064413 .

[hafen]

@ramnathv, your custom bl.ocks.org feature would be awesome. If you could point me to the branch for this feature, that would be great. To serve these, do you need a custom web server? Just thinking about how to integrate it with the widget gallery.

[hafen]

@jjallaire I just pushed a few changes that add a "CRAN only" switch that is turned on by default when the page is loaded, and also widgets are sorted by github stars by default as well. That should cover (1) and (2). For (3), it would be great if someone could take a pass right now and propose widgets that should not be there right now.

Also, I know I am missing several widgets. For example, I found pairsD3 and visNetwork on CRAN that aren't in _config.yml. Could someone please go through and add any widgets you think should be there?

I also updated the thumbnail and widget name links to point to the widget home page instead of opening up the detail. Now only clicking on the 3 vertical dots activates the detail view.

[jjallaire]

This is looking fantastic!

I don't have directly experience with rhandsontable or svgPanZoom. Does anyone else?

On Thu, Jul 16, 2015 at 3:13 PM, hafen [email protected] wrote:

@jjallaire https://github.com/jjallaire I just pushed a few changes that add a "CRAN only" switch that is turned on by default when the page is loaded, and also widgets are sorted by github stars by default as well. That should cover (1) and (2). For (3), it would be great if someone could take a pass right now and propose widgets that should not be there right now.

Also, I know I am missing several widgets. For example, I found pairsD3 and visNetwork on CRAN that aren't in _config.yml. Could someone please go through and add any widgets you think should be there?

I also updated the thumbnail and widget name links to point to the widget home page instead of opening up the detail. Now only clicking on the 3 vertical dots activates the detail view.

— Reply to this email directly or view it on GitHub https://github.com/hafen/htmlwidgetsgallery/issues/1#issuecomment-122054655 .

[timelyportfolio]

Yes, @hafen this is really nice. I'll volunteer to add a couple that I know are missing.

@jjallaire I have experience with both.

• svgPanZoom is mine and was accepted to CRAN today. I'll let y'all decide on its merit. Here is the post. For those wondering, I promise not to flood CRAN with all my widgets of varying, but certainly dubious quality. My policy is only if requested. This one svgPanZoom is being considered for use in tmap.
• rhandsontable is in my belief certainly good enough to be on the list. It is very active, and I know there are more than 3 using it in various Shiny projects

[timelyportfolio]

Also, what are thoughts on releasing/publicizing this? I would love for it to get all the attention it deserves plus more.

[hafen]

I'd love to release as soon as possible, but first do the following:

• find a home for it (what is a good domain that everyone likes, etc.)
• get feedback on how each individual widget is displayed - anything to tweak here?
• finalize widget meta data - is it good as it stands?
• figure out how to get github stars dynamically
• make sure it's okay on mobile

[timelyportfolio]

Would it not just go on http://htmlwidgets.org?

[timelyportfolio]

@hafen, would this link http://www.carsonshold.com/2014/05/github-metadata-with-jekyll-and-javascript/ help with the dynamic Github stars?

[hafen]

I'm all for putting it on htmlwidgets.org. Is that served with github pages? Or would you just do some DNS stuff to point htmlwidgets.org/gallery (or should we be using registry?). Some style work with the header would have to be done to match. Wherever it goes, I'm completely happy with the idea of it being owned by someone else (e.g. the htmlwidgets team) and I would just contribute with PRs.