ns_adp_include - Include and execute an ADP file
This command includes and executes an ADP file within the current ADP. The output produced by the included file, including static text and script output, is appended to the current output buffer.
ADP files can be nested by including each other up to a maximum depth (currently 256 levels).
This command is only available while processing an ADP file. To parse an ADP outside of an ADP context, use ns_adp_parse.
The included ADP is executed in a new ADP call frame with its own local variables, similar to a Tcl procedure. Additional arguments can be passed to the included ADP and accessed with ns_adp_argc, ns_adp_argv, and ns_adp_bind_args.
Include and execute the ADP file specified by filename. The file name may be absolute or relative to the current ADP working directory (i.e., the directory of the including file).
Specifies a time for caching the generated output. When caching is enabled, the complete output of the included ADP, including nested includes, is stored and reused for subsequent requests until the cache entry expires or is invalidated.
Disables caching for this include and any content generated within it, even if surrounding includes use caching.
The options -cache and -nocache can be combined to optimize performance for ADPs that mix static or shared content with dynamic or personalized content.
Selects the ADP tag set used while parsing the included ADP.
If -tagset is omitted, the include inherits the current effective tag set from the caller. This is the normal behavior and means that included ADPs are parsed with the same registered-tag vocabulary as the including ADP.
If -tagset default is specified, the include uses the built-in server-wide default ADP tag table for this include only.
If -tagset name is specified with a named tag set, that tag set is used for this include only. After the include completes, the previous effective tag set is restored.
The effective tag set is part of the identity of parsed ADP code. When ADP files are cached, the same file parsed under different named tag sets is cached separately.
Treats the specified filename as a Tcl script and wraps it on the fly as an ADP page.
Include another ADP file:
### ### Example: ADP file "a.adp" includes ADP file "b.adp" ### # In a.adp: begin of a.adp<br> <% ns_adp_include b.adp %> end of a.adp<br> # In b.adp: begin of b.adp<br> ...<br> <% ns_adp_puts "Hello, world!" %><br> ...<br> end of b.adp<br>
Passing arguments to an included ADP:
# In a.adp:
begin of a.adp<br>
<% ns_adp_include b.adp 1 2 3 %>
end of a.adp<br>
# In b.adp:
begin of b.adp<br>
...<br>
<% ns_adp_puts "Arguments: [ns_adp_argv]" %><br>
<%
ns_adp_bind_args x y z
ns_adp_puts "x=$x y=$y z=$z" ;# => {x=1 y=2 z=3}
%>
...<br>
end of b.adp<br>
Include an ADP using a named tag set:
ns_adp_tagset create -fallback default transformed-adp <% ns_adp_include -tagset transformed-adp fragment.adp %>
Force the built-in default tag table for an included legacy fragment:
<% ns_adp_include -tagset default legacy-fragment.adp %>
Use caching with an explicitly selected tag set:
<% ns_adp_include -cache 10m -tagset transformed-adp fragment.adp %>
The -tagset option is scoped to the current include operation. An included ADP without -tagset inherits the caller's current effective tag set. An included ADP with -tagset temporarily overrides the effective tag set, and the previous effective tag set is restored after the include returns.
This makes it possible to mix legacy and migrated ADP fragments in one request. For example, a page parsed with a legacy tag set can include a fragment parsed with a new tag set, or a page parsed with a new tag set can include a legacy fragment using -tagset default.
The parsed representation of an ADP file depends on the registered tags available while parsing. Therefore, when a named tag set is effective, NaviServer keeps parsed ADP cache entries separate from the same file parsed under the default tag table or under another named tag set.
This prevents cached ADP code parsed with one tag set from being reused under a different tag set. For more background about ADP, see ADP Overview.
ns_adp, ns_adp_abort, ns_adp_append, ns_adp_argc, ns_adp_argv, ns_adp_bind_args, ns_adp_break, ns_adp_debug, ns_adp_dir, ns_adp_dump, ns_adp_exception, ns_adp_mimetype, ns_adp_parse, ns_adp_puts, ns_adp_register, ns_adp_return, ns_adp_stats, ns_adp_tagset, ns_adp_tell, ns_adp_trunc, ns_time