Metadata by Polkas · Pull Request #19 · pharmaverse/gridify

Polkas · 2026-05-10T20:58:49Z

Add metadata argument to export_to() with JSON sidecar support

Introduces an opt-in metadata argument to export_to() that records set_cell() text values alongside exported files.

What's new

export_to() gains a metadata argument ("none" / "sidecar"). Passing "sidecar" writes a <file>.json sidecar next to the output — a flat JSON object for single-page exports, or a JSON array (one entry per page) for multi-page PDFs.
A gridify.export.metadata global option allows project-wide defaults (e.g. in .Rprofile).
Internal helpers extracted to gridify-utils.R: gridify_metadata(), gridify_to_json(), write_metadata_sidecar(), resolve_export_metadata().
jsonlite added as Suggests (not Imports) — only required when metadata = "sidecar" is used; a clear requireNamespace guard provides an install prompt otherwise.

Tests & docs

New test files: test_export_to.R, test_gridify_to_json.R.
New man pages for all internal helpers.
Vignettes (simple_examples, multi_page_examples) and NEWS.md updated.

codecov-commenter · 2026-05-10T21:02:21Z

Codecov Report

❌ Patch coverage is 97.77778% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 99.40%. Comparing base (01b7233) to head (2c04b10).

Files with missing lines	Patch %	Lines
R/gridify-utils.R	96.66%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #19      +/-   ##
==========================================
- Coverage   99.57%   99.40%   -0.18%     
==========================================
  Files           9        9              
  Lines         936     1000      +64     
==========================================
+ Hits          932      994      +62     
- Misses          4        6       +2

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Comment out old R versions in CI configuration

Polkas · 2026-05-28T11:49:53Z

Examples to run manually:

if (requireNamespace("devtools", quietly = TRUE)) {
  devtools::load_all(".", quiet = TRUE)
} else {
  library(gridify)
}

if (!requireNamespace("jsonlite", quietly = TRUE)) {
  stop("jsonlite is required for these manual metadata examples.")
}

out_dir <- file.path("sth", "manual_metadata_outputs")
dir.create(out_dir, recursive = TRUE, showWarnings = FALSE)

clean_file <- function(path) {
  unlink(c(path, paste0(path, ".json")), force = TRUE)
}

sidecar <- function(path) paste0(path, ".json")

read_sidecar <- function(path, simplifyVector = FALSE) {
  jsonlite::fromJSON(sidecar(path), simplifyVector = simplifyVector)
}

check_file <- function(path) {
  stopifnot(file.exists(path))
}

check_no_sidecar <- function(path) {
  stopifnot(!file.exists(sidecar(path)))
}

check_sidecar <- function(path) {
  stopifnot(file.exists(sidecar(path)))
}

check_gridify_schema <- function(metadata) {
  stopifnot(identical(metadata$schema, "gridify.sidecar.metadata"))
  stopifnot(identical(metadata$schema_version, "1.0.0"))
}

make_grid <- function(company = "My Company", title = "Manual Metadata PR", watermark = "DRAFT") {
  gridify(grid::rectGrob(), pharma_layout_base()) |>
    set_cell("header_left_1", company) |>
    set_cell("title_1", title) |>
    set_cell("watermark", watermark)
}

make_default_text_grid <- function() {
  gridify(grid::rectGrob(), pharma_layout_base())
}

make_true_empty_grid <- function() {
  gridify(grid::rectGrob(), simple_layout())
}

run_example <- function(label, expr) {
  message("\n", label)
  force(expr)
  message("OK: ", label)
}

old_options <- options(gridify.export.metadata = NULL)
on.exit(options(old_options), add = TRUE)

obj <- make_grid()
obj_special <- make_grid(
  company = "Company / Study X",
  title = "Title with quotes \"x\" and slash \\",
  watermark = "DRAFT\nSecond line"
)
default_text_obj <- make_default_text_grid()
true_empty_obj <- make_true_empty_grid()

run_example("01 default export writes output but no sidecar", {
  path <- file.path(out_dir, "01_default_no_sidecar.pdf")
  clean_file(path)
  export_to(obj, path)
  check_file(path)
  check_no_sidecar(path)
})

