Open the reading room (preview server) — reading

Serves a built site, or a mirror, on a local port with the cross-origin isolation headers webR needs. The server runs on httpuv's own thread, so it keeps answering while R is busy. Requires the httpuv package.

Usage

reading_room(
  path = ".",
  port = NULL,
  watch = FALSE,
  block = TRUE,
  open_browser = rlang::is_interactive()
)

Arguments

path: A collection or any directory inside one, whose built site (build.output-dir) is served, or any other directory holding an index.html, such as a mirror from collection_mirror(), which is served as it is.
port: Port number. NULL (the default) picks a free port. A port that is already in use is an error.
watch: If TRUE, build the collection, serve it, and rebuild it whenever _webrarian.yml or an included file changes. A change to the included files only updates vfs-files/ and the page's file list, and any other change runs a full bind(). The open page reloads itself after a successful rebuild (a small script added when the page is served, never written to the site). A failed rebuild keeps the last good site and is tried again after the next change. Needs block = TRUE, because the watch loop, which also answers the page's reload checks, runs in the console.
block: If TRUE (the default), keep the console busy until you press Ctrl+C, then stop the server. If FALSE, return at once, and the server keeps running until reading_room_close() or the room's close().
open_browser: If TRUE, open the preview in the default browser. Defaults to TRUE in interactive sessions only.

Value

Invisibly, the reading room. Its url and port elements give the address, and its close() element stops it. Previewing the same site again stops the earlier preview and says so.

Examples

if (interactive() && requireNamespace("httpuv", quietly = TRUE)) {
  collection <- file.path(tempdir(), "webrarian-preview-demo")
  catalog(collection)
  bind(collection)

  # Serve in the background and keep the console free
  room <- reading_room(collection, block = FALSE)
  room$url
  room$close()

  # Rebuild on every change, and reload the page, until you press Ctrl+C
  reading_room(collection, watch = TRUE)
}