Skip to contents

Define Conditional Row Actions for Tables

Source: R/rowstyle_actions.R
compute_cols.Rd

Declares a set of styling, merging, and row insertion actions to be applied to rows matching a condition. Actions are captured as unevaluated expressions and evaluated later during create_report(). Supports complex conditions using data columns and helper functions.

Usage

compute_cols(spec, cond, ...)

Arguments

spec

A TFL_spec object (must have docType = "Table")

cond

An unquoted logical expression to be evaluated in the data environment. Can reference:

  • Data columns directly (e.g., col1 > 10, Parameter == "Pulse")

  • Condition helpers evaluated over the data: firstOf(), lastOf(), firstRow(), lastRow(), rowNumber(), everyNth(), firstOfBlock() (see Details)

Must return a logical vector of length equal to nrow(data), or a single TRUE/FALSE scalar (applies the actions to all rows / no rows).

...

Action function calls: c_style(), c_merge(), c_addrow(), c_glue(), c_clear(), c_pageBreak(). Multiple actions allowed, including duplicates. Actions are captured unevaluated and execute in arrival order: argument order within one compute_cols() call, then call order across piped calls.

Value

Modified spec object with appended action metadata in spec$.metadata$compute_cols. Invisibly returns the updated spec to enable piping workflows.

Details

Condition helpers (available only inside cond; they operate on the raw data frame):

  • firstOf(col) / lastOf(col): TRUE at the first/last row of each RUN of equal values (run-length semantics). The input must be sorted so that each logical group is contiguous, otherwise a value that re-appears later counts as a new run. Multiple columns (firstOf(col1, col2)) test combined run boundaries.

  • firstRow() / lastRow(): single-row markers at absolute positions.

  • rowNumber(): integer row index, usable in arbitrary expressions.

  • everyNth(n): TRUE every n-th row starting from row 1.

  • firstOfBlock(col, n = 1, offset = 0): TRUE on the first row of every n-th run-block of col (after the first block).

Execution Timeline:

  1. compute_cols() captures condition and actions (no evaluation)

  2. Appends to spec$.metadata$compute_cols list

  3. During create_report(), conditions are evaluated and matched rows identified

  4. Actions are applied to matching rows (styling, merging, row insertion)

  5. StyleRows are serialized to JSON

Constraints:

  • Only allowed for docType = "Table"

  • Multiple compute_cols() calls accumulate on the same spec

  • Actions on the same row from different compute_cols() blocks are aggregated

  • Conditions must be deterministic (no NA values allowed)

Action Functions (used inside compute_cols()):

  • c_style(cols, styleRef): Apply style(s) to columns in matching rows

  • c_merge(cols, styleRef = NULL): Merge adjacent columns in matching rows

  • c_addrow(pos, value_from = NULL, styleRef = NULL): Insert row above/below matching rows

  • c_pageBreak(): Insert a page break at the matching row (no args)

  • c_glue(cols, position, glue_col = NULL, text = NULL, separator = NULL): Concatenate a data column value or literal text to matching cell text

  • c_clear(cols): Clear the display text of matching cells (render as blank)

See also

c_style(), c_merge(), c_addrow() for action functions used within compute_cols()

Examples

  spec <- create_table(mtcars)
  spec <- add_style(spec, id = "bold", s_font(bold = TRUE))
  spec <- add_style(spec, id = "red", s_font(color = "red"))
  spec <- add_style(spec, id = "highlight", s_table_style(background_color = "#FFFF00"))

  # Style columns in rows where cyl starts a new run (sorted input!)
  spec <- compute_cols(spec, firstOf(cyl), c_style(c(mpg, hp), styleRef = "bold"))

  # Style and merge columns in rows with high hp
  spec <- compute_cols(spec, hp > 200,
    c_style(hp, styleRef = "red"),
    c_merge(c(wt, qsec), styleRef = "highlight")
  )

  # Empty separator row above each new cyl run
  spec <- compute_cols(spec, firstOf(cyl), c_addrow(pos = "above"))

  # Row with content copied from a column (bare symbol or quoted name)
  spec <- compute_cols(spec, lastOf(cyl), c_addrow(pos = "below", value_from = mpg))

  # Page break before each new cyl run; scalar condition = all rows
  spec <- compute_cols(spec, firstOf(cyl), c_pageBreak())
  spec <- compute_cols(spec, TRUE, c_style(disp, "red"))

  # Actions execute in arrival order (here: wt is cleared, then re-filled)
  spec <- compute_cols(spec, gear == 4, c_clear(wt), c_glue(wt, "after", text = "t"))