Helper function show_icons() to get valid icon()s

[MichaelChirico]

Related: #2263

Currently, the documentation simply refers to the FontAwesome site:

Icons are drawn from the Font Awesome Free (currently icons from the v5.3.1 set are supported with the v4 naming convention)...

and

For lists of available icons, see http://fontawesome.io/icons/ ...

Unfortunately, the website only lists icons in the current version (5.8.1 as of this writing) and there doesn't appear to be any easy way to find out which icons were available for a specific version (e.g. shiny's current supported version of 5.3.1).

That means the process of looking up icons to use is currently quite onerous -- either guess & check by running your app, or look on the website and check the version nested in a given icon's page (e.g. I learned pepper-hot is apparently only available since 5.7.0 here)

It would be ideal if FontAwesome would offer an easier UX for this. But shiny could include a helper-function like show_icons; a rinky-dink version I cooked up is:

library(magrittr)
icons = file.path('www', 'shared', 'fontawesome', 'css', 'all.min.css') %>% 
  system.file(package = 'shiny') %>%
  readLines(warn = FALSE) %>% tail(1L) %>%
  strsplit('.', fixed = TRUE) %>% unlist %>%
  gsub(':before\\{content:".+"\\}', '', . ) %>% 
  grep('fa-', ., fixed = TRUE, value = TRUE) %>% 
  grep('[{,]', ., value = TRUE, invert = TRUE) %>% 
  gsub('^fa-', '', .)

I'm sure it doesn't capture everything correctly but I think it's close.

I don't know what the glyphicon version would look like or if it's necessary.

PS this phrase is quite confusing for a new user (me) who has no idea about the whole version shift situation, and is given no further context (e.g. in Details)

currently icons from the v5.3.1 set are supported with the v4 naming convention

PPS the glyphicon link in the documentation isn't correct (redirects to the top of the page and the HTML tag is apparently missing):

http://getbootstrap.com/components/#glyphicons

[alandipert]

@MichaelChirico this is a great point and I agree with you that the documentation could be improved.

I think the link we should consider including in the documentation is this one: https://fontawesome.com/v5.3.1/icons?d=gallery&m=free

As far as I can tell, that's the best way to see all the icons in 5.3.1 (available up to that version, not just added/updated in 5.3.1) but I might be interpreting it wrong.

Re: "the v4 naming convention", I think we can probably remove that note from the docs. It's not really relevant to the user, since the naming convention from the user's perspective has not changed. As far as I know we don't have plans to adopt the new v5 prefixes as part of our API.

I like the idea of a show_icons function but I think it would be much better if we didn't scrape CSS to power it. Perhaps we can figure out where the data is coming from that powers the search function on their website, and then use that as our canonical data.

So, I think we'd definitely consider a PR with link fixes and that removed the note about v4 prefixes, if you are so inclined.

If you have the time/interest in figuring out the best way to obtain icon data that could power a show_icons function, that would be a fantastic contribution also.

Thanks again for raising these issues, and in advance for any further contributions you have time for 👍

[MichaelChirico]

agree 100% about not using my hackish function officially, heavens knowns what kind of code sclerosis that could engender down the line -- but I couldn't figure out any better automated way to get it.

nice find on the direct link to v5.3.1 icons, I swear I tried that URL and was rebuffed.

will ponder a bit on implementation and follow up if I land on anything production-worthy. already the direct link to the list would be a big improvement.

[MichaelChirico]

@alandipert so, there's this file:

https://github.com/FortAwesome/Font-Awesome/blob/master/metadata/icons.yml

We could work around the following manual-ish implementation:

1. If upgrading Font Awesome dependency in shiny, go to the Releases page on their GH
2. Checkout the correct tag with a local clone of the FortAwesome/Font-Awesome repo (e.g., for 5.3.1, git checkout tags/5.3.1 will get you here)

Once here, we can use the following R script:

library(yaml)
library(magrittr)
list.files('.', recursive = TRUE, pattern = 'icons.yml', full.names = TRUE) %>%
  read_yaml %>% names %>% paste(collapse = '", "') %>% sprintf('c("%s")', .) %>% cat

Then we can copy/paste that into our function:

show_icons = function() {
  return(_output_from_above_command_)
}

Not completely automated but it's pretty straightforward.

I'm not 100% sure (1) it captures all the icons and (2) it's possible to distinguish free & pro icons

[alandipert]

@MichaelChirico thank you for digging into this, it's really helpful to know that there is a canonical source of data.

I discussed the situation with the team this morning, and we concluded that ultimately it's best to direct people to FontAwesome to select icons instead of building out our own infrastructure for helping people select them. First, we want to help FontAwesome by directing people to their site, which (once you have the right link!) is great. Second, we want to avoid introducing additional (inherently brittle, even when dealing with yaml) tooling in order to stay in sync with them.

While we decline the idea of adding show_icons(), the documentation could definitely use improvement. The FontAwesome link could be added and the confusing bit about "v4 syntax" could be removed.

If you're interested in making a PR for that, one would be most welcome. You'll just need to make sure you've submitted a contributor agreement.

Otherwise, it's something we'll get to.

Thanks again for your exploratory efforts, and sorry we have to turn down your idea.

[MichaelChirico]

@alandipert thanks for the heartfelt message, you're too kind. The reasoning makes sense, I don't take it personally. Fully agree; 85% of the value-add here is in fact from providing the direct link.

[MichaelChirico]

So I was on my way to filing the documentation PR when I found this file:

https://github.com/rstudio/shiny/blob/master/R/font-awesome.R

Not sure what to make of it. Looks like it was added by @wch and is close to what my suggestion above would have led to...

The place it's used in the code is here, but I don't quite understand what that section of code is doing:

  if (!is.null(name)) {
    prefix_class <- prefix
    if (prefix_class == "fa" && name %in% font_awesome_brands) {
      prefix_class <- "fab"
    }
    iconClass <- paste0(prefix_class, " ", prefix, "-", name)
  }

At a glance it looks like font_awesome_brands is a subset of all of the valid font-awesome tags?

But if that's being maintained, the marginal burden of maintaining a full set seems smaller?

[sanjmeh]

Request update after Consult team.

[sanjmeh]

So I was on my way to filing the documentation PR when I found this file:

https://github.com/rstudio/shiny/blob/master/R/font-awesome.R

the above link is broken now!

[philibe]

@sanjmeh

If I follow the changelog file:

• https://github.com/rstudio/shiny/blob/v1.7.0/NEWS.md
  • "icon(lib="fontawesome") is now powered by the {fontawesome} package, which will make it easier to use the latest FA icons in the future (by updating the {fontawesome} package). (Modify icon() function to call fontawesome::fa_i() for equivalent functionality #3302)"
• d65ad5e, 397aa8b
  • font-awesome.R is removed

PS: I am a simple developer.

[philibe]

@sanjmeh

And #3502 "Move master branch to main"

[sanjmeh]

d65ad5e, 397aa8b

• font-awesome.R is removed

Oh I see. Missed that. Thanks and best wishes.

[cpsievert]

Font awesome specific logic has been moved to https://github.com/rstudio/fontawesome. Please open issue(s) for Font Awesome there.

PS. As commented in #2399 (comment), I don't think we'll implement a show_icons(), but there is a fontawesome::fa_metadata() that'll give you various info on all the icons