run_example("02 metadata sidecar for single PDF", {
  path <- file.path(out_dir, "02_single_pdf_sidecar.pdf")
  clean_file(path)
  export_to(obj, path, metadata = "sidecar")
  check_file(path)
  check_sidecar(path)
  parsed <- read_sidecar(path)
  check_gridify_schema(parsed)
  stopifnot(length(parsed$pages) == 1)
  stopifnot(identical(parsed$pages[[1]]$cells$header_left_1, "My Company"))
  stopifnot(identical(parsed$pages[[1]]$cells$title_1, "Manual Metadata PR"))
})

run_example("03 metadata sidecar for PNG", {
  path <- file.path(out_dir, "03_png_sidecar.png")
  clean_file(path)
  export_to(obj, path, metadata = "sidecar")
  check_file(path)
  check_sidecar(path)
  parsed <- read_sidecar(path)
  check_gridify_schema(parsed)
  stopifnot(identical(parsed$pages[[1]]$cells$watermark, "DRAFT"))
})

run_example("04 metadata sidecar preserves special characters", {
  path <- file.path(out_dir, "04_special_chars.pdf")
  clean_file(path)
  export_to(obj_special, path, metadata = "sidecar")
  check_sidecar(path)
  parsed <- read_sidecar(path)
  check_gridify_schema(parsed)
  stopifnot(identical(parsed$pages[[1]]$cells$title_1, "Title with quotes \"x\" and slash \\"))
  stopifnot(identical(parsed$pages[[1]]$cells$watermark, "DRAFT\nSecond line"))
})

run_example("05 metadata = 's' abbreviation writes sidecar", {
  path <- file.path(out_dir, "05_abbrev_sidecar.pdf")
  clean_file(path)
  export_to(obj, path, metadata = "s")
  check_file(path)
  check_sidecar(path)
})

run_example("06 global option writes sidecar by default", {
  path <- file.path(out_dir, "06_global_option.pdf")
  clean_file(path)
  old <- options(gridify.export.metadata = "sidecar")
  on.exit(options(old), add = TRUE)
  export_to(obj, path)
  check_file(path)
  check_sidecar(path)
})

run_example("07 explicit metadata = 'none' overrides global option and removes stale sidecar", {
  path <- file.path(out_dir, "07_none_overrides_option.pdf")
  clean_file(path)
  export_to(obj, path, metadata = "sidecar")
  check_sidecar(path)
  old <- options(gridify.export.metadata = "sidecar")
  on.exit(options(old), add = TRUE)
  export_to(obj, path, metadata = "none")
  check_file(path)
  check_no_sidecar(path)
})

run_example("08 re-export same path without metadata removes stale sidecar", {
  path <- file.path(out_dir, "08_reexport_none_removes.pdf")
  clean_file(path)
  export_to(obj, path, metadata = "sidecar")
  check_sidecar(path)
  export_to(obj, path, metadata = "none")
  check_file(path)
  check_no_sidecar(path)
})

run_example("09 layout default text writes sidecar without set_cell values", {
  path <- file.path(out_dir, "09_default_layout_text.pdf")
  clean_file(path)
  export_to(default_text_obj, path, metadata = "sidecar")
  check_file(path)
  check_sidecar(path)
  parsed <- read_sidecar(path)
  check_gridify_schema(parsed)
  stopifnot(identical(parsed$pages[[1]]$cells, list(header_right_1 = "CONFIDENTIAL")))
})

run_example("09b true empty object writes no sidecar", {
  path <- file.path(out_dir, "09b_true_empty_no_sidecar.pdf")
  clean_file(path)
  export_to(true_empty_obj, path, metadata = "sidecar")
  check_file(path)
  check_no_sidecar(path)
})

run_example("09c true empty object filled with set_cell writes sidecar", {
  path <- file.path(out_dir, "09c_true_empty_then_filled.pdf")
  clean_file(path)
  filled_obj <- true_empty_obj |>
    set_cell("title", "Filled after empty")
  export_to(filled_obj, path, metadata = "sidecar")
  check_file(path)
  check_sidecar(path)
  parsed <- read_sidecar(path)
  check_gridify_schema(parsed)
  stopifnot(identical(parsed$pages[[1]]$cells, list(title = "Filled after empty")))
})

