Note:
This documentation is outdated and contains error, yet it gives a good
description of HTPL.
To INSTALL, see the INSTALL document.
1. What is HTPL?
2. What are the requirements for using HTPL?
3. How do I compile HTPL?
4. How does HTPL work?
5. Tutorial
5.1. Writing simple HTML
5.2. Embedding simple Perl commands
5.3. Interpreting forms
5.4. Simple internet functions
5.5. HTML generation functions
5.6. Reading a comma delimited file
5.7. Integrating an SQL database
6. Reference
6.1. HTPL library functions
6.2. HTPL result set
6.3. HTPL macros
6.4. HTPL directives
6.5. Writing your own macros
6.6. Additional information
1. What is HTPL?
HTPL (Hyper Text Programming Language, or just a lame monogram of HTML and
PERL) is a Perl based scripting tool for creating web content. It is
basically a wrapper to CGI. Anything HTPL can do can be basically done
with Perl and CGI, but HTPL provides rapid development tools. An HTPL file
is an HTML file with Embedded HTML. Additional commands can be added. (eg,
C, SQL), but all in all the web server runs a CGI script created from your
document.
Note: There are three other tools called HTPL. I have no connection with
them.
2. What are the requirements for using HTPL?
You must have CGI access on your account, be able to give local directives
to your web server (ie, .htaccess files on apache), be able to write
temporary files somewhere and preferably be able to install modules from
CPAN. (That can be done on your local directory. Modules can also be
transferred to the same path the HTPL binary resides in). Perl 5.004 or
later is required.
3. How do I compile HTPL?
To install type:
./configure
make
make install
make build
If you are the superuser, consider importing modules from CPAN by:
make CPAN
*IMPORTANT* * IMPORTANT* IMPORTANT* *IMPORTANT*
If you intend to install htpl as root, run configure as root!
*IMPORTANT* * IMPORTANT* IMPORTANT* *IMPORTANT*
4. How does HTPL work?
Anytime you access a htpl file the web server activates htpl.cgi as a cgi
script. Htpl.cgi reads the htpl file specified and converts it into a perl
script with the extension perl. (The file created can be run as a stand
alone CGI script, but you will not be able to use the redirect function
for document redirection or mime type settings). The perl file is then
executed. (Unless you used the XSUB extensions)
Once the perl file is created, htpl will not preprocess the source htpl
again but immediately execute the perl script; that is, unless the htpl
file is newer than the perl file, in which case the perl file will be
recreated according to the new version.
If you need to force reprocessing, update the htpl file or just “touch” it.
When creating an htpl documented with inline C code, htpl.cgi dumps the
embedded XSUB functions into a file, creates an installation module for it
and activates the usual compilation procedure. This can take a long time,
therefore you better add you C code only once fully functional.
When the script runs, its output is captured to a file, and only then
sent. This allows using the redirect function to redirect the browser even
if the script has already yielded output. Same is true for sending HTTP
cookies.
5. Tutorial
5.1 Writing simple HTML
Our first dcoument will display a very well known string.
Create the file hello.htpl in your web directory:
\n”;
#ENDIF
>
What happened here?
We connected to the database, and performed a SELECT query, into a result
set called customers.
We checked if the result set was empty. If it was not, we dumped the results.
According to the broad trend, you can access the database without writing
SQL code. (Obviously writing SQL code will provide many more options)
For example:
#SQL QUERY myquery mytable firstname lastname
Will provide the same as:
#SQL CURSOR myquery SELECT * FROM mytable WHERE firstname = ‘$firstname’ AND
lastname = ‘$lastname’
Important: HTPL assumes the new versions of DBI, therefore when using the
non script SQL access, you save the need to quote strings and to escape
quotes.
#SQL INSERT mytable firstname lastname email
Will be the same as:
#SQL EXEC INSERT INTO mytable (firstname, lastname, email) VALUES (‘$firstname’,‘$lastname’, ‘$email’)
5.8 Some more useful macros
Integrating a textual counter to your page as as easy as this:
people visited my page.
Random quotes were never easier:
Man existence must be some form of mistake.
Where do you want to go today
One world, no languages
Or usual switch statement:
#SWITCH CASE $s
#CASE 'abc'
&proc1();
#CASE 2 + $j
&proc2();
#END SWITCH
Or a random image:
6. Reference
6.1 HTPL Library functions
The source code for these functions is in the file htpl-lib.pl
&addheader(HTTP_HEADER)
Adds an HTTP header. Unavailable for converted scripts executed outside htpl.cgi.
&closedoc(HANDLE)
Closes file handle HANDLE and disposes the local copy if needed. To be used with &opendoc.
&doconnect(HANDLE, HOST, PORT)
Opens socket to HOST:PORT on handle HANDLE.
HANDLE should be used with &doread and &dowrite and not standard input/output funcation.
&doread(HANDLE)
Reads all the incoming data on a socket and returns as a scalar value.
&dowrite(HANDLE, BUFFER)
Writes the data on the scalar value BUFFER to the socket HANDLE.
&expect(HANDLE, REGEXP)
&expect(HANDLE, REGEXP, CODE)
Reads incoming data and matches against REGEXP. If successful, returns the regular expression
results. If not, calls the subroutine referenced by CODE where the input packet is passed to $_
&fileexists(FILENAME)
Checks if FILENAME exists. If FILENAME is a valid URL, checks if the URL exists.
&forkredirect
&forkredirect(LOCATION)
Redirects the browser to LOCATION while keeping the script running in background. Useful for batch
processing.
Redirection unavailable for converted scripts executed outside htpl.cgi.
If LCOATION is omitted, exits and returns the script output, while background copy still runs.
&getcc
Attempts to find the C compiler. Tries in the usual locations, unless the default has been edited in
htpl-config.pl.
&getmailprog
Attempts to find the mail program. Same mechanism as getcc.
&html_format(TEXT, TAGS)
&html_format(TEXT, TAGS, NONL, NOOUTPUT)
TAGS is a cons delmited list of HTML tags to apply, with no < > chars. TEXT is formatted with the
TAGS, while closing tags are added automatically.
Set NONL to true if you want all the output in one line.
Normally html_format yields the HTML code. Setting NOOUTPUT to true will make it only return the
code.
&html_header(TITLE)
Prints , and tags according to the TITLE supplied.
&html_hidden(FIELD)
&html_hidden(FIELD, VALUE)
&html_hidden(FIELD, VALUE, NOOUT)
Prints a hidden field. Usually used to transfer parameters between pages. If VALUE is
omitted, the value of the scalar variable with the name of FIELD is used.
Set NOOUT to true to get the code returned without printing it.
&html_table_cols(ATTRIBUTES)
&html_table_rows(ATTRIBUTES)
Formats a list of values in an HTML table.
ATTRIBUTES are given as key => value pairs.
Attributes are case insensitive.
For columns divided table, attribute cols should contain the column number. For rows divided table,
the attribute rows should be supplied.
The attributes tattr, rattr and cattr are used to specify the extra code for TABLE, TR and TD tags in the
table, to control alignment, etc. Normally, they contain the string to include.
If the attribute eval is set to true, the contents of the attributes above are evaluate. The code can use the
variables $x, $y, $data to inspect the cell before returning values.
Individual cells can be given different values, by using a hash reference instead of a scalar value ad the
cell value.
The hash should contain:
? Data – the real cell data
? Header – true if the cell should be formatted with TH and not TD
? cattr – alternative attributes for the cell. Ignored if not set or if null.
At last, the attribute noout can be set, so the html code is returned without being printed.
&include(FILENAME)
Dump a text file. FILENAME can be a URL.
&inputlist(ARRAYREF, ATTRIBUTES)
Returns a reference to an array of HTML code entries rendering a list of checkboxes or radio buttons.
ARRAYREF should point to an array of referenced hash tables, for each the following attributes have
to appear:
? value – Value for the VALUE attribute of the INPUT tag
? text – text to put near the input element
ATTRBIUTES are pairs of key => value that describe the input list. The possible attributes are:
? name – Name of input fields. Mandatory.
? Default – Value or a reference to an array of values of input fields that will be marked as
CHECKED
? OnCheck – Javascript code for onCheck event
? Attr – Additional attributes for INPUT tag
&isip(IP)
Returns true if IP is in IP address format. Doesn’t validate contents.
&isurl(STRING)
Checks is STRING is composed as a URL. To check validity of the URL use &validurl.
&max(LIST)
Returns the highest element of LIST, numeric wise.
&min(LIST)
Returns the lowest element of LIST, numeric wise.
&nslookup(HOSTNAME)
Uses gethostbyname() to resolve HOSTNAME. Returns undef if lookup fails.
&opendoc(HANDLE, FILENAME)
Opens HANDLE to read FILENAME. If FILENAME is a URL, the document is fetched and then
opened from a local copy. Handles opened with &opendoc should be closed with &closedoc to ensure
erasure of temporary files.
The filename to use is given by &tempfilename
&publish(HASH)
For each in HASH, the value is copied to variables in the main namespaces with names identical to the
key; both scalar and array values.
In htpl.head, this brings the CGI variables to the main namespace.
&readfile(FILENAME)
Reads the file named FILENAME into a scalar value. FILENAME may be a URL.
&redirect(URL)
Erases the output of the script and redirects the client. Any data sent to the HTTP headers (cookies etc)
won’t be erased except MIME TYPE info.
Unavailable for converted scripts executed outside htpl.cgi.
&rewind
Clear the output of the script.
Unavailable when script runs outside of htpl.cgi.
&revnslookup(IP)
Attempts to find hostname for IP.
&selectbox(DEFAULT, PAIRS)
&selectbox(HASHREF, PAIRS)
Prints