diff --git a/R/format_data.R b/R/format_data.R index 9c5b510942..1ff531b533 100644 --- a/R/format_data.R +++ b/R/format_data.R @@ -11135,13 +11135,16 @@ fmt_country <- function( #' #' @param fill_color *Color of the icon fill* #' -#' `scalar` // *default:* `NULL` (`optional`) +#' `scalar|vector` // *default:* `NULL` (`optional`) #' #' The fill color of the icon can be set with `fill_color`; providing a single #' color here will change the color of the fill but not of the icon's 'stroke' -#' or outline (use `stroke_color` to modify that). If not provided then the -#' default value of `"currentColor"` is applied so that the fill matches the -#' color of the parent HTML element's color attribute. +#' or outline (use `stroke_color` to modify that). A named vector or named +#' list comprising the icon names with corresponding fill colors can +#' alternatively be used here (e.g., +#' `list("circle-check" = "green", "circle-xmark" = "red"`). If nothing is +#' provided then the default value of `"currentColor"` is applied so that the +#' fill matches the color of the parent HTML element's color attribute. #' #' @param fill_alpha *Transparency value for icon fill* #' @@ -11416,6 +11419,45 @@ fmt_country <- function( #' `r man_get_image_tag(file = "man_fmt_icon_4.png")` #' }} #' +#' A fairly common thing to do with icons in tables is to indicate whether +#' a quantity is either higher or lower than another. Up and down arrow symbols +#' can serve as good visual indicators for this purpose. We can make use of the +#' `"up-arrow"` and `"down-arrow"` icons here. The `fmt_icon()` function has to +#' find those text values in cells to generate the icons, so, lets generate the +#' text within a new column via the [cols_add()] function (an expression is used +#' therein to generate the correct text given the `close` and `open` values). +#' Following that, `fmt_icon()` is used and its `fill_color` argument is +#' provided with a named vector that indicates which color should be used for +#' each icon. +#' +#' ```r +#' sp500 |> +#' dplyr::slice_head(n = 10) |> +#' dplyr::select(date, open, close) |> +#' dplyr::arrange(-dplyr::row_number()) |> +#' gt(rowname_col = "date") |> +#' cols_add(week = date, .after = date) |> +#' cols_add(dir = ifelse(close > open, "arrow-up", "arrow-down")) |> +#' cols_merge(columns = c(date, week), pattern = "{1} ({2})") |> +#' fmt_date(columns = date, date_style = "m_day_year") |> +#' fmt_datetime(columns = week, format = "w", pattern = "W{x}") |> +#' fmt_currency() |> +#' fmt_icon( +#' columns = dir, +#' fill_color = c("arrow-up" = "green", "arrow-down" = "red") +#' ) |> +#' cols_label( +#' open = "Opening Value", +#' close = "Closing Value", +#' dir = "" +#' ) |> +#' opt_stylize(style = 1, color = "gray") +#' ``` +#' +#' \if{html}{\out{ +#' `r man_get_image_tag(file = "man_fmt_icon_5.png")` +#' }} +#' #' @family data formatting functions #' @section Function ID: #' 3-24 @@ -11567,6 +11609,8 @@ fmt_icon <- function( x_str_non_missing <- x[!is.na(x)] + fill_color_named <- rlang::is_named(fill_color) + x_str_non_missing <- vapply( seq_along(x_str_non_missing), @@ -11593,11 +11637,22 @@ fmt_icon <- function( for (y in seq_along(icons)) { + icon_name_i <- icons[y] + + if ( + fill_color_named && + rlang::has_name(fill_color, name = icon_name_i) + ) { + fill_color_i <- fill_color[[icon_name_i]] + } else { + fill_color_i <- fill_color + } + out_y <- as.character( fontawesome::fa( name = icons[y], - fill = fill_color, + fill = fill_color_i, fill_opacity = fill_alpha, stroke = stroke_color, stroke_width = stroke_width, diff --git a/images/man_fmt_icon_5.png b/images/man_fmt_icon_5.png new file mode 100644 index 0000000000..823ace1e6c Binary files /dev/null and b/images/man_fmt_icon_5.png differ diff --git a/man/fmt_icon.Rd b/man/fmt_icon.Rd index fd792e0560..d8b3a47a5e 100644 --- a/man/fmt_icon.Rd +++ b/man/fmt_icon.Rd @@ -91,13 +91,16 @@ decimal value between \code{0} and \code{1}.} \item{fill_color}{\emph{Color of the icon fill} -\verb{scalar} // \emph{default:} \code{NULL} (\code{optional}) +\verb{scalar|vector} // \emph{default:} \code{NULL} (\code{optional}) The fill color of the icon can be set with \code{fill_color}; providing a single color here will change the color of the fill but not of the icon's 'stroke' -or outline (use \code{stroke_color} to modify that). If not provided then the -default value of \code{"currentColor"} is applied so that the fill matches the -color of the parent HTML element's color attribute.} +or outline (use \code{stroke_color} to modify that). A named vector or named +list comprising the icon names with corresponding fill colors can +alternatively be used here (e.g., +\verb{list("circle-check" = "green", "circle-xmark" = "red"}). If nothing is +provided then the default value of \code{"currentColor"} is applied so that the +fill matches the color of the parent HTML element's color attribute.} \item{fill_alpha}{\emph{Transparency value for icon fill} @@ -388,6 +391,44 @@ scores. \if{html}{\out{ This image of a table was generated from the fourth code example in the `fmt_icon()` help file. }} + +A fairly common thing to do with icons in tables is to indicate whether +a quantity is either higher or lower than another. Up and down arrow symbols +can serve as good visual indicators for this purpose. We can make use of the +\code{"up-arrow"} and \code{"down-arrow"} icons here. The \code{fmt_icon()} function has to +find those text values in cells to generate the icons, so, lets generate the +text within a new column via the \code{\link[=cols_add]{cols_add()}} function (an expression is used +therein to generate the correct text given the \code{close} and \code{open} values). +Following that, \code{fmt_icon()} is used and its \code{fill_color} argument is +provided with a named vector that indicates which color should be used for +each icon. + +\if{html}{\out{
}}\preformatted{sp500 |> + dplyr::slice_head(n = 10) |> + dplyr::select(date, open, close) |> + dplyr::arrange(-dplyr::row_number()) |> + gt(rowname_col = "date") |> + cols_add(week = date, .after = date) |> + cols_add(dir = ifelse(close > open, "arrow-up", "arrow-down")) |> + cols_merge(columns = c(date, week), pattern = "\{1\} (\{2\})") |> + fmt_date(columns = date, date_style = "m_day_year") |> + fmt_datetime(columns = week, format = "w", pattern = "W\{x\}") |> + fmt_currency() |> + fmt_icon( + columns = dir, + fill_color = c("arrow-up" = "green", "arrow-down" = "red") + ) |> + cols_label( + open = "Opening Value", + close = "Closing Value", + dir = "" + ) |> + opt_stylize(style = 1, color = "gray") +}\if{html}{\out{
}} + +\if{html}{\out{ +This image of a table was generated from the fifth code example in the `fmt_icon()` help file. +}} } \section{Function ID}{