run_example("09d re-run filled output with true empty object removes sidecar", {
  path <- file.path(out_dir, "09d_filled_then_true_empty_removes.pdf")
  clean_file(path)
  filled_obj <- true_empty_obj |>
    set_cell("title", "Temporary metadata")
  export_to(filled_obj, path, metadata = "sidecar")
  check_file(path)
  check_sidecar(path)
  export_to(true_empty_obj, path, metadata = "sidecar")
  check_file(path)
  check_no_sidecar(path)
})

run_example("10 re-export with changed metadata overwrites old sidecar", {
  path <- file.path(out_dir, "10_overwrite_sidecar.pdf")
  clean_file(path)
  export_to(make_grid(company = "Company A"), path, metadata = "sidecar")
  stopifnot(identical(read_sidecar(path)$pages[[1]]$cells$header_left_1, "Company A"))
  export_to(make_grid(company = "Company B"), path, metadata = "sidecar")
  stopifnot(identical(read_sidecar(path)$pages[[1]]$cells$header_left_1, "Company B"))
})

run_example("11 multi-page PDF writes pages schema with one entry per page", {
  path <- file.path(out_dir, "11_multipage_pdf.pdf")
  clean_file(path)
  export_to(
    list(make_grid(title = "Page 1"), make_grid(title = "Page 2")),
    path,
    metadata = "sidecar"
  )
  check_file(path)
  check_sidecar(path)
  parsed <- read_sidecar(path)
  check_gridify_schema(parsed)
  stopifnot(length(parsed$pages) == 2)
  stopifnot(identical(parsed$pages[[1]]$cells$title_1, "Page 1"))
  stopifnot(identical(parsed$pages[[2]]$cells$title_1, "Page 2"))
})

run_example("12 multi-page PDF with mixed empty and populated pages still writes sidecar", {
  path <- file.path(out_dir, "12_mixed_multipage_pdf.pdf")
  clean_file(path)
  export_to(list(true_empty_obj, make_grid(title = "Only page with metadata")), path, metadata = "sidecar")
  check_sidecar(path)
  parsed <- read_sidecar(path)
  check_gridify_schema(parsed)
  stopifnot(length(parsed$pages) == 2)
  stopifnot(length(parsed$pages[[1]]$cells) == 0)
  stopifnot(identical(parsed$pages[[2]]$cells$title_1, "Only page with metadata"))
})

run_example("13 multiple separate files write one sidecar per file", {
  paths <- file.path(out_dir, sprintf("13_separate_%s.png", 1:2))
  lapply(paths, clean_file)
  export_to(
    list(make_grid(title = "Separate 1"), make_grid(title = "Separate 2")),
    paths,
    metadata = "sidecar"
  )
  lapply(paths, check_file)
  lapply(paths, check_sidecar)
  stopifnot(identical(read_sidecar(paths[[1]])$pages[[1]]$cells$title_1, "Separate 1"))
  stopifnot(identical(read_sidecar(paths[[2]])$pages[[1]]$cells$title_1, "Separate 2"))
})

run_example("14 multiple separate files remove stale sidecars when metadata is truly empty", {
  paths <- file.path(out_dir, sprintf("14_separate_empty_%s.pdf", 1:2))
  lapply(paths, clean_file)
  export_to(list(make_grid(title = "Has metadata"), make_grid(title = "Also metadata")), paths, metadata = "sidecar")
  lapply(paths, check_sidecar)
  export_to(list(true_empty_obj, true_empty_obj), paths, metadata = "sidecar")
  lapply(paths, check_file)
  lapply(paths, check_no_sidecar)
})

run_example("15 invalid metadata value errors", {
  path <- file.path(out_dir, "15_invalid_metadata.pdf")
  clean_file(path)
  err <- tryCatch(
    {
      export_to(obj, path, metadata = "yes")
      NULL
    },
    error = identity
  )
  stopifnot(inherits(err, "error"))
  stopifnot(grepl("should be one of", conditionMessage(err), fixed = TRUE))
})

