{include:fn:type:headers:data:err}

Description

Fetches the content of a file or URL and returns it inline. By default it makes an HTTP request to fn (a filename or URL); the type parameter selects another source or HTTP method. With type GET/POST/PUT/DELETE/PATCH/OPTIONS/HEAD it performs that HTTP method, sending data as the request body and headers (a JSON object, typically built with jsonasoc) as request headers - the common pattern for calling REST APIs. type http (the default) and ajax fetch a URL; site, fileman and readfile read a local file from the site or slice file area or the document root. If fn is empty nothing is fetched and the result is empty. On a failed request the err text is returned instead; inside err the tokens _#status and _#errmsg are replaced with the HTTP status code and the error message. The literal URL_PARAMETERS inside fn is replaced with the current query string. Note: every render runs the fetch, so use include only where a live request on each page view is intended.

Parameters

fn required

Filename or URL to fetch. Required - if empty, include returns nothing. For HTTP types this is the URL (a literal URL_PARAMETERS in it is replaced with the current query string); for file types (site, fileman, readfile) it is a path within the chosen file area.

type optional default http

Where or how to fetch fn. Default http. HTTP fetch: http, ajax. HTTP methods (send data and headers): GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD. Local file read: site, fileman, readfile. An unknown type returns nothing.

headers optional

Request headers as a JSON object, e.g. built with jsonasoc. Used for the HTTP-method types. Empty means no extra headers.

data optional

Request body sent with POST, PUT, DELETE, PATCH and similar methods. Empty means no body.

err optional

Text returned instead of the response when the request fails. Inside it the token _#status is replaced with the HTTP status code and _#errmsg with the error message. Empty means a failed request returns an empty string.

Examples

test[{include:}]

Expected[]

Actual[]

With no filename nothing is fetched and the result is empty. Always provide fn.

test[{include:notes.txt:badtype}]

Expected[]

Actual[]

If type is not one of the recognised values (http, ajax, site, fileman, readfile, GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD) include returns an empty string without fetching anything.

virtual{include:https#://www.example.com/snippet.html}

Expected(the HTML returned by the URL)

With the default type http, fn is fetched as a URL and its body is returned inline. The hash before the colon escapes it so the colon in https is not read as a parameter separator.

virtual

{include:https#://api.example.com/v1/lists/42/subscribers?per_page=500:GET:{jsonasoc:Content-Type:application/json:key:API_KEY}}

Expected(the API response body, e.g. a JSON list of subscribers)

The real-world pattern for calling a REST API. type GET makes a GET request; the third parameter is the request headers as a JSON object, here built with jsonasoc (Content-Type plus an api key header). The response body (usually JSON) is returned for further parsing.

virtual{include:https#://api.example.com/v1/items:POST:{jsonasoc:Content-Type:application/json}:{jsonarray:title:Hello}}

Expected(the API response body for the created item)

type POST sends the fourth parameter (data) as the request body. Here the body is a small JSON object built with jsonarray and the Content-Type header says it is JSON. The same shape works for PUT, PATCH and DELETE.

virtual{include:https#://api.example.com/v1/data:GET:::Could not load data (HTTP _#status: _#errmsg)}

Expected(on failure, e.g. Could not load data (HTTP 404: ...))

ActualCould not load data (HTTP

The fifth parameter (err) is returned instead of the response when the request fails. The token _#status is replaced with the HTTP status code and _#errmsg with the error message, so you can show a useful message instead of a blank space.

virtual{include:disclaimer.html:fileman}

Expected(the contents of disclaimer.html from the slice file area)

type fileman reads a file from the current slice file area (its configured fileman_dir) and returns its contents. Use site to read from the site-wide file area, or readfile to read a path relative to the web document root.

virtual{include:https#://www.example.com/render.php?URL_PARAMETERS}

Expected(the body returned by render.php, called with the current query string)

The literal text URL_PARAMETERS inside fn is replaced with the current pages query string before the request is made, so the included script receives the same parameters as the current page.

← All expressions