A small spigot app is a folder with app.R, a template or
two and a www/ folder. Once an app has several sections,
the files are easier to find in the layout a Flask developer would
expect: templates in templates/, scripts and stylesheets in
static/, and each section of the site in a
blueprint that keeps its pages, endpoints, templates and files
together. This vignette shows that layout. Every part of it is optional,
and an app without it works as before.
The layout
myapp/
├── app.R
├── api.R # the app's own endpoints
├── R/
│ └── cars.R # the cars blueprint
├── api/
│ └── cars.R # the cars endpoints
├── templates/
│ ├── index.html
│ ├── partials/
│ │ └── nav.html
│ └── cars/
│ ├── list.html
│ └── model.html
└── static/
├── site.css
└── cars/
└── cars.js
app.R says where things are:
spigot_app(
pages = list("/" = spigot_page("index.html")),
api = "api.R",
blueprints = list("/cars" = cars),
templates = "templates",
partials = "templates/partials",
static = "static"
)templates is a search path. With it,
spigot_page("index.html") names a template rather than a
file next to app.R: spigot looks for
templates/index.html, and only then for
index.html in the app’s folder. It can list several
folders, searched in order.
partials is a folder of partials every
page can use, one per file: nav.html is
{{> nav}}. A page’s own partials win over
these, so one page can swap in its own nav.
static is a folder served at
/static. Every page can load
<link rel="stylesheet" href="static/site.css">,
whatever its depth, because spigot gives nested pages a
<base href> that points at the app’s root. httpuv
serves these files directly, without running R. www/ keeps
working alongside static/. Unlike www/,
static/ is served however the app is launched (see Where paths start).
A blueprint
The cars section of the site is one blueprint, defined in
R/cars.R:
cars <- spigot_blueprint(
pages = list("/" = spigot_page("list.html"), "/model" = spigot_page("model.html")),
api = "api/cars.R",
templates = "templates/cars",
partials = "templates/cars/partials",
static = "static/cars"
)spigot_app(blueprints = list("/cars" = cars)) mounts it
at /cars:
- Its pages are served under the prefix:
/at/cars,/modelat/cars/model. They are checked like the app’s own pages, so a path served twice is an error when the app is built. - Its endpoints are served under the app’s API, at
/api/cars/..., behind the same session check. A page calls them withspigot.get("cars/fit"). - Its templates are looked for in
templates/cars/first, then on the app’s search path, so the blueprint can override a shared template. Its partials win over the app’s, the same way. - Its static files are served at
/cars/static, and each of its pages gets that path as{{static}}. The template does not need to know where the blueprint is mounted:
# api/cars.R
#* @get /fit
function(x = "wt") {
fit_cars(x) # defined in R/, so available to the endpoints too
}Blueprints live in R/ because Shiny loads every file
there before it runs app.R, so cars exists by
the time spigot_app() needs it, and functions defined in
R/ are available to the endpoints. spigot adds no loader of
its own. The Blueprints vignette covers
them in full.
Compared with Flask
| Flask | spigot |
|---|---|
Blueprint("cars", ...),
url_prefix="/cars"
|
spigot_blueprint(...),
blueprints = list("/cars" = cars)
|
render_template("list.html") |
spigot_page("list.html") |
url_for("cars.static", filename="cars.js") |
{{static}}/cars.js |
a blueprint’s routes under /cars/...
|
its endpoints under /api/cars/...
|
<int:id> in a route |
not yet: a page reads the query string with
data = function(req)
|
whisker, spigot’s template engine, has no functions, so there is no
url_for(). Relative URLs and {{static}} cover
what it is used for.
Where paths start: root
Every path in spigot_app() and
spigot_blueprint() (templates, partials, static folders,
plumber files) is relative to root, and the files are read
when spigot_app() builds the app. root
defaults to the working directory at that moment. How the app is
launched decides what that is (see “Running the app” in
?spigot_app):
-
Running the folder, with
shiny::runApp("myapp"), RStudio’s Run App button, Shiny Server or Posit Connect: Shiny loadsR/, then runsapp.Rwith the folder as the working directory.rootis the app’s folder, and everything above works. -
Running the app object, by printing what
app.Rreturns (at the console, sourcing it with echo, orRscript app.R): Shiny does neither. The paths are relative to wherever R happens to be, andR/is not loaded, socarsdoes not exist andapp.Rstops with an error. Run the folder instead:Rscript -e 'shiny::runApp("myapp")'.
root can be set to an absolute path, for an app whose
files live somewhere other than the working directory. That does not
load R/; only running the folder does.