board_url: Use a vector of URLs as a board

Description

board_url() lets you build up a board from individual urls or a manifest file.

board_url() is read only.

Usage

board_url(
  urls,
  cache = NULL,
  use_cache_on_failure = is_interactive(),
  headers = NULL
)

Arguments

urls

Identify available pins being served at a URL or set of URLs (see details):

Unnamed string: URL to a manifest file.
Named character vector: URLs to specific pins (does not support versioning).
Named list: URLs to pin version directories (supports versioning).

cache

Cache path. Every board requires a local cache to avoid downloading files multiple times. The default stores in a standard cache location for your operating system, but you can override if needed.

use_cache_on_failure

If the pin fails to download, is it ok to use the last cached version? Defaults to is_interactive() so you'll be robust to poor internet connectivity when exploring interactively, but you'll get clear errors when the code is deployed.

headers

Named character vector for additional HTTP headers (such as for authentication). See connect_auth_headers() for Posit Connect support.

Authentication for <code>board_url()</code>

The headers argument allows you to pass authentication details or other HTTP headers to the board, such as for a Posit Connect vanity URL that is not public (see board_connect_url()) or a private GitHub repo.

gh_pat_auth <- c(
  Authorization = paste("token", "github_pat_XXXX")
)
board <- board_url(
  "https://raw.githubusercontent.com/username/repo/main/path/to/pins",
  headers = gh_pat_auth
)
board %>% pin_list()

Details

The way board_url() works depends on the type of the urls argument:

Unnamed character scalar, i.e. a single URL to a manifest file: If the URL ends in a /, board_url() will look for a _pins.yaml manifest. If the manifest file parses to a named list, versioning is supported. If it parses to a named character vector, the board will not support versioning.
Named character vector of URLs: If the URLs end in a /, board_url() will look for a data.txt that provides metadata for the associated pin. The easiest way to generate this file is to upload a pin version directory created by board_folder(). Versioning is not supported.
Named list, where the values are character vectors of URLs and each element of the vector refers to a version of the particular pin: If a URL ends in a /, board_url() will look for a data.txt that provides metadata. Versioning is supported.

Using a vector of URLs can be useful because pin_download() and pin_read() will be cached; they'll only re-download the data if it's changed from the last time you downloaded it (using the tools of HTTP caching). You'll also be protected from the vagaries of the internet; if a fresh download fails, you'll get the previously cached result with a warning.

Using a manifest file can be useful because you can serve a board of pins and allow collaborators to access the board straight from a URL, without worrying about board-level storage details. Some examples are provided in vignette("using-board-url").

Examples

Run this code

github_raw <- function(x) paste0("https://raw.githubusercontent.com/", x)

## with a named vector of URLs to specific pins:
b1 <- board_url(c(
  files = github_raw("rstudio/pins-r/main/tests/testthat/pin-files/"),
  rds = github_raw("rstudio/pins-r/main/tests/testthat/pin-rds/"),
  raw = github_raw("rstudio/pins-r/main/tests/testthat/pin-files/first.txt")
))

b1 %>% pin_read("rds")
b1 %>% pin_browse("rds", local = TRUE)

b1 %>% pin_download("files")
b1 %>% pin_download("raw")

## with a manifest file:
b2 <- board_url(github_raw("rstudio/pins-r/main/tests/testthat/pin-board/"))
b2 %>% pin_list()
b2 %>% pin_versions("y")