{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 or 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 with GET, or with POST when data is given; ajax adds the X-Requested-With header. fileman reads a local file from the File Manager directory of the current slice (its fileman_dir), only below that directory: never a file of the AA installation, a dotfile such as .htaccess, a script, a settings or key file, a dump or a backup. A refused file prints nothing and is listed in State Check under Refused file reads. The types readfile and site were removed in November 2026: they print nothing, and State Check names the slice or site whose template still uses them. Include such a file by its full web address instead, or move it into the File Manager directory of the slice and use fileman. If fn is empty nothing is fetched and the result is empty. Only a 2xx answer counts: its body is returned. Redirects are followed (up to 10), and a request waits at most 30 seconds. Addresses in private, loopback and other reserved ranges (127.0.0.1, 10.x, 192.168.x and the like) are refused, also after a redirect, and so is a host name that does not resolve - _#errmsg then says the host is blocked. 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 a short error message - never with the body of the failed answer. With http and ajax only, a relative fn is fetched from this same server with the visitor cookies passed on, and the literal URL_PARAMETERS inside fn is replaced with the current query string; the method types (GET, POST, ...) take fn as written and need a full URL. 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 and ajax this is the URL (a literal URL_PARAMETERS in it is replaced with the current query string); for fileman it is a path inside the File Manager directory of the slice, such as parts/menu.html.

type optional default http

Where or how to fetch fn. Default http. HTTP fetch: http and ajax use GET, or POST when data is given; ajax adds the X-Requested-With header. HTTP methods (send data and headers): GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD. Local file read: fileman. readfile and site were removed in November 2026 and print nothing. An unknown type returns nothing.

headers optional

Request headers as a JSON object, e.g. built with jsonasoc. Used by every HTTP type - http and ajax too. Empty means no extra headers.

data optional

Request body. With the method types it is sent as is; with http or ajax a non-empty body turns the request into a POST. When the headers set no Content-Type, the body is sent as a form (application/x-www-form-urlencoded). Empty means no body.

err optional

Text returned instead of the response when the request fails (no answer, or a status other than 2xx). Inside it _#status is replaced with the HTTP status code (empty when no answer came) and _#errmsg with a short message - HTTP and the status, or the reason the request got no answer; the body of the failed answer is never put in. A colon inside err must be written as #: or it ends the parameter. 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, fileman, GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD) include returns an empty string without fetching anything. The removed types readfile and site print nothing too.
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 (_#errmsg)}
Expected(Could not load data (HTTP 404) when the API answers 404; when no answer comes at all, the reason instead of HTTP 404)
ActualCould not load data (No answer from https://api.example.com/v1/data - Host "api.example.com" is blocked for "https://api.example.com/v1/data".)
On failure the err text replaces the response. _#errmsg is HTTP and the status code, or the reason when the server did not answer; _#status is the bare code. Write a colon inside err as #: - a bare colon ends the parameter and cuts the message.
virtual{include:disclaimer.html:fileman}
Expected(the contents of disclaimer.html from the slice file area)
type fileman reads a file from the File Manager directory of the current slice (its configured fileman_dir) and returns its contents. Only a file below that directory is read - never ../, a dotfile, a script or a settings or key file. To include a file from elsewhere use its full web address; readfile and site no longer read anything.
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.