cells_column_spanners: Location helper for targeting the column spanners

Description

cells_column_spanners() is used to target the cells that contain the table column spanners. This is useful when applying a footnote with tab_footnote() or adding custom style with tab_style(). The function is expressly used in each of those functions' locations argument. The 'column_spanners' location is generated by one or more uses of tab_spanner() or tab_spanner_delim().

Usage

cells_column_spanners(spanners = everything(), levels = NULL)

Value

A list object with the classes cells_column_spanners and location_cells.

Arguments

spanners

Specification of spanner IDs

<spanner-targeting expression> // default: everything()

The spanners to which targeting operations are constrained. Can either be a series of spanner ID values provided in c() or a select helper function (e.g. starts_with(), ends_with(), contains(), matches(), num_range(), and everything()).

levels

*Specification of the spanner levels *

scalar|vector<numerical> // default: NULL

The existing spanner levels (1, 2, ...) to which targeting operations are constrained. Use NULL to refer to all existing levels.

Examples

Use the exibble dataset to create a gt table. We'll add a spanner column label over three columns (date, time, and datetime) with tab_spanner(). The spanner column label can be styled with tab_style() by using the cells_column_spanners() function in locations. In this example, we are making the text of the column spanner label appear as bold.

exibble |>
  dplyr::select(-fctr, -currency, -group) |>
  gt(rowname_col = "row") |>
  tab_spanner(
    label = "dates and times",
    columns = c(date, time, datetime),
    id = "dt"
  ) |>
  tab_style(
    style = cell_text(weight = "bold"),
    locations = cells_column_spanners(spanners = "dt")
  )

This image of a table was generated from the first code example in the `cells_column_spanners()` help file.

Use the exibble dataset to create a gt table. We'll add two spanners for the column combinations of (num, char) and time related columns (time and datetime). Furthermore we add another level of spanners with a column label over all date- and time related columns (date, time, and datetime). We want all spanner labels with "time" in their name to be bold. Additionally we want the text to be red of the spanner that is both time- related and on level 1.

exibble |>
  dplyr::select(-fctr, -currency, -group) |>
  gt(rowname_col = "row") |>
  tab_spanner(
    label = "time related cols",
    columns = c(datetime, time)
  ) |>
  tab_spanner(
    label = "num and char",
    columns = c(num, char)
  ) |>
  tab_spanner(
    label = "date and time cols",
    columns = c(date, time, datetime)
  ) |>
  tab_style(
    style = cell_text(weight = "bold"),
    locations = cells_column_spanners(spanners = tidyselect::contains("time"))
  ) |>
  tab_style(
    style = cell_text(color = "red"),
    locations = cells_column_spanners(
      spanners = tidyselect::contains("time"),
      levels = 1
    )
  )

This image of a table was generated from the second code example in the `cells_column_spanners()` help file.

Function ID

8-14

Function Introduced

v0.2.0.5 (March 31, 2020)