A blueprint is one section of a spigot app, packaged so that it can
be written, read and moved on its own. It holds the section’s pages and
whatever they need: the endpoints they call, their templates and
partials, and the scripts and stylesheets they load. spigot_app() mounts
it under a prefix, and the blueprint itself never says where that
is.
Use one when an app has sections that are more than a page each, such
as a cars section with a table and a model form, or an admin area, so
that app.R lists sections rather than every page and
endpoint. A one-page app does not need one. The Templates, static files and blueprints
vignette shows the folder layout around them. This one covers what a
blueprint is and how its parts are found.
A blueprint and where it lands
Here is a small blueprint with two pages and one endpoint. The templates are inline text to keep the example short. A real one usually names template files.
page <- function(body) {
spigot_page(paste0("<html><head></head><body>", body, "</body></html>"))
}
greet <- spigot_blueprint(
pages = list(
"/" = page("<h1>Hello</h1> <a href='greet/about'>About</a>"),
"/about" = page("<p>A section of the app.</p>")
),
api = spigot_api() |> plumber::pr_get("/hello", function(name = "you") {
list(message = paste("Hello,", name))
})
)
greet
#> <spigot_blueprint>
#> pages: /, /about
#> api: routerIts paths are written as if it were the whole app: its main page is
/. The app chooses the prefix when it mounts it:
app <- spigot_app(
pages = page("<a href='greet'>Greetings</a>"),
api = spigot_api(),
blueprints = list("/greet" = greet)
)Each part of a blueprint mounted at /greet lands
here:
| Part | In the blueprint | Served at | From one of its pages |
|---|---|---|---|
| A page | / |
/greet |
<a href="greet"> |
| A page | /about |
/greet/about |
<a href="greet/about"> |
| An endpoint | /hello |
/api/greet/hello |
spigot.get("greet/hello") |
| A static file |
hello.js in static
|
/greet/static/hello.js |
<script src="{{static}}/hello.js"> |
Links on a spigot page are relative to the app’s root, whatever the
page’s depth, because spigot gives nested pages a
<base href> that points there. That is why the links
above start with greet/ and not /greet/: the
same page works when the app itself is served under a path, as it is on
Shiny Server or Posit Connect. A page that should not depend on the
blueprint’s own prefix can use {{static}} for its files
(see below). Its links and API calls still name the prefix.
The prefix can have more than one segment, such as
"/tools/greet". It cannot be /, and it cannot
be under the API’s prefix.
Pages
A blueprint’s pages are the same as
spigot_app()’s: one page, served at the prefix, or a list
of pages named by path. Every page must be a spigot_page(),
because a Shiny UI can only be the app’s own / page. Data,
data functions, caching and partials work as on the app’s pages.
When the app is built, spigot checks a blueprint’s pages along with the app’s own. A path that both the app and a blueprint serve is an error that names both:
spigot_app(
pages = list("/" = page("home"), "/greet/about" = page("mine")),
api = spigot_api(),
blueprints = list("/greet" = greet)
)
#> Error:
#> ! The page "/greet/about" of the blueprint "/greet" is also a page of the app.So is a blueprint mounted under the API:
spigot_app(pages = page("home"), api = spigot_api(), blueprints = list("/api/greet" = greet))
#> Error:
#> ! The blueprint "/api/greet" is under the API prefix "/api", so it would never be served.The API
A blueprint’s api is a plumber file or a plumber router.
spigot mounts it on the app’s router at the blueprint’s prefix, so with
the default prefix = "/api" the blueprint’s
/hello is /api/greet/hello. It is part of the
app’s API, so the app’s checks apply: unless
require_session = FALSE, it answers only requests from the
app’s own pages, and its endpoints can call spigot_session(),
spigot_emit()
and the rest. A page calls it like any other endpoint, with the path
below the API prefix:
A file is read when spigot_app() builds the app,
relative to the app’s root, and its endpoints are evaluated
in the environment where spigot_blueprint() was called. For
a blueprint defined in the app’s R/ folder, that is the
environment Shiny loads R/ into, so the endpoints can use
any function defined there:
# R/cars.R
fit_cars <- function(x) {
fit <- stats::lm(stats::reformulate(x, "mpg"), data = datasets::mtcars)
list(r_squared = summary(fit)$r.squared)
}
cars <- spigot_blueprint(
pages = list("/" = spigot_page("list.html"), "/model" = spigot_page("model.html")),
api = "api/cars.R"
)
# api/cars.R
#* @get /fit
function(x = "wt") fit_cars(x)A blueprint can leave api out. Its pages can still call
the app’s own endpoints.
Templates and partials
A blueprint’s templates are folders searched before the
app’s when one of its pages names a template file. For a page of the
cars blueprint, spigot_page("list.html") is found in the
first of these places that has it:
- The blueprint’s
templates, in order, such astemplates/cars/list.html. - The app’s
templates, in order, such astemplates/list.html. - The app’s
root,list.html.
A blueprint can therefore use the app’s shared templates, or keep its own file under a name the app also uses. Its file wins, and only for its own pages.
Partials follow the same rule, closest first. A page’s own
partials win over its blueprint’s, and those win over the
app’s. If the app’s partials folder holds nav.html and the
blueprint’s holds a nav.html too, {{> nav}}
is the blueprint’s nav on its pages and the app’s everywhere else:
cars <- spigot_blueprint(
pages = list("/" = spigot_page("list.html")),
templates = "templates/cars",
partials = "templates/cars/partials" # its own nav.html
)
spigot_app(
pages = list("/" = spigot_page("index.html")),
api = "api.R",
blueprints = list("/cars" = cars),
templates = "templates",
partials = "templates/partials" # the app's nav.html, head.html, footer.html
)All of these files are read, and every partial a page uses is
checked, when spigot_app() builds the app. A missing file
or partial stops the app before it serves anything.
Static files and {{static}}
A blueprint’s static is one folder, served at
<prefix>/static. httpuv sends these files directly,
without running R, however the app is launched.
Every page of a blueprint with static gets the folder’s
URL in its data as {{static}}: cars/static for
a blueprint mounted at /cars, relative to the app’s root
like every other link. A template can load its files without knowing the
prefix:
If a page’s data has its own static, that one is used. A
page whose data is a function gets static
added to what the function returns.
Defining blueprints in R/
Define each blueprint in a file in the app’s R/ folder,
one file per blueprint:
myapp/
├── app.R # spigot_app(blueprints = list("/cars" = cars, "/model" = model))
├── R/
│ ├── cars.R # cars <- spigot_blueprint(...)
│ └── model.R # model <- spigot_blueprint(...)
├── api/
│ └── cars.R
├── templates/
│ ├── cars/
│ └── model/
└── static/
├── cars/
└── model/
Shiny loads every file in R/, in alphabetical order,
before it runs app.R, so the blueprints exist when
spigot_app() asks for them. A blueprint’s paths, like the
app’s, are relative to the app’s root, which is the app’s
folder when the folder is run. This only happens when the
folder is run, with shiny::runApp("myapp"),
RStudio’s Run App button, Shiny Server or Posit Connect. See Where paths start.
The site example (run_example("site")) is
laid out this way, with a cars blueprint and a
model blueprint.
Blueprints are values
spigot_blueprint() returns an ordinary R object, and
mounting it does not change it. The same blueprint can be mounted at
more than one prefix. Its pages and endpoints are then served under each
prefix, and each mount’s pages get their own
{{static}}:
app <- spigot_app(
pages = page("home"),
api = spigot_api(),
blueprints = list("/greet" = greet, "/hello" = greet)
)Copies with different settings come from a function that returns a blueprint. Here, two sections show different columns of the same data:
table_section <- function(title, columns) {
spigot_blueprint(spigot_page(
"<html><head></head><body><h1>{{title}}</h1>{{#rows}}<p>{{row}}</p>{{/rows}}</body></html>",
data = list(
title = title,
rows = lapply(do.call(paste, unname(datasets::mtcars[columns])),
function(row) list(row = row))
),
cache = TRUE
))
}
app <- spigot_app(
pages = page("home"),
api = spigot_api(),
blueprints = list(
"/engine" = table_section("Engine", c("cyl", "disp", "hp")),
"/weight" = table_section("Weight", c("wt", "qsec"))
)
)Blueprints do not nest: a blueprint has pages but no
blueprints of its own. A section deep in a site takes a
longer prefix, such as "/tools/greet".
Compared with Flask
| Flask | spigot |
|---|---|
bp = Blueprint("cars", __name__, template_folder=..., static_folder=...) |
cars <- spigot_blueprint(pages, api, templates, static = ...) |
app.register_blueprint(bp, url_prefix="/cars") |
spigot_app(blueprints = list("/cars" = cars)) |
@bp.route("/model") |
"/model" = spigot_page(...) in pages
|
| a JSON route on the blueprint | an endpoint in its api, served at
/api/cars/...
|
url_for("cars.static", filename="cars.js") |
{{static}}/cars.js |
| blueprint templates searched after the app’s | blueprint templates searched before the app’s |
The last row is a deliberate difference. In Flask an app’s template overrides a blueprint’s with the same name. In spigot the blueprint’s own file wins, the way its partials do, so a section is not changed by a file another part of the app happens to add.