run_example("16 TIFF sidecar when TIFF device is available", {
  path <- file.path(out_dir, "16_tiff_sidecar.tiff")
  clean_file(path)
  err <- tryCatch(
    {
      export_to(obj, path, metadata = "sidecar")
      NULL
    },
    error = identity
  )
  if (inherits(err, "error")) {
    message("Skipped TIFF check because this R build/device failed: ", conditionMessage(err))
  } else {
    check_file(path)
    check_sidecar(path)
    parsed <- read_sidecar(path)
    check_gridify_schema(parsed)
    stopifnot(length(parsed$pages) == 1)
  }
})

run_example("17 multi-page PDF stale sidecar is removed when later pages are truly empty", {
  path <- file.path(out_dir, "17_multipage_empty_removes.pdf")
  clean_file(path)
  export_to(list(make_grid(title = "First"), make_grid(title = "Second")), path, metadata = "sidecar")
  check_sidecar(path)
  export_to(list(true_empty_obj, true_empty_obj), path, metadata = "sidecar")
  check_file(path)
  check_no_sidecar(path)
})

run_example("18 multi-page PDF overwrites page count and page metadata", {
  path <- file.path(out_dir, "18_multipage_overwrite.pdf")
  clean_file(path)
  export_to(list(make_grid(title = "Old 1"), make_grid(title = "Old 2")), path, metadata = "sidecar")
  stopifnot(length(read_sidecar(path)$pages) == 2)
  export_to(list(make_grid(title = "New only page")), path, metadata = "sidecar")
  parsed <- read_sidecar(path)
  check_gridify_schema(parsed)
  stopifnot(length(parsed$pages) == 1)
  stopifnot(identical(parsed$pages[[1]]$cells$title_1, "New only page"))
})

run_example("19 multiple separate PDF files write one-page sidecars with global option", {
  paths <- file.path(out_dir, sprintf("19_global_separate_%s.pdf", 1:3))
  lapply(paths, clean_file)
  old <- options(gridify.export.metadata = "sidecar")
  on.exit(options(old), add = TRUE)
  export_to(
    list(make_grid(title = "Global 1"), make_grid(title = "Global 2"), make_grid(title = "Global 3")),
    paths
  )
  lapply(paths, check_file)
  lapply(paths, check_sidecar)
  parsed <- lapply(paths, read_sidecar)
  lapply(parsed, check_gridify_schema)
  stopifnot(all(vapply(parsed, function(x) length(x$pages) == 1, logical(1))))
  stopifnot(identical(parsed[[3]]$pages[[1]]$cells$title_1, "Global 3"))
})

run_example("20 multiple separate files handle mixed empty and populated metadata", {
  paths <- file.path(out_dir, sprintf("20_mixed_separate_%s.png", 1:3))
  lapply(paths, clean_file)
  export_to(
    list(make_grid(title = "Old 1"), make_grid(title = "Old 2"), make_grid(title = "Old 3")),
    paths,
    metadata = "sidecar"
  )
  lapply(paths, check_sidecar)
  export_to(
    list(default_text_obj, make_grid(title = "Still has metadata"), default_text_obj),
    paths,
    metadata = "sidecar"
  )
  check_sidecar(paths[[1]])
  check_sidecar(paths[[2]])
  check_sidecar(paths[[3]])
  check_gridify_schema(read_sidecar(paths[[1]]))
  check_gridify_schema(read_sidecar(paths[[2]]))
  check_gridify_schema(read_sidecar(paths[[3]]))
  stopifnot(identical(read_sidecar(paths[[1]])$pages[[1]]$cells, list(header_right_1 = "CONFIDENTIAL")))
  stopifnot(identical(read_sidecar(paths[[2]])$pages[[1]]$cells$title_1, "Still has metadata"))
  stopifnot(identical(read_sidecar(paths[[3]])$pages[[1]]$cells, list(header_right_1 = "CONFIDENTIAL")))
})

message("\nManual metadata examples completed. Outputs are in: ", normalizePath(out_dir))

Alexandra01 · 2026-06-03T15:46:12Z

