if the URL is simply give in the form:

	/htdb  or
	/htdb/page.html

then HTDB will look into the default document 'site.htdb' for the
corresponding *.html definition.  if no explicit *.html is
specified in the URI, then HTDB will look for the definition
for "index.html" within site.htdb.  in this manner, there's no
such thing as a 404 in htdb - failed pages will default back
for "index.html" in "site.htdb"

if the url is given in the form:

	/htdb/buh  or
	/htdb/buh/page.html

then HTDB will look into the document 'buh.htdb' for the
corresponding *.html definition.  same rules as above apply.

*.htdb files are comprised simply of a sequence of "#define ..." blocks.

each define is then able to be used within other resources.  the order
of definion is not important.  in this way, multiples pages worth of
html documents may be contained in a single .htdb file.

so - an .htdb file is a sequence of #define blocks.  defined things
may either be document definitions, or may be smaller things which may
later be used to build up a document.  defined "things" are known as
"resources"

a resource is used thus:

	#define	message	hello world

and accessed:

	${message}

scripted functions are defined thus:

	#define	function()
		logic...

and accessed:

	${function()}

if/then/else/endif...


all HTDB logic statements (currently) are on lines which start with "#live":
(yes, it is ugly, but the plan is to migrate to full XML-stylee syntax someday)

	#live	if (defined(message))
		${mesage}
	#live	else
		no message available
	#live	endif

or

	#live	if (getval(_current_month) == Jan)
		1st month of the year
	#live	endif

one note:

	"=" means "exactly matches"
	"==" means "contains the string"

if HTDB detects that both the LH and RH of the equality are numbers,
then it uses numeric comparisions.

loop:	(#live MUST be followed by a TAB)

	#live	loop(x, 1, 10)
		${x}<br>
	#live	endloop

prints 1 through 10.

database access:

	#live	if (sql(res:select page_id, resource from session limit 2))
	#live	endif

using the "sql()" DSO calls the database and places a "hash" of results into
a result set prefixed by the string before the colon, in this case "res".

in essence, the following happens:

	#define	res[1]->page_id		1
	#define	res[1]->resource	htdb/index.html
	#define	res[2]->page_id		2
	#define	res[2]->resource	htdb/ttg
	#define	res->numResults		2

how do you walk through things like that?  you could use loop:

	#live	loop(x, 1, ${res->numResults})
		page_id #${x}: ${res[${x}]->page_id}<br>
		resource #${x}: ${res[${x}]->resource}<p>
	#live	endloop

or, you can use the "while" construct:

	#live	while (x = res[*]->page_id)
		page_id #${x}: ${res[${x}]->page_id}<br>
		resource #${x}: ${res[${x}]->resource}<p>
	#live	endwhile

that's pretty much it for the logic.  very simple.

everything else is built upon DSO functions.  ${eval()} does math functions.
there's a whole slew of date/time functions.  see dso_funcs.c for all your
options.  there's stuff to convert things into braille and morse code, too.

oh yeah - encryption.  most CGIs, as you're aware, use GET args to pass parameters
into the cgi programs.  suppose you don't want the world to see your args?

encrypt them!  HTDB will automatically decrypt them when it goes to the next page:

	<a href="..../htdb?${encrypt(CC=5555-1111-3333-1909&user_id=3)}">place my order!</a>

will make everything after the question mark into an encrypted mess (using the value of
${confFilter[3]->key} as the encryption key).  on the receiving end, you simple
ask for the values of "${CC}" and "${user_id}" and go on your merry way - they're
already decrytpted!  see the feedback.htdb file for extensive use of this sort of thing.

more later
-david
Sat Apr 24 13:07:31 PDT 2004
