$Header: /cvsroot/aolserver/aolserver.com/docs/devel/tcl/adp-overview.html,v 1.1 2002/03/09 02:26:03 kriston Exp $
AOLserver Engineering Standards Manual
Probably the easiest way to make AOLserver output dynamic content is to embed a Tcl script in an HTML page with AOLserver Dynamic Pages (ADPs). ADPs are HTML pages that are parsed and run on the server when the page is accessed. ADPs contain HTML tags and Tcl scripts that are embedded within the HTML tags. The embedded Tcl scripts can call other Tcl scripts that reside in separate files, allowing you to reuse Tcl code.
ADPs are ideal in situations where you want to generate all or part of a specific page dynamically. You can re-use code by storing Tcl scripts in Tcl libraries and invoking them from within multiple ADPs. You can also include files and parse other ADPs from within your ADPs.
Here are some examples of applications you can use ADPs for:
* Returning HTML conditionally
* Retrieving information from a database to use in a page
* Inserting information from a form into a database
The alternative to embedding Tcl scripts in HTML pages using ADPs, is to store Tcl scripts in Tcl libraries and register them to handle specific URLs or URL hierarchies. There are some situations, such as those listed below, that are better suited to the Tcl libraries approach.
* Inheritance: If you want one Tcl script to handle an URL and all of its sub-URLs, it's better to store the script in a Tcl library and register it using ns_register_proc to handle an URL hierarchy. For example, you may want to manage a server domain name change by redirecting every response to the corresponding domain name on another server.
* Special Extenstions: If you want one Tcl script to handle all files with a specific extension, like /*.csv, you would register the script with ns_register_proc to handle those files.
* Scheduled Procedures: If you want a Tcl script to be run at specific intervals, you can use the ns_schedule_* functions to run a script from the Tcl library at scheduled intervals. These procedures do not normally involve returning HTML pages and so are not well suited to ADPs.
* Filters: If you want a Tcl script to be called at pre-authorization, post-authorization, or trace time for a group of URLs, you would register a filter using the ns_register_filter function.
* Re-using Tcl Scripts: If there are Tcl scripts that you want to use in multiple situations, you can store them in a Tcl library and invoke them from within any ADP or Tcl script.
Since you will be creating HTML pages that contain Tcl scripts, you will need to specify which pages the server will need to parse for Tcl commands and process.
Required Configuration Parameters
* Use the Map configuration parameter to determine which files are to be processed. For example, you can specify that all files with the .adp extension are to be processed by the server. Or, you can specify that all files that reside in a certain directory (for example, /usr/pages/adp) will be processed.
* If you want to register your own ADP tags, you must set the Fancy
parameter to On. It also allows you to use the
List of Configuration Parameters
The following table describes all the parameters that can be set within the ADP section of the configuration file:
ns/server/servername/adp
Parameter
Default Value
Description Cache
on
Boolean value. If set to on, ADP caching is enabled. DebugInit
"ns_adp_debuginit"
The procedure to run when debugging begins. EnableExpire
off
Boolean value. If set to on, the "Expires: now" header is set on all outgoing ADPs. EnableCompress
off
Boolean value. If set to on, extraneous spaces within an HTML page are removed. EnableDebug
off
Boolean value. If set to on, appending "?debug" to a URL will enable TclPro debugging. Fancy
on
Boolean value. If set to on, "fancy" ADPs are enabled, meaning that:
the TagLocks parameter is enabled the
The Map parameter specifies which pages the server will parse. You can specify a file extension (such as /*.adp) or a directory (such as /usr/pages/adp). If no directory is specified, the pages directory is assumed. The wildcards * ? and [] can be included in the Map specification. You can specify multiple Map settings.
The following example specifies that all files in the pages directory with the extensions .adp or .asp will be parsed, and all files in the /usr/pages/myadps directory will be parsed. Map "/*.adp" Map "/*.asp" Map "/usr/pages/myadps"
StartPage
The file to be run on every connection instead of the requested ADP. It can be used to perform routine initialization. It would then usually include the requested ADP by calling: ns_adp_include [ns_adp_argv 0] TagLocks
off
Boolean value. If set to on, ADP tags may be registered after server startup. Pages will be served less quickly when this is turned on.
If set to off, ADP tags can only be registered before the first ADP is served.
1. Create an HTML page. Use an HTML editor or a file editor to create an HTML page. Be sure to either name the file with the correct extension or save it in the correct directory on your server as specified by the Map parameter setting.
If you plan to use the Tcl script to return part or all of the page's content, just omit that part of the page, but you can create all of the surrounding HTML.
2. Add your Tcl scripts with a file editor. Insert your Tcl scripts in the HTML file where you want them to be processed. Be sure to enclose each Tcl script using one of the <SCRIPT> or <% ...%> syntaxes . Save the HTML file. 3. View the HTML page in a browser. Visit the page you have created in a browser to see if the Tcl scripts work correctly. If you have set the EnableDebug parameter, you can append "?debug" to the URL to enable TclPro debugging. 4. Continue editing and viewing until it works correctly. Continue editing the page in a file editor, saving it, and refreshing it in a browser until it works the way you want it to.
To debug your ADPs with TclPro, follow these steps:
1. Download and install TclPro from http://www.scriptics.com/tclpro/.
Temporary licenses are available.
2. Copy the prodebug.tcl file from the TclPro distribution to the
modules/tcl directory.
3. Set the EnableDebug parameter in the ns/server/servername/adp
section of the configuration file to On.
4. Run TclPro and start a "remote project", which puts TclPro into a
mode waiting for AOLserver to connect.
5. Open an ADP file with the ?debug=
To set a breakpoint in a procedure you'll have to "instrument"
the procedure either after the debugger traps the first
time or with the "dproc=
There are three different syntaxes you can use to embed a Tcl script
into an HTML page. Not all syntaxes are available with all ADP
parsers. You must be using the appropriate ADP parser to process a
specific syntax.
Insert Tcl commands between any of the following sets of HTML tags:
* <script language=tcl runat=server stream=on>
...
You must have the Fancy parameter set to On to use this
syntax. The contents of the script are interpreted using the Tcl
interpreter. The result is not inserted into the page, however. You
can use the ns_puts Tcl function to put content into the page.
The language=tcl attribute is optional. Future enhancements to ADPs
will include the capability to embed scripts in other scripting
languages, and you will be able to configure the default language. If
the language attribute is set to anything except tcl, the script will
not be processed, and a warning will be written to the log file.
The runat=server attribute is required. If this attribute is missing,
the script will not be processed. The runat=server attribute is
necessary so that client-side scripts are not executed accidentally.
The stream=on attribute is optional. If it is included, all output for
the rest of the page is streamed out to the browser as soon as it's
ready. Streaming is useful when your script may take a long time to
complete (such as a complex database query). Content is output to the
page gradually as the script is running. One disadvantage of streaming
is that the server cannot return a Content-length header with the
response. Content-length can speed up the connection, especially if
the connection is going through a proxy server.
* <% ... %>
This syntax is evaluated exactly the same as the first syntax, above,
except that you cannot specify any of the attributes. The language=Tcl
and runat=server attributes are implied. Streaming is not allowed with
this syntax, but output within this syntax will be streamed if
streaming was turned on in a previous script. This syntax can be used
inside HTML tags.
* <%= ... %>
The Tcl commands within these tags are evaluated as the argument to an
ns_puts command, which inserts the results into the page. This syntax
can be used inside HTML tags.
You can define your own ADP tags with the ns_adp_registertag or the
ns_register_adptag Tcl functions.
You must have the Fancy parameter set to On to use registered ADP
tags. You can also set the Taglocks parameter to prevent new
registered tags from being created after the first ADP has been
served.
An ADP parser implements a specific syntax for ADPs. Two ADP parsers
are pre-defined for AOLserver:
* adp: The "adp" parser handles only the <% ... %> syntax and the
<%= ... %> syntax for ADPs. This parser offers the best
performance.
fancy: The "fancy" parser handles the <script language=tcl
runat=server stream=on> syntax in addition to the other two
syntaxes. It also handles registered ADP tags. The TagLocks
parameter is enabled, and the ns_register_adptag and
ns_adp_registertag commands are enabled. This parser offers a
moderate performance degradation as compared to the "adp" parser.
You can register additional ADP parsers using the Ns_AdpRegisterParser
C API function.
Configuration
To configure ADP parsers, set parameters in two configuration file
sections as follows:
1. Map parsers to file extensions in the
The above configuration specifies that ADPs with the .adp
extension will be parsed using the "adp" parser, and ADPs
with the .fadp extension will be parsed using the "fancy"
parser.
2. Define a default parser in the ns/server/servername/adp section.
The default parser will be used for any ADPs with file extensions
not associated with a parser. For example:
ADPs with the .adp extension will use the "adp" parser, and ADPs
with the .fadp extension will use the "fancy" extension,
as described above. The default ADP parser will be the
"adp" parser. Since ADPs with the .inc extension are also
allowed, the "adp" parser will be used for those ADPs,
because no parser is associated with the .inc extension.
For more information on configuring ADPs, see the ADP configuration
file sections starting on page page 56 of the AOLserver
Administrator's Guide.
This section contains the following ADP examples:
Example 1: Return partial HTML page conditionally
Example 1: Return partial HTML page conditionally
This ADP example tests for various browsers and returns a different
message in each case.
Example 2: Return full HTML page conditionally
This example consists of a form, cookbook.html, that asks the user
whether they want to view a page with or without frames, and an ADP,
cookbook.adp, that determines the response and displays the
appropriate page, either the page with frames or the page without
frames.
This is the cookbook.html file containing the form:
This is the ADP, cookbook.adp, that determines the response and
displays the appropriate page:
The cookset.html file contains a frame set for the cookbook. The
cook.html file contains the cookbook without frames.
Example 3: Return information from the database
This example retrieves information from the database -- a list of
tables -- and returns it as the options in a select box. When the user
chooses a table from the list, another ADP is run as the POST for the
form which retrieves information from the database on the chosen
table.
The first ADP, db.adp, creates a form with a select box with the list
of database tables:
The second ADP, db2.adp, is used as the POST from the first ADP:
Example 4: Get form information and insert into the database
This is another database example, but one where the user types
information into a form, and the submit runs an ADP that enters the
information into the database. Then it sends an email message to both
the db administrator and the user that the record was updated. The
survey.html file contains the form and calls the survey.adp file as
the POST action.
Here is the survey.html file, which consists of a simple form and a
submit button which calls an ADP:
Here is the survey.adp file, which gets the form data from the survey,
inserts it into the database, sends email to the subscription
administrator and the user, and displays a confirmation message:
Example 5: ADP sampler with includes, recursion, and streaming
The following HTML is an example of a page containing several Tcl
scripts using the various ADP syntaxes. It invokes some Tcl functions,
includes a file, executes another ADP, and uses streaming.
The standard-header file referenced in the above example looks like
this:
This is a standard header.
The time.adp file referenced in the example looks like this:
The time is: <%=[ns_httptime [ns_time]]%>
Because of the streaming used in the last script, the "1...", "2...",
"3!" and "End" part of the page will be displayed gradually.
ADP Syntax
Registered ADP Tags
ADP Parsers
ns/server/servername/adp/parsers configuration file section. For
example:
ns_section "ns/server/server1/adp/parsers"
ns_param "adp" ".adp"
ns_param "fancy" ".fadp"
ns_section "ns/server/server1/adp"
ns_param "map" "/*.adp"
ns_param "map" "/*.inc"
ns_param "map" "/*.fadp"
ns_param "DefaultParser" "adp"
ns_section "ns/server/server1/adp/parsers"
ns_param "adp" ".adp"
ns_param "fancy" ".fadp"
Example ADPs
Example 2: Return full HTML page conditionally
Example 3: Return information from the database
Example 4: Get form information and insert into the database
Example 5: ADP sampler with includes, recursion, and streaming