Bind the collection into a site

Builds the collection into a static site with the webR engine and the prebuilt packages (unless build.bundle-engine is false), the collection's compiled packages and files, the exlibris viewer with its configuration, and a LICENSES/ directory. Like bookbinding, this assembles every part into a finished volume. The site goes to build.output-dir in _webrarian.yml (default _site). An existing site there is replaced only once the new one is complete.

Usage

bind(path = ".", offline = NULL, clean = NULL)

Arguments

path: The collection, or any directory inside it.
offline: If TRUE, the site makes no request to another origin when it runs. The webR engine and every prebuilt package are copied into it, and a share link, the Packages tab or install.packages() can add only the packages it bundles. If FALSE, the page may also install packages from repo.r-wasm.org (and packages.repos), so visitors can add any published package. NULL (the default) uses build.offline from _webrarian.yml, which defaults to FALSE. Whether an online site carries the engine and its prebuilt packages is the separate build.bundle-engine setting. It defaults to true, and false loads the engine from the webR CDN and has the page install the packages when it opens.
clean: If TRUE, the new site replaces everything in the output directory. If FALSE, keep files of the previous site that the build does not write (a file added to the output directory by hand, say), but nothing under a directory the build owns, such as vfs-files/. Either way the site is built in a staging directory and replaces the old one only when the build succeeds. NULL (the default) uses build.clean, which defaults to TRUE.

Value

Invisibly, a webrarian_bind_result with output (the site's path), size_by_part (bytes of the engine, packages, files and viewer, the last being everything else, where engine is 0 when the page loads the engine from the webR CDN), packages (the packages the page installs) and offline. Printing it shows the same summary.

The viewer's Share button makes a link that opens a visitor's files on the same site. repl.share-links in _webrarian.yml decides what such a link may do. "open" (the default) lets it add files and packages, "fixed" lets it add files only, and "off" makes the page ignore links and hides the button. A link never removes the site's packages or replaces its startup script, so a shared file at the startup script's path is saved beside it as <name>-shared.<ext>. In "open" mode any other shared file with the same path as a bundled file replaces it for that visitor, and in "fixed" mode it is saved beside it. On a site built with build.offline: true a link can add only packages the site bundles. See vignette("customization", package = "webrarian").

Examples

collection <- file.path(tempdir(), "webrarian-bind-demo")
catalog(collection)
#> ✔ Created directory /tmp/RtmpQU25pJ/webrarian-bind-demo
#> ✔ Created _webrarian.yml
#> ✔ Added "_site/" and ".webrarian/" to .gitignore
#> ✔ Cataloged webrarian collection: "webrarian-bind-demo"
#> 
#> Next steps:
#>   Move into the collection: `setwd("/tmp/RtmpQU25pJ/webrarian-bind-demo")`
#>   Acquire packages: `webrarian::acquire_package("dplyr")`
#>   Acquire files: `webrarian::acquire_file("data/")`
#>   Bind: `webrarian::bind()`
#>   Reading room: `webrarian::reading_room()`
#> ℹ Or pass `path` to each call, e.g. `webrarian::bind(path =
#>   "/tmp/RtmpQU25pJ/webrarian-bind-demo")`
writeLines("mean(1:10)", file.path(collection, "analysis.R"))
acquire_file("analysis.R", path = collection)
#> ✔ Added 1 path: analysis.R

# Load the webR engine from its CDN instead of copying the ~40 MB engine
# into the site, so this build downloads nothing
settings_set(collection, "build.bundle-engine" = FALSE)
site <- bind(collection)
#> 
#> ── Building webrarian bundle ───────────────────────────────────────────────────
#> Project: "webrarian-bind-demo"
#> webR version: "0.6.0"
#> Output: /tmp/RtmpQU25pJ/webrarian-bind-demo/_site
#> ℹ Using webR CDN engine (v0.6.0)
#> ℹ Copying collection files...
#> ℹ Including 1 file in VFS
#> ℹ Copying collection files...

#> ✔ Copying collection files... [12ms]
#> 
#> ℹ Emitting viewer + config...
#> ✔ Emitted viewer with inline config
#> ℹ Emitting viewer + config...

#> ✔ Wrote _headers
#> ℹ Emitting viewer + config...

#> ✔ Emitting viewer + config... [44ms]
#> 
#> ✔ Build complete! Output size: 1.49M (engine 0, packages 0, files 11, viewer 1.49M)
#> 
#> Preview: `webrarian::reading_room("/tmp/RtmpQU25pJ/webrarian-bind-demo")`
site
#> Site: /tmp/RtmpQU25pJ/webrarian-bind-demo/_site
#> Size: 1.49M (engine 0, packages 0, files 11, viewer 1.49M)
#> Engine: loaded from the webR CDN
#> Offline: no, the page may install packages from the network
list.files(site$output)
#> [1] "LICENSES"                "_headers"               
#> [3] "exlibris-r.0f36498a.js"  "exlibris-r.8914b174.css"
#> [5] "index.html"              "sw.js"                  
#> [7] "vfs-files"              

# Build somewhere else by changing build.output-dir
settings_set(collection, "build.output-dir" = "public")
bind(collection)
#> 
#> ── Building webrarian bundle ───────────────────────────────────────────────────
#> Project: "webrarian-bind-demo"
#> webR version: "0.6.0"
#> Output: /tmp/RtmpQU25pJ/webrarian-bind-demo/public
#> ℹ Using webR CDN engine (v0.6.0)
#> ℹ Copying collection files...
#> ℹ Including 1 file in VFS
#> ℹ Copying collection files...

#> ✔ Copying collection files... [11ms]
#> 
#> ℹ Emitting viewer + config...
#> ✔ Emitted viewer with inline config
#> ℹ Emitting viewer + config...

#> ✔ Wrote _headers
#> ℹ Emitting viewer + config...

#> ✔ Emitting viewer + config... [57ms]
#> 
#> ✔ Build complete! Output size: 1.49M (engine 0, packages 0, files 11, viewer 1.49M)
#> 
#> Preview: `webrarian::reading_room("/tmp/RtmpQU25pJ/webrarian-bind-demo")`

if (FALSE) { # \dontrun{
# By default the webR engine is copied into the site; it is downloaded
# once into the webrarian cache (see webr_cache_info()).
settings_set(collection, "build.bundle-engine" = TRUE)
bind(collection)

# An offline site: the engine and every prebuilt package are copied in,
# and the page makes no request to another origin
bind(collection, offline = TRUE)

# GitHub and local packages are compiled to WebAssembly in the versioned
# ghcr.io/r-wasm/webr Docker image, so Docker must be running.
acquire_package("r-lib/cli", path = collection, source = "github")
bind(collection)
} # }

unlink(collection, recursive = TRUE)

Usage

Arguments

Value

Share links

Examples