ad_register_filter
and ad_register_proc
rather than
ns_register_filter
and ns_register_proc
!
ReturnHeaders
/ns_write
/ns_return
shortly.
ad_register_*
changes, you are merely encouraged,
not required, to use the new APIs. As of 4.0 (and all code integrated into
ACS as packages) you will need to use the new APIs. The next few months
will be a transitional period.
/packages
directory (at the very top of the directory tree, right
alongside /tcl
and /www
. The idea is to divide ACS into a series of
functional components, "packages," with each package mapped to its own
directory inside the /packages
directory. The ACS core package
(/packages/acs-core
) provides the very basic functionality expected
of an ACS system.
It is outside the scope of this document to describe how to develop a package
(but if you're interested, see the APM
documentation or the 5-Minute Guide to
Packaging Your Module)
We're not asking anyone to build packages yet - just keep developing as you always have
been for now, in the same directories, but know that a lot of files you might expect to see
in /tcl
, /www/doc/sql
, etc. have been moved inside the ACS core
package (/packages/acs-core
).
The package manager UI can be accessed at http://yourservername.com/admin/apm/ (site-wide administrators only).
.tcl
file in tho /tcl
directory. This still occurs, but very importantly, the
0-acs-init.tcl
script is sourced first. The entire startup process
(discussed in detail in the Bootstrapping) is:
/tcl/0-acs-init.tcl
.
0-acs-init.tcl
sources /packages/acs-core/bootstrap.tcl
.
bootstrap.tcl
sources all *-procs.tcl
files in the acs-core
package.
bootstrap.tcl
scan all directories inside the /packages
directory,
looking for package specification files (*.info
files) which describe packages.
If it finds any new ones, it loads them into the database.
bootstrap.tcl
sources the *-procs.tcl
files for all enabled packages.
bootstrap.tcl
sources the *-init.tcl
files for all enabled packages.
/tcl
directory (i.e., every file
after 0-acs-init.tcl
in lexicographical order).
*-procs.tcl
and *-init.tcl
files is necessary to
*-procs.tcl
) and
initialization code that should truly be called only once (*-init.tcl
).
/www
directory), as in the case of pages associated with
packages.
ns_register_proc
s for each
possible URL prefix (/groups
, /some-group-type
,
/some-group-name
, etc.).
/download/files/
won't work for requests
under /groups/some-group-name/download/files/62/smug.jpg
).
rpp_handler
in /packages/acs-core/request-processor-procs.tcl
), described
in detail in the request processor documentation.
We have replacement routines for ns_register_filter
and
ns_register_proc
, called ad_register_filter
and
ad_register_proc
respectively, which solve the first four problems:
www
and admin-www
directories.
ad_register_filter
has a -priority
flag. Filters with numerically lower
priorities run before filters with numerically higher priorities.
We'll solve the latter two problems as soon as subcommunities are implemented for 4.0.
Important: You must usead_register_filter
andad_register_proc
rather than the correspondingns_
calls.ns_register_filter
andns_register_proc
are disabled in the release version of ACS 3.3.
ns_db
is being phased out (although we're not deprecating ns_db
yet
- you can continue to use it).
That's right, we're providing a new Database Access API
which totally frees you from the responsibility of allocating database handles and passing
them around to subroutines. For instance, instead of
you can now just writeset db [ns_db gethandle] set selection [ns_db select $db "select foo, bar from greeble"] while { [ns_db getrow $db $selection] } { set_variables_after_query append output "<li>foo=$foo; bar=$bar\n" } ns_db releasehandle
Not a database handle (db_foreach "select foo, bar from greeble" { append output "<li>foo=$foo; bar=$bar\n" } db_release_unused_handles
$db
) in sight; the database handles are managed and
recycled for you. Don't worry, this actually does work (despite the many incredulous
emails we've received): the entire package manager was written with it and works without
a hitch.
See the Database Access API documentation for more information, including a discussion of why this is A Good IdeaTM.
ReturnHeaders
, ns_write
, ns_return
, and friends!
From Building Documents in ACS (philg, jsalz):
Standard AOLserver programming, like CGI scripting before it, had the programmer directly writing bytes to a client browser connection. Thus from 1995 through 2000 an AOLserver programmer would build up a complete HTML page in a script and write the bytes of that page to the client either all at once withThe basic idea is that, in Tcl scripts, you now usens_return
or incrementally withns_write
.Problems with this standard old approach:
- difficult to control style on a site-global basis via a master template
- difficult to write a script that returns an XML document that is then rendered by a higher-level request processor (i.e., each individual script has to be aware of all possible document types that might be required by client, e.g., HTML, WML, XML, etc.)
- easy for novice programmer to create server performance problems by calling API procedures that block in the TCP stack while holding a database handle from the pool (i.e., a script could be waiting for a client on a slow modem to accept some packets while holding a database connection from a limited pool)
doc_set_property
to set the
title and navigational context for a document, and doc_body_append
(rather than ns_write
) to build up the body for the page (leaving out the
headers and footers) master template later builds a page for you, tacking on header,
title, navbar, footer, etc. as appropriate in a customizable way.
Don't worry, you don't need to start using this right away. But for more details, see Building Documents in ACS.