NAME¶
ns_adp - ADP introduction and operation
DESCRIPTION¶
Several commands, normally beginning with the
ns_adp prefix, are used to
support
AOLserver Dynamic Pages, or
ADP's. ADP's are a
server-side environment for embedding Tcl code within static text blocks
(typically HTML or XML). The Tcl code is normally delimited within
<% and
%> or
<%= and
%> tags and can
be used to generate additional text or for any other purpose, e.g., updating a
database. The
<% ...script... %> is used for cases where the
result of the Tcl script is ignored while the
<%= ...script %>
syntax is used to append the script result to the output buffer. In either
case, the
ns_adp_puts command can be used to add content to the output
buffer. A simple ADP file could contain:
<html>
<head><title>Hello from <%=[ns_info hostname]%></title></head>
<body>
Time is: <%=[clock format [clock seconds]]%>
Four links:
<%
for {set i 0} {$i < 4} {incr i} {
ns_adp_puts "<a href=/link/$i.htm>Link $i</a><br>"
}
%>
</body></html>
Accessing this page would generate output similar to:
<html>
<head><title>Hello from jgdavidson.local</title></head>
<body>
Time is: Mon Aug 01 22:15:18 EDT 2005
Ten links:
<a href=/link/0.htm>Link 0</a><br>
<a href=/link/1.htm>Link 1</a><br>
<a href=/link/2.htm>Link 2</a><br>
<a href=/link/3.htm>Link 3</a><br>
</body></html>
ADP processing normally occurs in the context of an HTTP transaction when an URL
request is mapped to an ADP file in the server's page root. (see
ADP
CONFIGURATION below for details on configuring this mapping). The ADP
request processing code allocates a Tcl interpreter and includes the
cooresponding ADP file. Output generated during execution of the ADP is sent
as a normal HTTP response, using default status code of "200 OK" and
the mime type which corresponds to the ADP file extensions, normally .adp and
text/html (commands such as
ns_adp_mimetype can be used to control the
eventual response type).
An ADP can include additional ADP files with the
ns_adp_include command
or evaluate ADP text/script code directly with
ns_adp_eval. This
capability enables are large degree of reuse of presentation and code between
applications. Each such included file or ADP string evaluation is performed in
it's own
call frame similar to a Tcl procedure with a local variable
namespace. Arguments can be passed to new call frames and then accessed with
commands such as
ns_adp_argv. When necessary, commands such as
ns_adp_abort provide limited support to interrupt and/or return from
within an ADP, unwinding the ADP call stack to the underyling C-level request
processing code.
CONFIGURATION¶
AOLserver can be configured to execute ADP's placed with other static files
within a virtual server's pages directory via the
map parameter in the
adp server config section, for example:
ns_section ns/server/server1/adp
ns_param map /*.adp
ns_param map {/stories/*.adp 60}
The first map will evaluate all files which end in
.adp and do not have
more specific mappings (such as the second map). The second config map will
execute files which end with
.adp located under the
/stories
directly and also specifies a cache timeout in seconds. In this case, results
will be retained and returned to subsequent requests without re-executing the
ADP for up to 60 seconds (see the
-cache paramter to the
ns_adp_include command for more details).
Alternatively, arbitrary URL's may be mapped to individual ADP files using the
ns_register_adp command. This command would normally be included in a
virtual-server initialization scripts within the
modules/tcl/ server
subdirectory.
ERROR HANDLING AND EXCEPTIONS¶
By default, errors within an ADP script block are reported in the server log and
interrupt execution of the current block only; subsequent text and script
blocks continue to be processed and and no error message is included in the
output. This approach is highly defensive and has the benefit of generating a
valid, if partial, responses after minor errors. A negative aspect of this
approach is that, without careful monitoring of the server log, such errors
can easily be ignored.
The default error handling behavior can be modified by settings one or more
virtual-server configuration flags:
ns_section ns/server/server1/adp
ns_param stricterror false; # Interrupt execution on any error.
ns_param displayerror false; # Include error message in output.
ns_param detailerror true; # Include connection details messages.
These flags, along with other options, can be queried or modified for an
individual ADP execution stream via the
ns_adp_ctl.
SCRIPT BLOCK SCOPE¶
By default, each Tcl block is independent of other blocks and must be a complete
script. In particular, this means that conditional code cannot span blocks,
e.g., the following does not work by default:
<% foreach elem $list { %>
Here is an <%=$elem%> element.
<% } %>
This behavior can be changed with the
singlescript config option or via
the
ns_adp_ctl command which instructs the ADP parser to converts all
text/code blocks within an ADP into a single Tcl script block:
ns_section ns/server/server1/adp
ns_param singlescript false; # Combine code blocks into one scripts.
Setting this option would covert the script above into the following equivalent:
<% foreach elem $list {
ns_adp_puts -nonewline "\n Here is an "
ns_adp_puts -nonewline $elem
ns_adp_puts -nonewline " element.\n"
} %>
Note that this option combines scripts within a particular ADP file, it does not
combine scripts which span multiple included ADP's. In addition, error
semantics described above apply to the combined script and any error within
any block combined into a single script will stop execution of the entire
included page.
BUFFER MANAGEMENT¶
Output including accumulated text blocks and output generated by Tcl script
blocks is normally buffered internally until the end of the connection. Once
complete, a single response is generated which follows HTTP response headers
indicating the resulting content length. The content may optionally be gzip
compressed first.
Alternatively, an incremental response can be be generated either in response to
calling the
ns_adp_stream or
ns_adp_flush commands or
automatically due to buffer overflow. In this case, an HTTP response will be
generated on the first flush which specifies incremental content using
HTTP/1.1 chunked-encoding. Forcing a connection into streaming mode can be
useful for certain long running requests where it's reasonable to expect the
browser can render incremental respnoses.
The size of the internal buffer and gzip compression options can be set with
corresponding server and ADP config options. Note both the virtual-server wide
gzip and ADP gzip options must be enabled to support compression of ADP
output.
ns_section ns/server/server1
ns_param gzip true; # Enable compression.
ns_param gziplevel 4; # Compression level.
ns_param gzipmin 4096; # Minimum size before gzip.
ns_section ns/server/server1/adp
ns_param gzip true; # Enable ADP output compression.
ns_param bufsize 102400; # Buffer size, 1meg default.
CHARACTER ENCODING¶
The ADP interface uses the server's mimetype configuration to map file
extensions to charsets and cooresponding encoding. This configuration is
necessary to ensure the file text and script blocks are properly coverted to
UTF-8 for use internally. This mimetype is also used to set the character
output encoding although the
ns_conn encoding option can be used to
override the encoding if necessary.
SEE ALSO¶
ns_adp_include(n), ns_adp_puts(n), ns_adp_ctl(n)
KEYWORDS¶
ADP, dynamic pages