pkg://htmltmpl-1.22-5.src.rpm:75348/htmltmpl-1.22.tar.gz
info downloads
htmltmpl-1.22/ 0040775 0000764 0000764 00000000000 07407003263 012034 5 ustar trip trip htmltmpl-1.22/doc/ 0040775 0000764 0000764 00000000000 07407003263 012601 5 ustar trip trip htmltmpl-1.22/doc/examples/ 0040775 0000764 0000764 00000000000 07407003263 014417 5 ustar trip trip htmltmpl-1.22/doc/examples/products.html 0100664 0000764 0000764 00000000757 07342033601 017153 0 ustar trip trip <html>
<head>
<title>Our products</title>
</head>
<body>
<h1>Our products</h1>
<table>
<tr>
<td>1</td>
<td>Seagate</td>
</tr>
<tr>
<td>2</td>
<td>Conner</td>
</tr>
<tr>
<td>3</td>
<td>Maxtor</td>
</tr>
</table>
</body>
</html>
htmltmpl-1.22/doc/examples/products.py 0100664 0000764 0000764 00000003163 07344073045 016641 0 ustar trip trip
import MySQLdb
import MySQLdb.cursors
from htmltmpl import TemplateManager, TemplateProcessor
# Define some constants.
DB = "test"
USER = ""
PASSWD = ""
TABLE = """
CREATE TABLE IF NOT EXISTS Products (
id INTEGER NOT NULL AUTO_INCREMENT,
name VARCHAR(255) NOT NULL,
CONSTRAINT pkey_id
PRIMARY KEY(id)
)
"""
template = TemplateManager().prepare("products.tmpl")
tproc = TemplateProcessor()
# Assign a string to template variable named "title".
tproc.set("title", "Our products")
# Connect the database. Create the table.
db = MySQLdb.connect(db = DB, user = USER, passwd = PASSWD,
cursorclass = MySQLdb.cursors.DictCursor)
create_cur = db.cursor()
create_cur.execute(TABLE)
create_cur.close()
# Insert some data.
insert_cur = db.cursor()
insert_cur.executemany("""
INSERT INTO Products (name) VALUES (%(name)s)
""", [
{"name": "Seagate"},
{"name": "Conner"},
{"name": "Maxtor"}
])
insert_cur.close()
# Select the products.
products_cur = db.cursor()
products_cur.execute("""
SELECT id, name
FROM Products
""")
# Append product data in form of mappings (dictionaries) to the
# products list.
products = []
for i in range(products_cur.rowcount):
products.append(products_cur.fetchone())
products_cur.close()
db.close()
# Assign the products list to template loop identifier 'Products'.
# NOTE: htmltmpl automatically converts all the values
# to strings using str().
tproc.set("Products", products)
# Process the template and print the result.
print tproc.process(template)
htmltmpl-1.22/doc/examples/products.tmpl 0100664 0000764 0000764 00000000544 07342033601 017155 0 ustar trip trip <html>
<head>
<title><TMPL_VAR title></title>
</head>
<body>
<h1>Our products</h1>
<table>
<TMPL_LOOP Products>
<tr>
<td><TMPL_VAR id></td>
<td><TMPL_VAR name></td>
</tr>
</TMPL_LOOP>
</table>
</body>
</html>
htmltmpl-1.22/doc/examples/template.html 0100664 0000764 0000764 00000001153 07344073045 017122 0 ustar trip trip <html>
<head>
<title>Our customers</title>
</head>
<body>
<h1>Customers:</h1>
<p>
Total: 2
</p>
<table>
<tr>
<td>old customer</td>
<td>1</td>
<td>Joe Sixpack</td>
<td>Los Angeles</td>
</tr>
<tr>
<td>new customer</td>
<td>2</td>
<td>Paul Newman</td>
<td>New York</td>
</tr>
</table>
</body>
</html>
htmltmpl-1.22/doc/examples/template.py 0100664 0000764 0000764 00000001245 07344073045 016610 0 ustar trip trip
from htmltmpl import TemplateManager, TemplateProcessor
# Compile or load already precompiled template.
template = TemplateManager().prepare("template.tmpl")
tproc = TemplateProcessor()
# Set the title.
tproc.set("title", "Our customers")
# Create the 'Customers' loop.
customers = []
# First customer.
customer = {}
customer["name"] = "Joe Sixpack"
customer["city"] = "Los Angeles"
customer["new"] = 0
customers.append(customer)
# Second customer.
customer = {}
customer["name"] = "Paul Newman"
customer["city"] = "New York"
customer["new"] = 1
customers.append(customer)
tproc.set("Customers", customers)
# Print the processed template.
print tproc.process(template)
htmltmpl-1.22/doc/examples/template.tmpl 0100664 0000764 0000764 00000001275 07344073045 017137 0 ustar trip trip <html>
<head>
<title><TMPL_VAR title></title>
</head>
<body>
<h1>Customers:</h1>
<p>
Total: <TMPL_VAR Customers>
</p>
### this comment will be removed
<table>
<TMPL_LOOP Customers>
<tr>
<TMPL_IF new>
<td>new customer</td>
<TMPL_ELSE>
<td>old customer</td>
</TMPL_IF>
<td><TMPL_VAR __PASS__></td>
<td><TMPL_VAR name></td>
<td><TMPL_VAR city></td>
</tr>
</TMPL_LOOP>
</table>
</body>
</html>
htmltmpl-1.22/doc/easydoc-api.html 0100664 0000764 0000764 00000017713 07400313515 015670 0 ustar trip trip <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>easydoc: documentation</title>
<meta name="author"
content="Tomas Styblo (tripie@cpan.org)"></meta>
<meta name="keywords" content="Python,module,easydoc"></meta>
<meta name="description" content="A module to autogenerate HTML documentation from docstrings."></meta>
<style type="text/css">
<!--
body {
font-family: "Helvetica CE", "Arial CE", Helvetica, Arial, sans-serif;
background-color: #d8d0a4;
color: black;
}
a {
color: red;
font-weight: bold;
}
.methodbg {
background-color: #d8e0d4;
}
-->
</style>
</head>
<body>
<h1>easydoc</h1>
<!-- module info -->
<p><strong>A module to autogenerate HTML documentation from docstrings.</strong></p>
<p>
<strong>
VERSION: 1.01 <br></br>
AUTHOR: Tomas Styblo (<a href="mailto:tripie@cpan.org">tripie@cpan.org</a>)
<br></br>
WEBSITE: <a href="http://htmltmpl.sourceforge.net/">http://htmltmpl.sourceforge.net/</a>
<br></br>
LICENSE: <a href="http://www.gnu.org/licenses/gpl.html">GNU GPL</a>
</strong>
</p>
<p>The documentation of this module can be found in 'doc' directory of the
distribution tarball or at the website of this package.
Latest versions of this module are also available at that website.</p>
<p>You can use and redistribute this module under conditions of the
GNU General Public License that can be found either at
<a href="http://www.gnu.org/">http://www.gnu.org/</a> or in file "LICENSE" contained in the
distribution tarball of this module.</p>
<p>Copyright (c) 2001 Tomas Styblo, tripie@cpan.org
Prague, the Czech Republic</p>
<hr></hr>
<!-- module requirements -->
<p><strong>REQUIRES:</strong></p>
<ul>
<li>htmltmpl (<a href="http://htmltmpl.sourceforge.net/">http://htmltmpl.sourceforge.net/</a>)</li>
</ul>
<hr></hr>
<!-- table of functions -->
<!-- table of classes and methods -->
<p><strong>CLASSES:</strong></p>
<ul>
<li>
<p>
<a href="#class-Easydoc">Easydoc</a>:
Autogenerate documentation from docstrings. </p>
<table border="0" cellpadding="3">
<tr>
<td>
</td>
<td class="methodbg">
<a href="#method-Easydoc_process">
process</a>
</td>
<td>Create documentation for a module.</td>
</tr>
<tr>
<td>
</td>
<td class="methodbg">
<a href="#method-Easydoc___init__">
__init__</a>
</td>
<td>Constructor.</td>
</tr>
</table>
</li>
</ul>
<hr></hr>
<!-- documentation of functions -->
<hr></hr>
<!-- documentation of classes -->
<!-- class: Easydoc -->
<h2>CLASS: <a name="class-Easydoc"></a>Easydoc</h2>
<p><strong>Autogenerate documentation from docstrings.</strong></p>
<p>This class provides all the functionality of easydoc. You can
subclass it and override its processing methods module(),
mclass() and method() to customize its behaviour.</p>
<p>You also can easily use your own template to modify the output
in any way you need. Output colors can be customized via
parameters.</p>
<!-- table of methods of class Easydoc -->
<p><strong>METHODS:</strong></p>
<table border="0" cellpadding="3">
<tr>
<td> </td>
<td class="methodbg">
<a href="#method-Easydoc_process">
process</a>
</td>
<td>Create documentation for a module.</td>
</tr>
<tr>
<td> </td>
<td class="methodbg">
<a href="#method-Easydoc___init__">
__init__</a>
</td>
<td>Constructor.</td>
</tr>
</table>
<hr></hr>
<!-- documentation of methods of class Easydoc -->
<!-- method process -->
<h3>METHOD: <a name="method-Easydoc_process"></a>
process()</h3>
<p>
<strong><em>Create documentation for a module.</em></strong>
<small>(class
<a href="#class-Easydoc">Easydoc</a>)
</small>
</p>
<p><strong>RETURN VALUE:</strong></p>
<p>String containing the resulting HTML documentation.</p>
<!-- parameters of method process -->
<p><strong>PARAMETERS:</strong></p>
<pre>process(module, bgcolor, textcolor, linkcolor, with_hidden=0)</pre>
<ul>
<li>
<p><strong>module</strong></p>
<p><strong><em>Filename of the module to document.</em></strong></p>
<p>The module must be specified as filename. The module is not
imported nor executed, only parsed.</p>
</li>
<li>
<p><strong>bgcolor</strong></p>
<p><strong><em>Set background color.</em></strong></p>
<p>Accepts any valid CSS color value.</p>
</li>
<li>
<p><strong>textcolor</strong></p>
<p><strong><em>Set text color.</em></strong></p>
<p>Accepts any valid CSS color value.</p>
</li>
<li>
<p><strong>linkcolor</strong></p>
<p><strong><em>Set color of hyperlinks.</em></strong></p>
<p>Accepts any valid CSS color value.</p>
</li>
<li>
<p><strong>with_hidden</strong></p>
<p><strong><em>Do not exclude hidden sections from output.</em></strong></p>
<p>This optional parameter can be used to force inclusion of
hidden sections in the resulting documentation. Hidden sections
are by default not included.</p>
</li>
</ul>
<hr></hr>
<!-- method __init__ -->
<h3>METHOD: <a name="method-Easydoc___init__"></a>
__init__()</h3>
<p>
<strong><em>Constructor.</em></strong>
<small>(class
<a href="#class-Easydoc">Easydoc</a>)
</small>
</p>
<!-- parameters of method __init__ -->
<p><strong>PARAMETERS:</strong></p>
<pre>__init__(template, debug=0)</pre>
<ul>
<li>
<p><strong>template</strong></p>
<p><strong><em>String containing template data.</em></strong></p>
</li>
<li>
<p><strong>debug</strong></p>
<p><strong><em>Enable or disable debugging messages.</em></strong></p>
<p>This optional parameter can be used to enable or disable debugging
messages which are printed to stderr. By default debugging
messages are disabled.</p>
</li>
</ul>
<hr></hr>
<hr></hr>
</body>
</html>
htmltmpl-1.22/doc/easydoc.html 0100664 0000764 0000764 00000021762 07400327060 015120 0 ustar trip trip <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>htmltmpl - easydoc</title>
<meta name="author" content="Tomas Styblo (tripie@cpan.org)"></meta>
<link rel="StyleSheet" type="text/css" href="main.css"></link>
</head>
<body>
<table width="100%" border="2" cellspacing="4" cellpadding="8">
<tr>
<td align="center">
<span class="title">
<strong>
htmltmpl: templating engine for separation of code and HTML
</strong>
</span>
</td>
</tr>
</table>
<p></p>
<table border="0" cellspacing="0" cellpadding="16">
<tr>
<!-- menu on the left -->
<td valign="top">
<ul>
<li><p><a href="http://htmltmpl.sourceforge.net/">HOMEPAGE</a></p></li>
<li><p><a href="index.html">OVERVIEW</a></p></li>
<li><p><a href="lang.html">THE LANGUAGE</a></p></li>
<li><p><a href="python-api.html">API DOCS</a></p></li>
<li><p><a href="gettext.html">GETTEXT SUPPORT</a></p></li>
<li><p><a href="python.html">PYTHON VERSION</a></p></li>
<li><p><a href="easydoc.html">PYTHON EASYDOC</a></p></li>
<li><p><a href="php.html">PHP VERSION</a></p></li>
<li><p><a href="http://lists.sourceforge.net/lists/listinfo/htmltmpl-support">MAILING LIST</a></p></li>
<li><p><a href="http://sourceforge.net/cvs/?group_id=34229">PUBLIC CVS</a></p></li>
<li><p><a href="http://sam.tregar.com/html_template.html">HTML::TEMPLATE</a></p></li>
<li><p><a href="http://sourceforge.net">
<img src="http://sourceforge.net/sflogo.php?group_id=34229"
width="88" height="31" class="noborder"
alt="SourceForge Logo"></img></a></p></li>
</ul>
</td>
<!-- the text right to the menu -->
<td valign="top">
<p>
Easydoc is an example application that uses htmltmpl
to provide flexible HTML output. It can process docstrings
embedded in source file of a module and generate proper XHTML
documentation from them. It's very similar to the
<em>javadoc</em> program used by Java applications.
The API documentation for htmltmpl and easydoc itself
is auto-generated by easydoc.
</p>
<p>
The purpose of the program is to ease maintenance of
documentation. It's very annoying to maintain more
versions of documentation at once - docstrings in a source
file and a HTML form of them which is much more convenient
for common users. After a while the two versions always fail
to be synchronized and become a maintenance nightmare.
</p>
<p>
The solution is to maintain the documentation only in form
of docstrings in the source code and generate the HTML version
automatically from them.
</p>
<p>
Of course, many other solutions exist for this purpose. This
program was created to be similar to javadoc and as a
test application for htmltmpl. The default template it uses
is quite complex; it contains loops which are nested
four levels deep. You can replace the default template with
your own one to customize the output.
</p>
<p>
Easydoc is now part of the htmltmpl distribution and is
automatically installed when you install htmltmpl.
There also is a script called <em>easy.py</em> which provides
command line interface to the module. It's included in the
distribution. Run it without any parameters to view
usage instructions.
</p>
<p>
<strong>
The API documentation of the easydoc module can be found
<a href="easydoc-api.html">here</a>.
</strong>
</p>
<ul>
<li><a href="#example">Explanation and example</a></li>
</ul>
</td>
</tr>
</table>
<hr></hr>
<h2><a name="example"></a>Explanation and example</h2>
<p>
This example documented module illustrates and describes the special
syntax of docstrings which easydoc requires. The syntax is similar to
that of javadoc.
</p>
<pre>
""" Short one line description of the module.
Detailed description of the module which can span more lines. You can
use HTML tags here, but you should use only in-line tags which will not
break the page. Do NOT use <p> or <br> tags to separate
paragraphs. Instead use empty lines which are automatically converted
to paragraph separators. HTML brackets which are not part of a tag
should be written as appropriate HTML entities. All strings in form
<em>[ http://some.url.com ]</em> are automatically converted to
hyperlinks.
After the detailed description comes the 'meta' section which should be
used to give the docstring processor some structured information about
the section which is being documented. It uses special statements which
begin with the '@' character. This character is ignored if it isn't the
first non-whitespace character on a line. URLs in parameters that
specify an URL should _NOT_ be written in the special hyperlink form
described above.
<span class="red">@name</span> easydoc
<span class="red">@version</span> 1.00
<span class="red">@website</span> http://htmltmpl.sourceforge.net/
<span class="red">@author-name</span> Tomas Styblo
<span class="red">@author-email</span> tripie@cpan.org
<span class="red">@license-name</span> GNU GPL
<span class="red">@license-url</span> http://www.gnu.org/licenses/gpl.html
<span class="red">@require</span> htmltmpl ([ http://htmltmpl.sourceforge.net ])
<span class="red">@require</span> some other prerequisite ...
"""
class Example:
""" One line description of the class. End it with a dot if appropriate.
Detailed description which can span more lines. You can use HTML tags
here, but you should use only in-line tags which will not break the page.
Do NOT use <p> or <br> tags to separate paragraphs. Instead
use empty lines which are automatically converted to paragraph separators.
HTML brackets which are not part of a tag should be written as appropriate
HTML entities. Code examples must be placed inside a <pre> block.
After the detailed description comes the 'meta' section which should
be used to give the docstring processor some structured information
about the section which is being documented. It uses special statements
which begin with the '@' character. This character is ignored if it isn't
the first non-whitespace character on a line.
<span class="red">@hidden</span> The meta section can contain some special processing instructions.
The @hidden instruction can be used to exclude the section which is being
documented from the resulting documentation. This is useful for private
classes and methods.
The sections marked as hidden can be included in the output if you use
the '--with-hidden' command line option of easydoc.
"""
def method(param1, param2=""):
""" Short one line description of the method.
Detailed description of the method. Same rules as for detailed
descriptions of classes apply here.
The header statement below must contain a full header of the method,
as it appears in the code. It's used for quick overview of the
method's parameters and their default values. Do not include the
<em>self</em> parameter of methods here.
<span class="red">@return</span> Short one line description of return value.
Here comes detailed description of the return value. It can span
more lines and contain appropriate HTML markup. You should explicitly
document cases when the method has no return value.
<span class="red">@header</span>
method(param1, param2="")
<span class="red">@param</span> param1 One Line description of parameter.
More detailed description of the 'param' parameter which again can
span more lines and contain HTML tags. These detailed descriptions
are terminated by either end of the docstring or by another statement.
The detailed descriptions also can consist of more paragraphs
separated by an empty line.
<span class="red">@param</span> param2 One line description of parameter.
Detailed description of the second parameter.
<span class="red">@hidden</span> This statement has the same meaning as in classes.
"""
</pre>
</body>
</html>
htmltmpl-1.22/doc/gettext.html 0100664 0000764 0000764 00000016253 07400324463 015160 0 ustar trip trip <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>htmltmpl templating engine</title>
<meta name="author" content="Tomas Styblo (tripie@cpan.org)"></meta>
<link rel="StyleSheet" type="text/css" href="main.css"></link>
</head>
<body>
<table width="100%" border="2" cellspacing="4" cellpadding="8">
<tr>
<td align="center">
<span class="title">
<strong>
htmltmpl: templating engine for separation of code and HTML
</strong>
</span>
</td>
</tr>
</table>
<p></p>
<table border="0" cellspacing="0" cellpadding="16">
<tr>
<!-- menu on the left -->
<td valign="top">
<ul>
<li><p><a href="http://htmltmpl.sourceforge.net/">HOMEPAGE</a></p></li>
<li><p><a href="index.html">OVERVIEW</a></p></li>
<li><p><a href="lang.html">THE LANGUAGE</a></p></li>
<li><p><a href="python-api.html">API DOCS</a></p></li>
<li><p><a href="gettext.html">GETTEXT SUPPORT</a></p></li>
<li><p><a href="python.html">PYTHON VERSION</a></p></li>
<li><p><a href="easydoc.html">PYTHON EASYDOC</a></p></li>
<li><p><a href="php.html">PHP VERSION</a></p></li>
<li><p><a href="http://lists.sourceforge.net/lists/listinfo/htmltmpl-support">MAILING LIST</a></p></li>
<li><p><a href="http://sourceforge.net/cvs/?group_id=34229">PUBLIC CVS</a></p></li>
<li><p><a href="http://sam.tregar.com/html_template.html">HTML::TEMPLATE</a></p></li>
<li><p><a href="http://sourceforge.net">
<img src="http://sourceforge.net/sflogo.php?group_id=34229"
width="88" height="31" class="noborder"
alt="SourceForge Logo"></img></a></p></li>
</ul>
</td>
<!-- the text right to the menu -->
<td valign="top">
<p>
This section is a description of the gettext support integrated in
htmltmpl. It's of interest for anyone who would like to use htmltmpl
to easily build a multilingual web application.
</p>
<p>
The section describes only the gettext support in htmltmpl. Please
refer to other sources for general info on gettext and its
principles. The info manual for gettext should be included in every
modern UNIX distribution.
</p>
<p>
The gettext support in htmltmpl must be explicitely activated by
setting the parameter '<em>gettext</em>' of TemplateManager or
TemplateCompiler constructor to TRUE.
</p>
<p>
The support will not work if your computer's locale system is not
installed properly or if your Python or PHP interpreter is not
configured to support locales and gettext. In Python, gettext support
is part of the standard library. PHP must be compiled using the
'<em>--with-gettext</em>' parameter, otherwise an attempt to use
htmltmpl in gettext mode will result in a "call to undefined
function" error.
</p>
<ul>
<li><a href="#syntax">Syntax</a></li>
<li><a href="#xgettext">tmpl-xgettext</a></li>
<li><a href="#programming">Programming</a></li>
</ul>
</td>
</tr>
</table>
<hr></hr>
<h2><a name="syntax"></a>Syntax</h2>
<p>
In the templates, all text which should be translated by gettext must be
enclosed in double brackets. Example:
</p>
<pre>
<span class="red"><TMPL_LOOP Test></span>
<span class="red">[[</span><span class="string">Product</span><span class="red">]]</span>: <span class="red"><TMPL_VAR product></span><br>
<span class="red">[[</span><span class="string">Price</span><span class="red">]]</span>: <span class="red"><TMPL_VAR price></span><br>
<span class="red"></TMPL_LOOP></span>
</pre>
<p>
The brackets will be removed when the template is processed.
If you need to include opening brackets somewhere in the text of the
template, you can escape them using a backslash. In the following example
the brackets will not be removed and the word 'jumps' will not be translated.
The backslash will be removed always and only when it is placed right before
opening or closing double brackets.
</p>
<pre>
Quick brown fox \[[jumps]] over a lazy dog.
Sometimes we need to use the backslash '\'.
... will be printed as:
Quick brown fox [[jumps]] over a lazy dog.
Sometims we need to use the backslash '\'.
</pre>
<p>
In some rare cases you need to print a backslash right before double
brackets. You can use another backslash to escape the backslash. In that
case, one backslash will be printed and the translation will take place.
In the following example the word 'jumps' will be translated:
</p>
<pre>
Quick brown fox \\[[jumps]] over a lazy dog.
... will be printed as:
Quick brown fox \jumps over a lazy dog.
</pre>
<p>
The backslash can also be used to include closing double brackets in a text
which should be translated. In the following example, the double brackets
are taken as a part of the text to be translated. That means, the whole
text 'jumps over ]] a lazy' will be translated.
</p>
<pre>
Quick brown fox [[jumps over \]] a lazy]] dog.
</pre>
<p>
A backslash always escapes another backslash. That means that to print two
backslashes, you must write four of them. An example:
</p>
<pre>
This will print one backslash: \.
This will print one backslash: \\.
This will print two backslashes: \\\\.
... will be printed as:
This will print one backslash: \.
This will print one backslash: \.
This will print two backslashes: \\.
</pre>
<!-- xgettext -->
<hr></hr>
<h2><a name="xgettext"></a>tmpl-xgettext</h2>
<p>
The gettext strings must usually be extracted using the xgettext program.
The standard xgettext program cannot work with htmltmpl templates, though.
You must use the tmpl-xgettext.pl script which is included in htmltmpl
distribution to convert the templates into a format which xgettext can
understand.
</p>
<pre>
cat template.tmpl | perl tmpl-xgettext.pl | xgettext -o file.po -
</pre>
<!-- Programming -->
<hr></hr>
<h2><a name="programming"></a>Programming</h2>
<p>
Your program must initialize gettext before it calls the
<strong>process()</strong> method
of TemplateProcessor. It usually means to call setlocale(),
bindtextdomain() and textdomain() with appropriate parameters.
Check documentation of PHP or Python gettext extensions
for more information.
</p>
<p>
Also, your program is of course responsible for translation of any texts
which are assigned as values to TMPL_VARs.
</p>
</body>
</html>
htmltmpl-1.22/doc/index.html 0100664 0000764 0000764 00000017440 07406735714 014615 0 ustar trip trip <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>htmltmpl templating engine</title>
<meta name="author" content="Tomas Styblo (tripie@cpan.org)"></meta>
<link rel="StyleSheet" type="text/css" href="main.css"></link>
</head>
<body>
<table width="100%" border="2" cellspacing="4" cellpadding="8">
<tr>
<td align="center">
<span class="title">
<strong>
htmltmpl: templating engine for separation of code and HTML
</strong>
</span>
</td>
</tr>
</table>
<p></p>
<table border="0" cellspacing="0" cellpadding="16">
<tr>
<!-- menu on the left -->
<td valign="top">
<ul>
<li><p><a href="http://htmltmpl.sourceforge.net/">HOMEPAGE</a></p></li>
<li><p><a href="index.html">OVERVIEW</a></p></li>
<li><p><a href="lang.html">THE LANGUAGE</a></p></li>
<li><p><a href="python-api.html">API DOCS</a></p></li>
<li><p><a href="gettext.html">GETTEXT SUPPORT</a></p></li>
<li><p><a href="python.html">PYTHON VERSION</a></p></li>
<li><p><a href="easydoc.html">PYTHON EASYDOC</a></p></li>
<li><p><a href="php.html">PHP VERSION</a></p></li>
<li><p><a href="http://lists.sourceforge.net/lists/listinfo/htmltmpl-support">MAILING LIST</a></p></li>
<li><p><a href="http://sourceforge.net/cvs/?group_id=34229">PUBLIC CVS</a></p></li>
<li><p><a href="http://sam.tregar.com/html_template.html">HTML::TEMPLATE</a></p></li>
<li><p><a href="http://sourceforge.net">
<img src="http://sourceforge.net/sflogo.php?group_id=34229"
width="88" height="31" class="noborder"
alt="SourceForge Logo"></img></a></p></li>
</ul>
</td>
<!-- the text right to the menu -->
<td valign="top">
<p>
<strong>Current versions:</strong>
</p>
<table cellpadding="8" cellspacing="1" border="1">
<tr>
<td>
htmltmpl for Python<br></br>
easydoc for Python
</td>
<td><strong>1.22</strong></td>
<td>2001/12/15</td>
<td>
<a href="htmltmpl-1.22.tar.gz">download</a>
</td>
</tr>
<tr>
<td>htmltmpl for PHP</td>
<td><strong>1.12</strong></td>
<td>2001/12/15</td>
<td>
<a href="htmltmpl-php-1.12.tar.gz">download</a>
</td>
</tr>
</table>
<p>
The purpose of the templating engine is to provide web
application developers,
who need to separate program code and design (HTML code) of their
web application projects, with a templating tool that can be
easily used by cooperating webdesigners who have no programming
skills.
</p>
<p>
Templating language provided by the engine is inspired by Perl
templating module HTML::Template.
Templates created for HTML::Template can be used with this engine.
</p>
<p>
The engine is currently available for Python and PHP.
The Python package includes <strong>easydoc</strong>, a module
which uses the templating engine to generate HTML documentation
from docstrings embedded in source files of Python modules.
</p>
<p>
The primary goal of the templating engine is to keep things simple
for a webdesigner who creates the templates. Therefore, neither
Python nor PHP code can be used in the templates.
Instead, the templating
engine provides its own simple templating language that supports
basic programming operations like for example loops, conditionals
and substitution of variables. These operations are controlled
from within the templates by statements that look like HTML tags
and integrate nicely with regular HTML code.
</p>
<p>
The secondary goal is good performance. High speed template
processing is necessary when the engine is used by web
applications.
</p>
<p>
I am aware that other templating solutions for Python and PHP
exist.
But none of them is similar to HTML::Template. I love its
enforcement of strict separation of code and HTML and the style
and syntax of its template language.
I find it much more cleaner and maintainable than
the other solutions. Also, I need to move some projects from
Perl to Python and PHP and I want to reuse my old HTML::Template
templates. These are the reasons why I created the templating
engine.
</p>
<p>
The engine now also has an integrated support for gettext, which
makes it very convenient for development of multilingual
"skinnable" web applications.
</p>
<hr></hr>
<ul>
<li><a href="#author">Author and license</a></li>
<li><a href="#credits">Credits</a></li>
<li><a href="#support">Support (mailing list)</a></li>
</ul>
</td>
</tr>
</table>
<!-- author and license -->
<hr></hr>
<h2><a name="author"></a>Author and license</h2>
<address>
Copyright (c) 2001 Tomas Styblo<br></br>
Email: <a href="mailto:tripie@cpan.org">tripie@cpan.org</a><br></br>
Homepage: <a href="http://geocities.com/tripiecz/">
http://geocities.com/tripiecz/</a><br></br>
Prague, the Czech Republic
</address>
<p>
You can use and redistribute the engine under conditions of the
<a href="http://www.gnu.org/licenses/gpl.html">
GNU General Public License</a> that can be found either at
<a href="http://www.gnu.org/">http://www.gnu.org/</a>
or in file "LICENSE" contained in the distribution tarball of the
engine.
</p>
<p>
Author of the engine and its documentation is not an English
native speaker. Corrections of grammar or spelling are welcome.
</p>
<!-- credits -->
<hr></hr>
<h2><a name="credits"></a>Credits</h2>
<p>
The engine is inspired by Perl templating module HTML::Template
created by Sam Tregar (sam@tregar.com).
Sam invented the excellent templating
language. The htmltmpl implementation, however, was designed from scratch
and is not based on code of HTML::Template.
</p>
<p>
You should check the documentation of HTML::Template.
The templating language of htmltmpl is fully compatible with
HTML::Template and the documentation of HTML::Template
describes it much better than the yet unfinished documentation
of htmltmpl.
</p>
<p>
Documentation of HTML::Template can be found at
<a href="http://sam.tregar.com/html_template.html">
http://sam.tregar.com/html_template.html</a>
</p>
<!-- support -->
<hr></hr>
<h2><a name="support"></a>Support</h2>
<p>
There is a
<a href="http://lists.sourceforge.net/lists/listinfo/htmltmpl-support">
mailing list</a> for htmltmpl on SourceForge. Don't hesitate
to post a message if you find a bug, want to contribute a patch or
have some interesting idea.
</p>
</body>
</html>
htmltmpl-1.22/doc/lang.html 0100664 0000764 0000764 00000051203 07400276175 014415 0 ustar trip trip <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>htmltmpl templating engine</title>
<meta name="author" content="Tomas Styblo (tripie@cpan.org)"></meta>
<link rel="StyleSheet" type="text/css" href="main.css"></link>
</head>
<body>
<table width="100%" border="2" cellspacing="4" cellpadding="8">
<tr>
<td align="center">
<span class="title">
<strong>
htmltmpl: templating engine for separation of code and HTML
</strong>
</span>
</td>
</tr>
</table>
<p></p>
<table border="0" cellspacing="0" cellpadding="16">
<tr>
<!-- menu on the left -->
<td valign="top">
<ul>
<li><p><a href="http://htmltmpl.sourceforge.net/">HOMEPAGE</a></p></li>
<li><p><a href="index.html">OVERVIEW</a></p></li>
<li><p><a href="lang.html">THE LANGUAGE</a></p></li>
<li><p><a href="python-api.html">API DOCS</a></p></li>
<li><p><a href="gettext.html">GETTEXT SUPPORT</a></p></li>
<li><p><a href="python.html">PYTHON VERSION</a></p></li>
<li><p><a href="easydoc.html">PYTHON EASYDOC</a></p></li>
<li><p><a href="php.html">PHP VERSION</a></p></li>
<li><p><a href="http://lists.sourceforge.net/lists/listinfo/htmltmpl-support">MAILING LIST</a></p></li>
<li><p><a href="http://sourceforge.net/cvs/?group_id=34229">PUBLIC CVS</a></p></li>
<li><p><a href="http://sam.tregar.com/html_template.html">HTML::TEMPLATE</a></p></li>
<li><p><a href="http://sourceforge.net">
<img src="http://sourceforge.net/sflogo.php?group_id=34229"
width="88" height="31" class="noborder"
alt="SourceForge Logo"></img></a></p></li>
</ul>
</td>
<!-- the text right to the menu -->
<td valign="top">
<p>
This is a description of the templating language used by
htmltmpl.
</p>
<ul>
<li><a href="#compat">HTML::Template compatibility</a></li>
<li><a href="#syntax">Syntax overview</a></li>
<li><a href="#statements">Statements</a></li>
<li><a href="#example">Example</a></li>
</ul>
</td>
</tr>
</table>
<hr></hr>
<h2><a name="compat"></a>HTML::Template compatibility</h2>
<p>
Templates created for HTML::Template can be used with this engine
in case they do not violate character case rules of htmltmpl.
</p>
<p>
<strong>WARNING:</strong>
Template statements and their parameters must always be in uppercase.
Variable names must always be in lowercase. Loop names must be in
lowercase, but capitalized.
</p>
<p>
<strong>WARNING:</strong>
All included templates must be located in a directory named
<strong>'inc'</strong> which must be a subdirectory of the
directory in which the main template file is located. You must
refer to these templates only by their filename, ie. without
the 'inc' part of the path.
</p>
<p>
<strong>
This engine offers all features of HTML::Template except:
</strong>
</p>
<ul>
<li>The IPC shared cache.</li>
</ul>
<p>
<strong>
The engine also offers some additional features:
</strong>
</p>
<ul>
<li>
<p>
Gettext support for easy creation of multilingual web applications.
</p>
</li>
<li>
<p>
Special comments in form of "### some comment" can be added
to the templates. These comments are removed when the
templates are processed.
</p>
</li>
<li>
<p>
Precompiled versions of the templates can be saved
to disk to increase performance significantly.
This feature vastly reduces the need of caching of any sort.
</p>
</li>
<li>
<p>
Multipart templates can be created using the <TMPL_BOUNDARY>
directive. Multipart templates are useful when you need to process
and output a part of the template before all data needed to process
the whole template are ready.
</p>
</li>
<li>
<p>
Additional loop context variables.
</p>
<ul>
<li>__PASS__</li>
<li>__PASSTOTAL__</li>
<li>__EVERY__x</li>
</ul>
</li>
<li>
<p>
Loop identifiers used in <TMPL_VAR> statements produce
a total number of passes in the corresponding loop.
</p>
</li>
<li>
<p>
You can override the global_vars setting on a per-variable
basis using a new 'GLOBAL' parameter.
</p>
</li>
<li>
<p>
All variables are by default automatically HTML escaped.
This can be disabled by setting the 'html_escape' parameter
to false.
</p>
</li>
</ul>
<hr></hr>
<h2><a name="syntax"></a>Syntax overview</h2>
<h3>Statements</h3>
<p>
The control statements of the templating language look like HTML tags.
They can be written in two forms:
</p>
<ul>
<li><TMPL_VAR></li>
<li><!-- TMPL_VAR --></li>
</ul>
<p>
There must be <strong>exactly</strong> one space after
the opening "<em><!--</em>" and before the
closing "<em>--></em>" if you use the longer form.
</p>
<p>
All statements except TMPL_VAR should be placed on a separate line.
</p>
<p>
All tabs and spaces on a line before a statement are removed,
if there are no other characters except tabs and spaces between
beginning of the line and the statement.
</p>
<p>
A trailing newline after a statement is removed if there are no other
characters between the newline and the statement.
</p>
<p>
The white-space removing described above is a Good Thing, because it
keeps the HTML nicely formatted, especially when loops are involved.
If you want to preserve the newline after a statement, just add a space
or a tab after the statement.
</p>
<p>
The statements do not need to follow HTML validity rules.
For example, following usage of TMPL_VAR is absolutely valid:
</p>
<pre>
<img src="<span class="red"><TMPL_VAR image></span>" />
</pre>
<p>
Unrecognized TMPL_* statements are detected and TemplateError
is raised when one is found.
</p>
<p>
Statements must be completely in uppercase: for example "TMPL_VAR".
It improves readability of the templates a lot. It makes
the statements easily distinguishable from normal XHTML tags,
that are always in lowercase.
</p>
<p>
Templates must not contain the '\0' character (ASCII code zero).
</p>
<hr></hr>
<h3>Parameters of the statements</h3>
<p>
Parameters can be written in two forms:
</p>
<ul>
<li>with double quotes: <TMPL_VAR myvar ESCAPE="HTML"></li>
<li>without double quotes: <TMPL_VAR myvar ESCAPE=HTML></li>
</ul>
<p>
There must not be any space between the "=" character and the name or
the value of the parameter.
</p>
<p>
Parameter names must be completely in uppercase: ESCAPE="HTML".
</p>
<p>
Predefined special values of parameters (like for example the
"HTML", "URL" and "NONE" values of the ESCAPE parameter) must
be completely in uppercase.
</p>
<p>
Parameter names and values can contain only alphanumeric characters
(non-locale) plus some additional characters: dash, dot, underscore,
colon, slash, backslash. They must NOT contain any spaces.
</p>
<hr></hr>
<h3>Identifiers</h3>
<p>
There are three types of identifiers:
</p>
<ul>
<li>names of variables</li>
<li>names of loops</li>
<li>filenames of included templates</li>
</ul>
<p>
Names of loops and variables can contain ASCII (non-locale)
alphanumeric characters, underscores and dashes. Names of loops and
variables are further restricted by the character case rules
described below.
</p>
<p>
Template filenames in TMPL_INCLUDE statements can contain only the same
characters that are allowed in values of parameters(see above). They
must NOT contain any spaces.
</p>
<p>
Minimum length of an identifier is one character.
Names of variables and loops can be specified in two ways:
</p>
<ul>
<li>as bare-words: <TMPL_VAR myvar></li>
<li>as 'NAME' parameters: <TMPL_VAR NAME="myvar"></li>
</ul>
<p>
Following character case rules apply to the
names of variables and loops:
</p>
<ul>
<li>Variable names must be completely in lowercase: myvar</li>
<li>Loop names must be capitalized and in lowercase: Myloop</li>
</ul>
<hr></hr>
<h3>Valid statements and parameters</h3>
<table cellpadding="8" cellspacing="1" border="1">
<tr>
<td><strong>TMPL_INCLUDE</strong></td>
<td>NAME</td>
</tr>
<tr>
<td><strong>TMPL_VAR</strong></td>
<td>NAME, ESCAPE, GLOBAL</td>
</tr>
<tr>
<td><strong>TMPL_IF</strong></td>
<td>NAME, GLOBAL</td>
</tr>
<tr>
<td><strong>TMPL_UNLESS</strong></td>
<td>NAME, GLOBAL</td>
</tr>
<tr>
<td><strong>TMPL_ELSE</strong></td>
<td> </td>
</tr>
<tr>
<td><strong>/TMPL_IF</strong></td>
<td> </td>
</tr>
<tr>
<td><strong>/TMPL_UNLESS</strong></td>
<td> </td>
</tr>
<tr>
<td><strong>TMPL_LOOP</strong></td>
<td>NAME</td>
</tr>
<tr>
<td><strong>/TMPL_LOOP</strong></td>
<td> </td>
</tr>
<tr>
<td><strong>TMPL_BOUNDARY</strong></td>
<td> </td>
</tr>
</table>
<p></p>
<hr></hr>
<h3>Template comments</h3>
<p>
Comments are in form of "### some comment".
Everything that follows these four characters - "### " - is removed
before the template is processed.
The ending space in "### " IS significant.
Comments can be disabled using the 'comments' parameter.
</p>
<hr></hr>
<h4>Examples:</h4>
<pre>
<TMPL_VAR myname> ### first comment
<TMPL_VAR hisname> ### second comment
</pre>
<hr></hr>
<h2><a name="statements"></a>Statements</h2>
<h3>Template inclusion</h3>
<p>
The <TMPL_INCLUDE> statement includes a template
directly into the current template at the point where the
statement is found. The included template contents are used
exactly as if its contents were physically included in the main
template.
</p>
<p>
All included templates must be located in a directory named
<strong>'inc'</strong> which must be a subdirectory of the
directory in which the main template file is located. You must
refer to these templates only by their filename, ie. without
the 'inc' part of the path.
</p>
<h4>Examples:</h4>
<p>
In this example, the file <em>header.tmpl</em> must be located in the
<strong>'inc'</strong> subdirectory of the directory in
which the main template file is located.
</p>
<pre>
<TMPL_INCLUDE header.tmpl>
<TMPL_INCLUDE NAME="header.tmpl">
</pre>
<hr></hr>
<h3>Variables</h3>
<p>
TODO
</p>
<p>
Variables defined by the TMPL_VAR statements are substituted with values
associated with them by the <em>set()</em> method of TemplateProcessor.
</p>
<h4>Escaping of variables</h4>
<p>
All variables are automatically HTML escaped. This can be disabled
using the 'html_escape' parameter.
Escaping of variables can also be specified on a per variable basis
using the ESCAPE parameter. This parameter overrides the default
escaping setting. It can have three values:
</p>
<ul>
<li>HTML : enable HTML escaping</li>
<li>URL : enable URL escaping</li>
<li>NONE : disable escaping</li>
</ul>
<h4>Global look-up of variables</h4>
<p>
All variables that are inside a loop are local to that loop.
If you want to reference a "global" variable from inside a loop,
then you must either enable the 'global_vars' parameter or use
the GLOBAL parameter to override 'global_vars'
setting on a per variable basis.
</p>
<h4>Examples:</h4>
<pre>
<TMPL_VAR name>
<TMPL_VAR NAME="city">
<TMPL_VAR NAME="text1" ESCAPE="HTML">
<TMPL_VAR NAME="text2" ESCAPE="NONE" GLOBAL="0">
<TMPL_VAR address GLOBAL="1">
<!-- TMPL_VAR test ESCAPE=URL -->
</pre>
<hr></hr>
<h3>Conditionals</h3>
<p>
TODO
</p>
<p>
The TMPL_IF, /TMPL_IF, TMPL_ELSE, TMPL_UNLESS and /TMPL_UNLESS
statements are conditionals.
They mark start and end of a block that is included in the output
only when the condition is true.
Only names of variables or loops can be used
in the condition. Conditional blocks may contain other nested conditional
blocks.
</p>
<p>
If name of a loop is used in a condition, then the condition is true
if the content of the loop will be included in the output at least once.
</p>
<h4>Examples:</h4>
<pre>
<span class="red"><TMPL_IF myvar></span>
This block appears in the output if myvar is true.
<span class="red"><TMPL_ELSE></span>
This block appears in the output if myvar is false.
<span class="red"></TMPL_IF></span>
<span class="red"><TMPL_UNLESS hisvar></span>
This block appears in the output if hisvar is false.
<span class="red"><TMPL_ELSE></span>
This block appears in the output if hisvar is true.
<span class="red"></TMPL_UNLESS></span>
</pre>
<hr></hr>
<h3>Loops</h3>
<p>
TODO
</p>
<p>
The TMPL_LOOP and /TMPL_LOOP statements mark start and end of a block
which is printed once for each mapping in the list of mappings
associated with the corresponding loop.
</p>
<p>
Loops can contain other nested loops. Every loop introduces its own namespace
(scope) for variables. Variables located inside a loop cannot reference
variables located outside the loop unless the 'global_vars' parameter
is true, or unless this parameter is overridden for
this variable using the 'GLOBAL' parameter of the corresponding
TMPL_VAR statement.
</p>
<p>
Loop names used as variables in TMPL_VAR statements produce
total number of passes in the corresponding loop.
</p>
<h4>examples</h4>
<pre>
<span class="red"><TMPL_LOOP Myloop></span>
This block appears in the output
once for every pass of the loop.
<span class="red"><TMPL_VAR myvar></span> <span class="red">### Local variable.</span>
<span class="red"></TMPL_LOOP></span>
</pre>
<hr></hr>
<h3>Magic loop variables</h3>
<p>
Magic context variables are automatically defined in every loop.
They can be used the same way as normal variables. Their names always
start with two underscores.
Values of these variables are always integers (true = 1, false = 0).
</p>
<p>
Following list lists all recognized magic variables.
Any other variable name which starts with two underscores is
invalid. The TemplateError exception is raised when such a variable
name is found.
</p>
<h4>__FIRST__</h4>
<p>
This variable is true if current pass is the first pass.
</p>
<h4>__LAST__</h4>
<p>
This variable is true if current pass is the last pass.
</p>
<h4>__INNER__</h4>
<p>
This variable is true if current pass is neither first nor last pass.
</p>
<h4>__ODD__</h4>
<p>
This variable is true if number of current pass is odd.
That means it's true in the first, third, fifth, seventh ..... pass.
</p>
<h4>__PASS__</h4>
<p>
Value of this variable is the number of current pass.
Passes are counted from one. Value of this variable is one in the first
pass, two in the second pass etc.
</p>
<h4>__PASSTOTAL__</h4>
<p>
Value of this variable is total number of passes in current loop.
</p>
<h4>__EVERY__x</h4>
<p>
Where 'x' must be an integer. It can consist of more than one digit.
This variable is true if number of
current pass modulo 'x' equals to zero. The variable is never true in
first or last pass, even if the condition above is true
in such a pass. This variable can be used to put separators
between every 'x' items of a list.
</p>
<hr></hr>
<h3>Multipart templates</h3>
<p>
Multipart templates can be created using the <TMPL_BOUNDARY>
directive. This directive has no parameters.
</p>
<p>
Multipart templates are useful when you need to process
and output a part of the template before all data needed to process
the whole template are ready.
</p>
<p>
This can be useful to improve
perceived responsiveness of web applications by sending the top part of
a page to the client before the web application for example sends a slow
query to the database and generates rest of the page from results of
the query. Keep in mind that you probably will have to flush the
output stream to achieve the desired effect. This can usually be done by
calling <em>sys.stdout.flush()</em> in Python or <em>flush()</em> in PHP.
</p>
<p>
Multipart templates must follow this rule: <strong>every part itself
must be a syntactically valid template.</strong> It means that boundaries
between the parts must not be located inside a conditional block or
inside a loop block.
</p>
<p>
The boundaries are processed after template inclusions are processed.
It's possible to put the boundaries into the included templates,
tough it's not recommended.
</p>
<p>
Please consult API documentation of the TemplateProcessor.process()
method to find out how to correctly use multipart templates in
your applications.
</p>
<h4>examples</h4>
<pre>
This is part one.
<span class="red"><TMPL_BOUNDARY></span>
This is part two.
<span class="red"><TMPL_BOUNDARY></span>
This is part three.
</pre>
<!-- Example -->
<hr></hr>
<h2><a name="example"></a>Example</h2>
<h3>template.tmpl</h3>
<pre>
<html>
<head>
<title><span class="red"><TMPL_VAR title></span></title>
</head>
<body>
<h1>Customers:</h1>
<p>
Total: <span class="red"><TMPL_VAR Customers></span>
</p>
<span class="red">### this comment will be removed</span>
<table>
<span class="red"><TMPL_LOOP Customers></span>
<tr>
<span class="red"><TMPL_IF new></span>
<td>new customer</td>
<span class="red"><TMPL_ELSE></span>
<td>old customer</td>
<span class="red"></TMPL_IF></span>
<td><span class="red"><TMPL_VAR __PASS__></span></td>
<td><span class="red"><TMPL_VAR name></span></td>
<td><span class="red"><TMPL_VAR city></span></td>
</tr>
<span class="red"></TMPL_LOOP></span>
</table>
</body>
</html>
</pre>
</body>
</html>
htmltmpl-1.22/doc/main.css 0100664 0000764 0000764 00000001071 07342133223 014231 0 ustar trip trip
body {
font-family: "Helvetica CE", "Arial CE", Helvetica, Arial, sans-serif;
background-color: #d8d0a4;
color: black;
}
a {
color: red;
font-weight: bold;
}
.red {
color: red;
font-weight: bold;
}
.title {
font-size: larger;
}
.noborder {
border-width: 0;
}
span.keyword {
color: #ff0000;
font-weight: bold;
} /* font-lock-keyword-face */
span.string {
color: #008b00;
font-weight: bold;
} /* font-lock-string-face */
span.comment {
color: #00008b;
font-style: italic;
} /* font-lock-comment-face */
htmltmpl-1.22/doc/makedoc.sh 0100775 0000764 0000764 00000000161 07400313521 014530 0 ustar trip trip #!/bin/sh
python ../easy.py ../htmltmpl.py ./python-api.html
python ../easy.py ../easydoc.py ./easydoc-api.html
htmltmpl-1.22/doc/php.html 0100664 0000764 0000764 00000020215 07400260036 014247 0 ustar trip trip <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>htmltmpl templating engine</title>
<meta name="author" content="Tomas Styblo (tripie@cpan.org)"></meta>
<link rel="StyleSheet" type="text/css" href="main.css"></link>
</head>
<body>
<table width="100%" border="2" cellspacing="4" cellpadding="8">
<tr>
<td align="center">
<span class="title">
<strong>
htmltmpl: templating engine for separation of code and HTML
</strong>
</span>
</td>
</tr>
</table>
<p></p>
<table border="0" cellspacing="0" cellpadding="16">
<tr>
<!-- menu on the left -->
<td valign="top">
<ul>
<li><p><a href="http://htmltmpl.sourceforge.net/">HOMEPAGE</a></p></li>
<li><p><a href="index.html">OVERVIEW</a></p></li>
<li><p><a href="lang.html">THE LANGUAGE</a></p></li>
<li><p><a href="python-api.html">API DOCS</a></p></li>
<li><p><a href="gettext.html">GETTEXT SUPPORT</a></p></li>
<li><p><a href="python.html">PYTHON VERSION</a></p></li>
<li><p><a href="easydoc.html">PYTHON EASYDOC</a></p></li>
<li><p><a href="php.html">PHP VERSION</a></p></li>
<li><p><a href="http://lists.sourceforge.net/lists/listinfo/htmltmpl-support">MAILING LIST</a></p></li>
<li><p><a href="http://sourceforge.net/cvs/?group_id=34229">PUBLIC CVS</a></p></li>
<li><p><a href="http://sam.tregar.com/html_template.html">HTML::TEMPLATE</a></p></li>
<li><p><a href="http://sourceforge.net">
<img src="http://sourceforge.net/sflogo.php?group_id=34229"
width="88" height="31" class="noborder"
alt="SourceForge Logo"></img></a></p></li>
</ul>
</td>
<!-- the text right to the menu -->
<td valign="top">
<p>
This is the PHP version of htmltmpl. This page contains
some basic information about the module and examples that
illustrate its usage.
</p>
<p>
<strong>
A complete documentation of the module's API can be found
<a href="python-api.html">here</a>.
</strong>
It contains description of all public classes and methods which
the module provides. The documentation is automatically
generated from docstrings in source file of the
<strong>Python version</strong> of the module. There are some
minor differences between the PHP and the Python version.
These differences are described later on this page.
</p>
<p>
The PHP version of the module works on UNIX and Windows
platforms. It <strong>requires PHP 4.0.6 or newer</strong>.
If you get strange compilation errors, then your PHP is too old.
</p>
<p>
The API of the PHP version differs from the Python version in
following aspects:
</p>
<ul>
<li>
<p>
Debugging is activated by pointing a global variable
$HTMLTMPL_DEBUG to a debugging logfile. No constructor takes
the 'debug' parameter in the PHP version.
</p>
</li>
<li>
<p>
All the factory methods which return an internally
constructed <em>Template</em> object return a
<strong>REFERENCE</strong> to it.
That means your code must use reference assignments:
</p>
<pre>
$manager = new TemplateManager();
$template <strong><span class="red">=&</span></strong> $manager->prepare($template_file);
</pre>
</li>
<li>
<p>
PHP does not support exceptions. The <em>TemplateError</em>
exception class does not exist in the PHP version. Instead,
all problems are handled via <em>user_error()</em> followed
by <em>exit()</em>.
</p>
</li>
</ul>
<p>
The version numbering is mutually independent. The 1.00 release
of the PHP version was based on the Python release 1.18.
</p>
<hr />
<ul>
<li><a href="python-api.html">API documentation</a>
(of the Python version)</li>
<li><a href="#examples">Examples</a>
<ul>
<li><a href="#example-simple">simple</a></li>
</ul>
</li>
</ul>
</td>
</tr>
</table>
<!-- end of the top part -->
<!-- examples -->
<hr></hr>
<h2><a name="examples"></a>Examples</h2>
<p>
Source files of all these examples are available in 'doc/examples'
directory of the distribution. Files from the regression test
suite (the 'test' directory) can also serve as examples.
</p>
<h3><a name="example-simple"></a>simple:</h3>
<h4>template.tmpl</h4>
<pre>
<html>
<head>
<title><span class="red"><TMPL_VAR title></span></title>
</head>
<body>
<h1>Customers:</h1>
<p>
Total: <span class="red"><TMPL_VAR Customers></span>
</p>
<span class="red">### this comment will be removed</span>
<table>
<span class="red"><TMPL_LOOP Customers></span>
<tr>
<span class="red"><TMPL_IF new></span>
<td>new customer</td>
<span class="red"><TMPL_ELSE></span>
<td>old customer</td>
<span class="red"></TMPL_IF></span>
<td><span class="red"><TMPL_VAR __PASS__></span></td>
<td><span class="red"><TMPL_VAR name></span></td>
<td><span class="red"><TMPL_VAR city></span></td>
</tr>
<span class="red"></TMPL_LOOP></span>
</table>
</body>
</html>
</pre>
<h4>template.php</h4>
<pre>
<?
require('htmltmpl.php');
# Compile or load already precompiled template.
$manager = new TemplateManager();
$template =& $manager->prepare("template.tmpl");
$tproc = new TemplateProcessor();
# Set the title.
$tproc->set("title", "Our customers");
# Create the 'Customers' loop. (regular array)
$customers = array();
# First customer (associative array).
$customer = array();
$customer['name'] = 'Joe Sixpack';
$customer['city'] = 'Los Angeles';
$customer['new'] = 0;
array_push($customers, $customer);
# Second customer.
$customer = array();
$customer['name'] = 'Paul Newman';
$customer['city'] = 'New York';
$customer['new'] = 1;
array_push($customers, $customer);
$tproc->set("Customers", $customers);
# Print the processed template.
echo $tproc->process($template);
?>
</pre>
<h4>template.html</h4>
<pre>
<html>
<head>
<title>Our customers</title>
</head>
<body>
<h1>Customers:</h1>
<p>
Total: 2
</p>
<table>
<tr>
<td>old customer</td>
<td>1</td>
<td>Joe Sixpack</td>
<td>Los Angeles</td>
</tr>
<tr>
<td>new customer</td>
<td>2</td>
<td>Paul Newman</td>
<td>New York</td>
</tr>
</table>
</body>
</html>
</pre>
</body>
</html>
htmltmpl-1.22/doc/python-api.html 0100664 0000764 0000764 00000110206 07400313515 015551 0 ustar trip trip <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>htmltmpl: documentation</title>
<meta name="author"
content="Tomas Styblo (tripie@cpan.org)"></meta>
<meta name="keywords" content="Python,module,htmltmpl"></meta>
<meta name="description" content="A templating engine for separation of code and HTML."></meta>
<style type="text/css">
<!--
body {
font-family: "Helvetica CE", "Arial CE", Helvetica, Arial, sans-serif;
background-color: #d8d0a4;
color: black;
}
a {
color: red;
font-weight: bold;
}
.methodbg {
background-color: #d8e0d4;
}
-->
</style>
</head>
<body>
<h1>htmltmpl</h1>
<!-- module info -->
<p><strong>A templating engine for separation of code and HTML.</strong></p>
<p>
<strong>
VERSION: 1.20 <br></br>
AUTHOR: Tomas Styblo (<a href="mailto:tripie@cpan.org">tripie@cpan.org</a>)
<br></br>
WEBSITE: <a href="http://htmltmpl.sourceforge.net/">http://htmltmpl.sourceforge.net/</a>
<br></br>
LICENSE: <a href="http://www.gnu.org/licenses/gpl.html">GNU GPL</a>
</strong>
</p>
<p>The documentation of this templating engine is separated to two parts:</p>
<p>1. Description of the templating language.</p>
<p>2. Documentation of classes and API of this module that provides
a Python implementation of the templating language.</p>
<p>All the documentation can be found in 'doc' directory of the
distribution tarball or at the homepage of the engine.
Latest versions of this module are also available at that website.</p>
<p>You can use and redistribute this module under conditions of the
GNU General Public License that can be found either at
<a href="http://www.gnu.org/">http://www.gnu.org/</a> or in file "LICENSE" contained in the
distribution tarball of this module.</p>
<p>Copyright (c) 2001 Tomas Styblo, tripie@cpan.org</p>
<hr></hr>
<!-- module requirements -->
<!-- table of functions -->
<!-- table of classes and methods -->
<p><strong>CLASSES:</strong></p>
<ul>
<li>
<p>
<a href="#class-TemplateProcessor">TemplateProcessor</a>:
Fill the template with data and process it. </p>
<table border="0" cellpadding="3">
<tr>
<td>
</td>
<td class="methodbg">
<a href="#method-TemplateProcessor___init__">
__init__</a>
</td>
<td>Constructor.</td>
</tr>
<tr>
<td>
</td>
<td class="methodbg">
<a href="#method-TemplateProcessor_process">
process</a>
</td>
<td>Process a compiled template. Return the result as string.</td>
</tr>
<tr>
<td>
</td>
<td class="methodbg">
<a href="#method-TemplateProcessor_set">
set</a>
</td>
<td>Associate a value with top-level template variable or loop.</td>
</tr>
<tr>
<td>
</td>
<td class="methodbg">
<a href="#method-TemplateProcessor_reset">
reset</a>
</td>
<td>Reset the template data.</td>
</tr>
</table>
</li>
<li>
<p>
<a href="#class-TemplateError">TemplateError</a>:
Fatal exception. Raised on runtime or template syntax errors. </p>
</li>
<li>
<p>
<a href="#class-Template">Template</a>:
This class represents a compiled template. </p>
<table border="0" cellpadding="3">
<tr>
<td>
</td>
<td class="methodbg">
<a href="#method-Template_is_uptodate">
is_uptodate</a>
</td>
<td>Check whether the compiled template is uptodate.</td>
</tr>
</table>
</li>
<li>
<p>
<a href="#class-TemplateCompiler">TemplateCompiler</a>:
Preprocess, parse, tokenize and compile the template. </p>
<table border="0" cellpadding="3">
<tr>
<td>
</td>
<td class="methodbg">
<a href="#method-TemplateCompiler___init__">
__init__</a>
</td>
<td>Constructor.</td>
</tr>
<tr>
<td>
</td>
<td class="methodbg">
<a href="#method-TemplateCompiler_compile_string">
compile_string</a>
</td>
<td>Compile template from a string.</td>
</tr>
<tr>
<td>
</td>
<td class="methodbg">
<a href="#method-TemplateCompiler_compile">
compile</a>
</td>
<td>Compile template from a file.</td>
</tr>
</table>
</li>
<li>
<p>
<a href="#class-TemplateManager">TemplateManager</a>:
Class that manages compilation and precompilation of templates. </p>
<table border="0" cellpadding="3">
<tr>
<td>
</td>
<td class="methodbg">
<a href="#method-TemplateManager___init__">
__init__</a>
</td>
<td>Constructor.</td>
</tr>
<tr>
<td>
</td>
<td class="methodbg">
<a href="#method-TemplateManager_update">
update</a>
</td>
<td>Update (recompile) a compiled template.</td>
</tr>
<tr>
<td>
</td>
<td class="methodbg">
<a href="#method-TemplateManager_prepare">
prepare</a>
</td>
<td>Preprocess, parse, tokenize and compile the template.</td>
</tr>
</table>
</li>
</ul>
<hr></hr>
<!-- documentation of functions -->
<hr></hr>
<!-- documentation of classes -->
<!-- class: TemplateProcessor -->
<h2>CLASS: <a name="class-TemplateProcessor"></a>TemplateProcessor</h2>
<p><strong>Fill the template with data and process it.</strong></p>
<p>This class provides actual processing of a compiled template.
Use it to set template variables and loops and then obtain
result of the processing.</p>
<!-- table of methods of class TemplateProcessor -->
<p><strong>METHODS:</strong></p>
<table border="0" cellpadding="3">
<tr>
<td> </td>
<td class="methodbg">
<a href="#method-TemplateProcessor___init__">
__init__</a>
</td>
<td>Constructor.</td>
</tr>
<tr>
<td> </td>
<td class="methodbg">
<a href="#method-TemplateProcessor_process">
process</a>
</td>
<td>Process a compiled template. Return the result as string.</td>
</tr>
<tr>
<td> </td>
<td class="methodbg">
<a href="#method-TemplateProcessor_set">
set</a>
</td>
<td>Associate a value with top-level template variable or loop.</td>
</tr>
<tr>
<td> </td>
<td class="methodbg">
<a href="#method-TemplateProcessor_reset">
reset</a>
</td>
<td>Reset the template data.</td>
</tr>
</table>
<hr></hr>
<!-- documentation of methods of class TemplateProcessor -->
<!-- method __init__ -->
<h3>METHOD: <a name="method-TemplateProcessor___init__"></a>
__init__()</h3>
<p>
<strong><em>Constructor.</em></strong>
<small>(class
<a href="#class-TemplateProcessor">TemplateProcessor</a>)
</small>
</p>
<!-- parameters of method __init__ -->
<p><strong>PARAMETERS:</strong></p>
<pre>__init__(html_escape=1, magic_vars=1, global_vars=0, debug=0)</pre>
<ul>
<li>
<p><strong>html_escape</strong></p>
<p><strong><em>Enable or disable HTML escaping of variables.</em></strong></p>
<p>This optional parameter is a flag that can be used to enable or
disable automatic HTML escaping of variables.
All variables are by default automatically HTML escaped.
The escaping process substitutes HTML brackets, ampersands and
double quotes with appropriate HTML entities.</p>
</li>
<li>
<p><strong>magic_vars</strong></p>
<p><strong><em>Enable or disable loop magic variables.</em></strong></p>
<p>This parameter can be used to enable or disable
"magic" context variables, that are automatically defined inside
loops. Magic variables are enabled by default.</p>
<p>Refer to the language specification for description of these
magic variables.</p>
</li>
<li>
<p><strong>global_vars</strong></p>
<p><strong><em>Globally activate global lookup of variables.</em></strong></p>
<p>This optional parameter is a flag that can be used to specify
whether variables which cannot be found in the current scope
should be automatically looked up in enclosing scopes.</p>
<p>Automatic global lookup is disabled by default. Global lookup
can be overriden on a per-variable basis by the
<strong>GLOBAL</strong> parameter of a <strong>TMPL_VAR</strong>
statement.</p>
</li>
<li>
<p><strong>debug</strong></p>
<p><strong><em>Enable or disable debugging messages.</em></strong></p>
</li>
</ul>
<hr></hr>
<!-- method process -->
<h3>METHOD: <a name="method-TemplateProcessor_process"></a>
process()</h3>
<p>
<strong><em>Process a compiled template. Return the result as string.</em></strong>
<small>(class
<a href="#class-TemplateProcessor">TemplateProcessor</a>)
</small>
</p>
<p>This method actually processes a template and returns
the result.</p>
<p><strong>RETURN VALUE:</strong></p>
<p>Result of the processing as string.</p>
<!-- parameters of method process -->
<p><strong>PARAMETERS:</strong></p>
<pre>process(template, part=None)</pre>
<ul>
<li>
<p><strong>template</strong></p>
<p><strong><em>A compiled template.</em></strong></p>
<p>Value of this parameter must be an instance of the
<em>Template</em> class created either by the
<em>TemplateManager</em> or by the <em>TemplateCompiler</em>.</p>
</li>
<li>
<p><strong>part</strong></p>
<p><strong><em>The part of a multipart template to process.</em></strong></p>
<p>This parameter can be used only together with a multipart
template. It specifies the number of the part to process.
It must be greater than zero, because the parts are numbered
from one.</p>
<p>The parts must be processed in the right order. You
cannot process a part which precedes an already processed part.</p>
<p>If this parameter is not specified, then the whole template
is processed, or all remaining parts are processed.</p>
</li>
</ul>
<hr></hr>
<!-- method set -->
<h3>METHOD: <a name="method-TemplateProcessor_set"></a>
set()</h3>
<p>
<strong><em>Associate a value with top-level template variable or loop.</em></strong>
<small>(class
<a href="#class-TemplateProcessor">TemplateProcessor</a>)
</small>
</p>
<p>A template identifier can represent either an ordinary variable
(string) or a loop.</p>
<p>To assign a value to a string identifier pass a scalar
as the 'value' parameter. This scalar will be automatically
converted to string.</p>
<p>To assign a value to a loop identifier pass a list of mappings as
the 'value' parameter. The engine iterates over this list and
assigns values from the mappings to variables in a template loop
block if a key in the mapping corresponds to a name of a variable
in the loop block. The number of mappings contained in this list
is equal to number of times the loop block is repeated in the
output.</p>
<p><strong>RETURN VALUE:</strong></p>
<p>No return value.</p>
<!-- parameters of method set -->
<p><strong>PARAMETERS:</strong></p>
<pre>set(var, value)</pre>
<ul>
<li>
<p><strong>var</strong></p>
<p><strong><em>Name of template variable or loop.</em></strong></p>
</li>
<li>
<p><strong>value</strong></p>
<p><strong><em>The value to associate.</em></strong></p>
</li>
</ul>
<hr></hr>
<!-- method reset -->
<h3>METHOD: <a name="method-TemplateProcessor_reset"></a>
reset()</h3>
<p>
<strong><em>Reset the template data.</em></strong>
<small>(class
<a href="#class-TemplateProcessor">TemplateProcessor</a>)
</small>
</p>
<p>This method resets the data contained in the template processor
instance. The template processor instance can be used to process
any number of templates, but this method must be called after
a template is processed to reuse the instance,</p>
<p><strong>RETURN VALUE:</strong></p>
<p>No return value.</p>
<!-- parameters of method reset -->
<p><strong>PARAMETERS:</strong></p>
<pre>reset(keep_data=0)</pre>
<ul>
<li>
<p><strong>keep_data</strong></p>
<p><strong><em>Do not reset the template data.</em></strong></p>
<p>Use this flag if you do not want the template data to be erased.
This way you can reuse the data contained in the instance of
the <em>TemplateProcessor</em>.</p>
</li>
</ul>
<hr></hr>
<hr></hr>
<!-- class: TemplateError -->
<h2>CLASS: <a name="class-TemplateError"></a>TemplateError</h2>
<p><strong>Fatal exception. Raised on runtime or template syntax errors.</strong></p>
<p>This exception is raised when a runtime error occurs or when a syntax
error in the template is found. It has one parameter which always
is a string containing a description of the error.</p>
<p>All potential IOError exceptions are handled by the module and are
converted to TemplateError exceptions. That means you should catch the
TemplateError exception if there is a possibility that for example
the template file will not be accesssible.</p>
<p>The exception can be raised by constructors or by any method of any
class.</p>
<p>The instance is no longer usable when this exception is raised.</p>
<!-- table of methods of class TemplateError -->
<hr></hr>
<!-- documentation of methods of class TemplateError -->
<hr></hr>
<!-- class: Template -->
<h2>CLASS: <a name="class-Template"></a>Template</h2>
<p><strong>This class represents a compiled template.</strong></p>
<p>This class provides storage and methods for the compiled template
and associated metadata. It's serialized by pickle if we need to
save the compiled template to disk in a precompiled form.</p>
<p>You should never instantiate this class directly. Always use the
<em>TemplateManager</em> or <em>TemplateCompiler</em> classes to
create the instances of this class.</p>
<p>The only method which you can directly use is the <em>is_uptodate</em>
method.</p>
<!-- table of methods of class Template -->
<p><strong>METHODS:</strong></p>
<table border="0" cellpadding="3">
<tr>
<td> </td>
<td class="methodbg">
<a href="#method-Template_is_uptodate">
is_uptodate</a>
</td>
<td>Check whether the compiled template is uptodate.</td>
</tr>
</table>
<hr></hr>
<!-- documentation of methods of class Template -->
<!-- method is_uptodate -->
<h3>METHOD: <a name="method-Template_is_uptodate"></a>
is_uptodate()</h3>
<p>
<strong><em>Check whether the compiled template is uptodate.</em></strong>
<small>(class
<a href="#class-Template">Template</a>)
</small>
</p>
<p>Return true if this compiled template is uptodate.
Return false, if the template source file was changed on the
disk since it was compiled.
Works by comparison of modification times.
Also takes modification times of all included templates
into account.</p>
<p><strong>RETURN VALUE:</strong></p>
<p>True if the template is uptodate, false otherwise.</p>
<!-- parameters of method is_uptodate -->
<p><strong>PARAMETERS:</strong></p>
<pre>is_uptodate(compile_params=None)</pre>
<ul>
<li>
<p><strong>compile_params</strong></p>
<p><strong><em>Only for internal use.</em></strong></p>
<p>Do not use this optional parameter. It's intended only for
internal use by the <em>TemplateManager</em>.</p>
</li>
</ul>
