Build a poster from a declarative spec

Assembles a title band and a multi-column body of section cards into a single gtable::gtable sized for a real paper size (default A1 portrait). The spec can be an R list (built by hand, or by reading YAML with read_poster_yaml()) or a path to a YAML file, in which case it is read automatically.

Usage

poster(spec, objects = list(), theme = NULL, base_dir = NULL)

Arguments

spec: An R list following the schema above, or a path to a YAML file.
objects: Named list of R objects (ggplots, data.frames, grobs) referenced from sections[[.]]$body$object in the spec.
theme: A poster_theme() object. If NULL (default), it is built from spec$theme.
base_dir: Directory used to resolve relative image paths in the spec. Defaults to the YAML file's directory, or the working directory for a list spec.

Value

An object of class ggposter, a thin wrapper around a gtable::gtable. Print it to preview, or pass it to render_poster() to save a PDF/PNG at true size. To inspect the layout with each card's content area outlined, pass show_plot_area = TRUE to render_poster() – it's an output option, so the same poster object renders both the normal and the outlined version.

Details

See the package vignette for the full spec schema. In short:

poster: size (e.g. "A1") and orientation.
theme: Arguments passed to poster_theme().
title: Arguments passed to poster_title().
layout: columns, left, right (or any other column names): which section names go in which column, top to bottom. Set align_rows: true to line up each row position across columns to the tallest "auto"-height card at that position, instead of each column stacking at its own height. Every section must appear exactly once across all columns.
grid: An alternative to layout for irregular (CSS-Grid-like) arrangements where a card spans multiple columns and/or rows: columns (integer) and boxes (a list of list(name=, x=, y=, w=, h=), x/y 0-based, w/h defaulting to 1). Row heights follow the same height/"auto" rule as layout, but resolved per row from whichever boxes in that row don't span multiple rows; a spanning box never stretches the rows/columns it spans, it is top-left anchored at its own natural size within them. Overlapping or out-of-bounds boxes, and any section not placed in exactly one box, raise an error; content taller than the page raises a warning. If both layout and grid are set, grid wins (with a warning).
sections: Named list; each has header, optional relative height, and a body of type "text", "table", "figure", or "image" plus that type's arguments.

A spec may also be written the way the sibling tools acposter (build-poster-pdf) and qtposter write a header – flat, with the metadata at the top level rather than inside title/poster/theme – so that one header serves all three unchanged:

title: "A poster"
author: ["A. One", "B. Two"]     # authors, poster-authors
institute: "Somewhere Univ."     # institutes, affiliation(s)
note: "Funded by X"              # funding, footer
paper: A1                        # -> poster$size
orientation: portrait
columns: 2                       # -> an equal-share layout
font-size: 20                    # -> theme$base_size
font: "Noto Sans"                # -> theme$base_family

Each key is folded into the block it belongs to and renamed to ggposter's own: author/authors/poster-authors -> title$authors, institute/institutes/affiliation(s) -> title$affiliations, note/funding/footer -> title$funding, paper -> poster$size, font-size/font/cjk-family -> theme$base_size/base_family/cjk_family. A list of authors or affiliations (as the other two tools write them) is joined into the one line poster_title() draws. Setting the same thing twice – a key and its alias, or the flat and the nested form – keeps ggposter's own and warns. Nested specs are untouched, and the two forms can be mixed.

A bare size is not accepted: qtposter means type size by it and a spec here means paper, so write font-size or paper.

A top-level columns count (as cols too) stands in for layout when neither layout nor grid is given: the sections flow down the leftmost column and on into the next, in spec order, split as evenly as they divide. Given alongside layout/grid it is ignored, with a warning.

Examples

spec <- list(
  title = list(title = "Example poster"),
  layout = list(left = "intro", right = "outro"),
  sections = list(
    intro = list(header = "INTRO", body = list(type = "text", md = "- Hello")),
    outro = list(header = "OUTRO", body = list(type = "text", md = "- Bye"))
  )
)
p <- poster(spec)