File: adp-overview.html

package info (click to toggle)
aolserver4 4.5.1-12
links: PTS, VCS
area: main
in suites: squeeze
size: 11,768 kB
ctags: 14,788
sloc: ansic: 45,120; tcl: 5,532; sh: 1,021; makefile: 379; pascal: 219; php: 13
file content (722 lines) | stat: -rw-r--r-- 16,988 bytes
parent folder | download | duplicates (8)
<html>
<head>
<title>AOLserver</title>
</head>
<body>

<h1>AOLserver ADP Development</h1>

<p>

<p>
$Header: /cvsroot/aolserver/aolserver.com/docs/devel/tcl/adp-overview.html,v 1.1 2002/03/09 02:26:03 kriston Exp $
<p>

<p>

<a href=../tcl/api/>AOLserver Tcl API Reference</a>

<p>

<a href=http://tcl.activestate.com/man/>Tcl Language Manuals</a>

<p>

<a href=../tech/standards.html>AOLserver Engineering Standards Manual</a>

<p>

<a href=#1>What Are ADPs?</a>

<p>

<a href=#2>When to Use ADPs</a>

<p>

<a href=#3>When to Use Tcl Libraries</a>

<p>

<a href=#4>Configuring ADP Processing</a>

<p>

<a href=#5>Building ADPs</a>

<p>

<a href=#6>Debugging ADPs with TclPro</a>

<p>

<a href=#7>ADP Syntax</a>

<p>

<a href=#8>Registered ADP Tags</a>

<p>

<a href=#9>ADP Parsers</a>

<p>

<a href=#10>Example ADPs</a>

<p>


<h2><a name=1>What Are ADPs?</a></h2>

<p>

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.

<p>


<h2><a name=2>When to Use ADPs</a></h2>

<p>

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.

<p>

Here are some examples of applications you can use ADPs for:
<p>
 * Returning HTML conditionally

<p>

<p>
  * Retrieving information from a database to use in a page 

<p>
  * Inserting information from a form into a database
<p>


<h2><a name=3>When to Use Tcl Libraries</a></h2>

<p>

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.

<p>

<p>
  * 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.

<p>

<p>
  * 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.

<p>

<p>
  * 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.

<p>

<p>
  * 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.

<p>

<p>
  * 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.

<p>


<h2><a name=4>Configuring ADP Processing</a></h2>

<p>

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.

<p>

 Required Configuration Parameters

<p>


<p>
  * 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.

<p>

<p>
  * If you want to register your own ADP tags, you must set the Fancy
 parameter to On. It also allows you to use the <server> ...
 </server> ADP syntax and determine whether ADP tags can be
 registered after startup.

<p>

 List of Configuration Parameters

<p>

The following table describes all the parameters that can be set
within the ADP section of the configuration file:

<p>

 ns/server/servername/adp

<p>

Parameter

<p>

Default Value

<p>

Description
Cache 

<p>

on

<p>

Boolean value. If set to on, ADP caching is enabled.
DebugInit

<p>

"ns_adp_debuginit"

<p>

The procedure to run when debugging begins.
EnableExpire

<p>

off

<p>

Boolean value. If set to on, the "Expires: now" header is set on all
outgoing ADPs.
EnableCompress 

<p>

off

<p>

Boolean value. If set to on, extraneous spaces within an HTML page are
removed.
EnableDebug 

<p>

off

<p>

Boolean value. If set to on, appending "?debug" to a URL will enable
TclPro debugging.
Fancy 

<p>

on

<p>

Boolean value. If set to on, "fancy" ADPs are enabled, meaning that:
the TagLocks parameter is enabled the <server>...</server> syntax is
enabled the ns_register_adptag and ns_adp_registertag commands are
enabled registered ADP tags are enabled
Map

<p>

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.

<p>

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"

<p>

StartPage

<p>

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 

<p>

off

<p>

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.

<p>

If set to off, ADP tags can only be registered before the first ADP is
served.

<p>


<h2><a name=5>Building ADPs</a></h2>

<p>

 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.

<p>

  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.

