String Interpolation
Template variables, delimited by curly brackets, can be used to interpolate strings for three use cases:
- Captured URI targets, via the "capture" route type
- Redirection URI targets, via the "redirect" route type
- Cache key templates
Prudence supports many built-in interpolation variables, extracted from the conversation attributes and summarized below. See also the related Restlet API documentation.
Note that for cache key templates, it's possible to create your own interpolation variables using plugins.
Request URIs
These variables are composed of a prefix and a suffix. The prefix specifies which URI you are referring to, while the suffix specifies the part of that URI. For example, the prefix "{r-}" can be combined with the suffix "{-i}" for "{ri}", to specify the complete request URI.
Prefixes
- {r-}: actual URI (reference)
- {h-}: virtual host URI
- {o-}: the application's root URI on the current virtual host
- {f-}: the referring URI (sent by some clients: usually means that the client clicked a hyperlink or was redirected here from elsewhere)
Suffixes
- {-i}: the complete URI (identifier)
- {-h}: the host identifier (protocol + authority)
- {-a}: the authority (for URLs, this is the host or IP address)
- {-p}: the path (everything after the authority)
- {-w}: the wildcard (remaining part of the path after the base URI, not including the query)
- {-r}: the remaining part of the path after the base URI, including the query
- {-e}: a relative path from the URI to the application's base URI (note that this is a constructed value, not merely a string extracted from the URI)
- {-q}: the query (everything after the "?")
- {-f}: the fragment (the tag after the "#"; note that web browsers handle fragments internally and never send them to the server, however fragments may exist in URIs sent from the server: see the "{R-}" variable mentioned below)
Base URIs
Every URI also has a "base" version of it: in the case of wildcard URI templates, it is the URI before the wildcard begins. Otherwise it is usually the application's root URI on the virtual host. It is used in the "{-r}" and "{-e}" suffixes above.
To refer to the base URI directly, use the special "{-b-}" infix, to which you would still need to add one of the above suffixes. For example, "{rbi}" refers to the complete base URI of the actual URI.
Relative URIs
For cache key templates only, you can also use the "{cb}" variable. It is equivalent to calling the conversation.base API.
Interpolating the Wildcard
This is a common use case for redirection, so even though it's included in the documentation above, it's worth emphasizing. According to the rules, the "*" would be the "{rw}" variable. For example:
app.routes = {
...
'/assets/*': '/files/media/{rw}'
}
The above would capture a URI such as "/assets/images/logo.png" to "/files/media/images/logo.png".
The wildcard can also be accessed via API.
Request Attributes
- {p}: the protocol ("http," "https," "ftp," etc.)
- {m}: the method (in HTTP, it would be "GET," "POST," "PUT," "DELETE," etc.)
- {d}: date (in the RFC1123 format used by HTTP)
Client Attributes
- {cia}: client IP address
- {ciua}: client upstream IP address (if the request reached us through an upstream load balancer)
- {cig}: client agent name (for example, and identifier for the browser)
Payload Attributes
All these refer to the payload ("entity") sent by the client.
- {es}: entity size (in bytes)
- {emt}: entity media (MIME) type
- {ecs}: entity character set
- {el}: entity language
- {ee}: entity encoding
- {et}: entity tag (HTTP ETag)
- {eed}: entity expiration date
- {emd}: entity modification date
Negotiated Attributes
These are the result of content negotiation, and are used specifically for cache key templates.
- {nmt}: negotiated media (MIME) type
- {nl}: negotiated language
- {ne}: negotiated encoding
Implementation Attributes
These are used specifically for cache key templates.
- {dn}: document name
- {an}: application name
Response Attributes
These attributes are not normally used in Prudence—they are not used in routing nor in cache key templates—but are mentioned here for completion. They are all in uppercase to differentiate them from the request variables:
- {S}: the HTTP status code
- {SIA}: server IP address
- {SIP}: server port number
- {SIG}: server agent name
- {R-}: the redirection URI (see "Request URIs" above for a list of suffixes, which must also be in uppercase)
Additionally, all the entity attributes can be used in uppercase to correspond to the response entity. For example, "{ES}" for the response entity size, "{EMT}" for the response media type, etc.
conversation.locals
As we've seen in the app.routes guide, URI templates delimited by curly brackets can be used to parse incoming request URIs and extract the values into conversation.locals. For example, a "/person/{id}/" URI template will match the "/person/linus/" URI and extract "linus" into the "id" conversation.local.
But you can also do the opposite: interpolate the values that were extracted from the matched URI template. An example of redirection that both extracts and interpolates:
app.routes = {
...
"/person/{id}/": ">http://newsite.org/profile/?id={id}"
}
The Prudence Manual is provided for you under the terms of the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. The complete manual is available for download as a PDF.