+#' Validated with [match.arg()] so it can be abbreviated.
+#' When `metadata = NULL` (the default), the value is taken from the
+#' `gridify.export.metadata` global option (see [options()]), falling back to
+#' `"none"` if unset. This makes it possible to enable the feature globally
+#' for a project via
+#' `options(gridify.export.metadata = "sidecar")`.


Suggested change

#' Validated with [match.arg()] so it can be abbreviated.

#' When `metadata = NULL` (the default), the value is taken from the

#' `gridify.export.metadata` global option (see [options()]), falling back to

#' `"none"` if unset. This makes it possible to enable the feature globally

#' for a project via

#' `options(gridify.export.metadata = "sidecar")`.

#' It is possible to enable the feature globally for a project via

#' `options(gridify.export.metadata = "sidecar")`.

Alexandra01 · 2026-06-03T15:47:50Z

-})
+setGeneric(
+  "export_to",
+  function(x, to, device = NULL, metadata = NULL, ...) {


The documentation says this is "none" by default and to use "none" when you don't want to export the metadata

Suggested change

function(x, to, device = NULL, metadata = NULL, ...) {

function(x, to, device = NULL, metadata = "none", ...) {

Or it should be NULL by default and docs need updating

Alexandra01 · 2026-06-03T15:48:59Z

+    return(FALSE)
+  }
+  if (is.list(payload) && is.null(names(payload))) {
+    return(any(vapply(payload, has_metadata_payload, logical(1))))


Is this the best way to manage the situation? payload is one of NULL, an empty list or its a non-empty list so I'm not sure what the vapply is doing

Alexandra01 · 2026-06-03T15:49:59Z

  user_args <- list(...)
+  payload <- if (metadata == "none") NULL else gridify_metadata(x)
+  sidecar_json <- if (metadata == "sidecar" && has_metadata_payload(payload)) {
+    gridify_to_json(metadata_sidecar_payload(payload))


These functions gridify_to_json and metadata_sidecar_payload are always used together and are quite small, it might be worth merging them together. I also think it would be easier to debug in the future as you wouldn't have to check both functions

metadata

32187ba

Polkas force-pushed the metadata branch from 280a73f to 32187ba Compare May 10, 2026 21:02

Polkas added 4 commits May 11, 2026 10:19

improve arg

d941ad9

none as default and global option

42b8795

proper utils meta

940f0ae

improve the PR - simplify and no deps

c90575a

Polkas mentioned this pull request May 21, 2026

General Issue: Investigate the topic of metadata for pdf in R #15

Open

Polkas marked this pull request as ready for review May 25, 2026 16:33

Merge branch 'main' into metadata

edd73e3

Polkas closed this May 26, 2026

Polkas reopened this May 26, 2026

Polkas and others added 5 commits May 26, 2026 18:02

Merge branch 'main' into metadata

4aebc72

Disable old R versions in workflow

dd82292

Comment out old R versions in CI configuration

Huge improvements - better json structure and prevent outdated json

e849921

improve the structure

fa44a14

Update NEWS.md with changes and bug fixes

0da061c

take into account defaults

2c04b10

Polkas marked this pull request as draft June 3, 2026 09:04

Alexandra01 reviewed Jun 3, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Metadata#19

Metadata#19
Polkas wants to merge 12 commits into
mainfrom
metadata

Polkas commented May 10, 2026 •

edited

Loading

Uh oh!

codecov-commenter commented May 10, 2026 •

edited

Loading

Uh oh!

Polkas commented May 28, 2026

Uh oh!

Alexandra01 Jun 3, 2026

Uh oh!

Alexandra01 Jun 3, 2026

Uh oh!

Alexandra01 Jun 3, 2026

Uh oh!

Alexandra01 Jun 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	function(x, to, device = NULL, metadata = NULL, ...) {
	function(x, to, device = NULL, metadata = "none", ...) {

Conversation

Polkas commented May 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov-commenter commented May 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Polkas commented May 28, 2026

Uh oh!

Alexandra01 Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

Alexandra01 Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

Alexandra01 Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

Alexandra01 Jun 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Polkas commented May 10, 2026 •

edited

Loading

codecov-commenter commented May 10, 2026 •

edited

Loading