<p>

 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 &lt;SCRIPT&gt; or &lt;% ...%&gt;
 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.

<p>


<h2><a name=6>Debugging ADPs with TclPro</a></h2>

<p>

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=<pattern> 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.

<p>

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

<p>


<h2><a name=7>ADP Syntax</a></h2>

<p>

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.

<p>

Insert Tcl commands between any of the following sets of HTML tags:

<p>

<p>
  * &lt;script language=tcl runat=server stream=on>

<p>

  ... 

<p>

  </script>

<p>

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.

<p>

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.

<p>

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.

<p>

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.

<p>

<p>
  * &lt;% ... %&gt;

<p>

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.

<p>

<p>
  * &lt;%= ... %&gt;

<p>

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.

<p>


<h2><a name=8>Registered ADP Tags</a></h2>

<p>

You can define your own ADP tags with the ns_adp_registertag or the
ns_register_adptag Tcl functions.

<p>

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.

<p>


<h2><a name=9>ADP Parsers</a></h2>

<p>

An ADP parser implements a specific syntax for ADPs. Two ADP parsers
are pre-defined for AOLserver:

<p>

<p>
  * adp: The "adp" parser handles only the &lt;% ... %&gt; syntax and the
 &lt;%= ... %&gt; syntax for ADPs. This parser offers the best
 performance.
 fancy: The "fancy" parser handles the &lt;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.

<p>

You can register additional ADP parsers using the Ns_AdpRegisterParser
C API function.

<p>

 Configuration

<p>

To configure ADP parsers, set parameters in two configuration file
sections as follows:
 1. Map parsers to file extensions in the
<pre>
 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"
</pre>

<p>

  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.

<p>

 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:

<pre>
 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"
</pre>

<p>

  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.

<p>

For more information on configuring ADPs, see the ADP configuration
file sections starting on page page 56 of the AOLserver
Administrator's Guide.

<p>


<h2><a name=10>Example ADPs</a></h2>

<p>

This section contains the following ADP examples:

<p>

 Example 1: Return partial HTML page conditionally
<br>
 Example 2: Return full HTML page conditionally
<br>
 Example 3: Return information from the database
<br>
 Example 4: Get form information and insert into the database
<br>
 Example 5: ADP sampler with includes, recursion, and streaming
<br>

<p>

 Example 1: Return partial HTML page conditionally

<p>

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

<p>
<a href=example1.adp.txt>example1.adp.txt</a>
<p>

 Example 2: Return full HTML page conditionally

<p>

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.

<p>

This is the cookbook.html file containing the form:

<p>
<a href=example2a.adp.txt>example2a.adp.txt</a>
<p>


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

<p>
<a href=example2b.adp.txt>example2b.adp.txt</a>
<p>

The cookset.html file contains a frame set for the cookbook. The
cook.html file contains the cookbook without frames.

<p>


Example 3: Return information from the database

<p>

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.

<p>

The first ADP, db.adp, creates a form with a select box with the list
of database tables:

<p>
<a href=example3a.adp.txt>example3a.adp.txt</a>
<p>

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

<p>
<a href=example3b.adp.txt>example3b.adp.txt</a>
<p>

 Example 4: Get form information and insert into the database

<p>

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.

<p>

Here is the survey.html file, which consists of a simple form and a
submit button which calls an ADP:

<p>
<a href=example4a.adp.txt>example4a.adp.txt</a>
<p>

<p>

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:

<p>
<a href=example4b.adp.txt>example4b.adp.txt</a>
<p>


 Example 5: ADP sampler with includes, recursion, and streaming

<p>

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.

<p>
<a href=example5a.adp.txt>example5a.adp.txt</a>
<p>

The standard-header file referenced in the above example looks like
this:
<p>This is a standard header.

<p>

The time.adp file referenced in the example looks like this:
 <p>The time is: &lt;%=[ns_httptime [ns_time]]%&gt;<p>

<p>

Because of the streaming used in the last script, the "1...", "2...",
"3!" and "End" part of the page will be displayed gradually.

<p>

</body>
</html>