{require:libs:script:position}

Description

require declares a page dependency - a JavaScript library, a CSS stylesheet, or a snippet of JS to run after a library loads. It prints nothing where you write it; instead it registers the dependency, and the matching generate:HEAD and generate:FOOT commands emit the deduplicated script and link tags in the page head and foot. AA tracks each dependency by a hash, so requiring the same library from ten views loads it once. The first parameter, libs, is either a single name or path, or a JSON array of several. A bare word with no slash and no .js or .css extension (aa-jslib, tippy, select2 with a version like select2@4) is a built-in library AA knows how to load. A value ending in .css, or containing .css? or /css? (Google Fonts), becomes a stylesheet link; you may append a media type such as print. Anything else with a slash or a .js extension becomes a script tag, and you may append defer, async, or an SRI integrity hash. The second parameter, script, is JavaScript run once the libraries are ready - use it to initialise the library you just required. The third parameter, position, set to FOOT, loads the libraries at the end of the body instead of the head. require needs generate:HEAD and generate:FOOT present in your site template to have any visible effect. See css for adding a block of CSS code.

Parameters

libs optional default (empty)

One dependency or a JSON array of several. A built-in library name (aa-jslib, tippy, select2@4), a stylesheet (ends in .css, or has .css? or /css? for Google Fonts; append a media type like print), or a script (a path or a .js file; append defer, async, or an SRI integrity hash like sha256-...). A JSON array loads each entry, for example ["/css/a.css", "/js/b.js"].

script optional default (empty)

JavaScript to run once the required libraries are loaded. Use it to initialise the library you just required, for example calling tippy(...) or lightGallery(...). Runs in the page, after the libs are ready.

position optional default (empty)

Where the libraries load. Empty (the default) loads them in the head; FOOT loads them at the end of the body, before generate:FOOT. Only affects the libs, not the script.

Allowed values FOOT (load before generate:FOOT, at the end of the body) or empty (the default, load in the head).

Examples

test[{require:aa-jslib}]
Expected[]
Actual[]
A bare name with no slash and no extension is a built-in library AA knows how to load (here the AA jQuery helpers). require prints nothing - the empty brackets show its output is empty; the library is queued for generate:HEAD. Add a version like aa-jslib@2 to pin one.
test[{require:/js/site.js}]
Expected[]
Actual[]
A path or a value ending in .js becomes a script tag in the head. Output is still empty; the tag is emitted by generate:HEAD.
test[{require:/js/site.js defer}]
Expected[]
Actual[]
Append defer (or async) after the path and it lands on the script tag. Output stays empty.
test[{require:/css/print.css print}]
Expected[]
Actual[]
A value ending in .css becomes a stylesheet link. A trailing word like print sets the media attribute, so this sheet applies only when printing.
test[{require:["/css/site.css", "/js/site.js"]}]
Expected[]
Actual[]
The first parameter can be a JSON array; each entry is queued by its own rule (the .css becomes a link, the .js a script). One require call, several dependencies.
test[{require:tippy:tippy('.tip')}]
Expected[]
Actual[]
The second parameter is JavaScript that runs once the library is loaded - here tippy is required, then started on the .tip elements. A literal colon inside the script would be read as a parameter separator; escape it as #: . Curly braces in the script must be wrapped in deferred-eval {- ... } so AA does not treat them as commands.
test[{require:datatable@1::FOOT}]
Expected[]
Actual[]
The third parameter FOOT loads the library at the end of the body (before generate:FOOT) instead of the head. The empty middle parameter means no init script. Use FOOT for heavy libraries that do not need to block rendering.
test[{require:https#://cdn.example.org/lib.min.js sha256-ri1AEoNtgONXOIJ0k7p9HoQHGq6MEDsjPPYZh7NWpu0=}]
Expected[]
Actual[]
For an external script, escape the colon in https:// as https#:// so AA does not read it as a parameter break, then append an SRI integrity hash (sha256-... or sha384-...) so the browser verifies the file. defer and async may be appended too.
virtual{require:/css/site.css}
Expected(empty here; require registers the file, and the {generate:HEAD} placeholder later emits its link tag into the page head)
require only registers a dependency; generate:HEAD and generate:FOOT are what actually emit the tags. Sketch of the result: the head ends up with <link rel="stylesheet" href="/css/site.css">. Because the real output depends on every require on the page and on AA version, this example is illustrative, not asserted.
← All expressions