AOLserver ADP Development

$Header: /cvsroot/aolserver/aolserver.com/docs/devel/tcl/adp-overview.html,v 1.2 2002/09/26 19:51:33 kriston Exp $

AOLserver Tcl API Reference

Tcl Language Manuals

AOLserver Engineering Standards Manual

What Are ADPs?

When to Use ADPs

When to Use Tcl Libraries

Configuring ADP Processing

Building ADPs

Debugging ADPs with TclPro

ADP Syntax

Registered ADP Tags

ADP Parsers

Example ADPs

What Are ADPs?

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.

When to Use ADPs

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

When to Use Tcl Libraries

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.

Configuring ADP Processing

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 ... ADP syntax and determine whether ADP tags can be registered after startup.

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 ... syntax is enabled the ns_register_adptag and ns_adp_registertag commands are enabled registered ADP tags are enabled Map

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.

Building ADPs

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.

Debugging ADPs with TclPro

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= query string in addition to any other query data you may send. AOLserver will then trap on ADP files matching the pattern. For example, you can just use debug=*.adp to trap all files, or you can use debug=someinclude.inc file to trap in an included file.

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=" query argument.

ADP Syntax

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.

Registered ADP 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.

ADP Parsers

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

 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"

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:

 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"

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.

Example ADPs

This section contains the following ADP examples:

Example 1: Return partial HTML page conditionally
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

Example 1: Return partial HTML page conditionally

This ADP example tests for various browsers and returns a different message in each case.

example1.adp.txt

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:

example2a.adp.txt

This is the ADP, cookbook.adp, that determines the response and displays the appropriate page:

example2b.adp.txt

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:

example3a.adp.txt

The second ADP, db2.adp, is used as the POST from the first ADP:

example3b.adp.txt

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:

example4a.adp.txt

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:

example4b.adp.txt

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.

example5a.adp.txt

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.