doc-single.html

Below we contrast the difference between static and dynamic includes. A
dynamic include is included on each request; a static include is inserted at
compile time. A static include runs in the same context, while a dynamic
include has a separate context.<p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/include.spy</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b><font color="#CC00CC">[[.import name=include]]</font>
&lt;html&gt;&lt;body&gt;
  main file&lt;br&gt;
  &lt;hr&gt;
  <font color="#0000CC">[[
    context = {'foo': 'old value'}
    result=include.spyce('include.spi', context)
  ]]</font>
  &lt;hr&gt;
  main file again&lt;br&gt;
  context: <font color="#CC0000">[[=context]]</font>&lt;br&gt;
  return value: <font color="#CC0000">[[=result]]</font>&lt;br&gt;
&lt;/body&gt;&lt;/html&gt;
</b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/include.spy">Run this code</a></b>
    </font>
</td></tr></table>
<p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/include.spi</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b>begin include&lt;br&gt;
context: <font color="#CC0000">[[=include.context ]]</font>&lt;br&gt;
from: <font color="#CC0000">[[=request.stack()[-2] ]]</font>&lt;br&gt;
foo was <font color="#CC0000">[[=include.vars.foo]]</font>&lt;br&gt;
setting foo to 'new value' <font color="#0000CC">[[include.vars.foo = 'new value']]</font>&lt;br&gt;
returing 'retval'&lt;br&gt;
end include&lt;br&gt;
<font color="#0000CC">[[ return 'retval' ]]</font>
</b></font></pre>
  </font>
</td></tr></table>
<p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/includestatic.spy</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b>&lt;html&gt;&lt;body&gt;
  <font color="#0000CC">[[x=1]]</font>
  main file&lt;br&gt;
  x=<font color="#CC0000">[[=x]]</font>&lt;br&gt;
  &lt;hr&gt;
  <font color="#CC00CC">[[.include file=&quot;includestatic.spi&quot;]]</font>
  &lt;hr&gt;
  main file again&lt;br&gt;
  x=<font color="#CC0000">[[=x]]</font>
&lt;/body&gt;&lt;/html&gt;
</b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/includestatic.spy">Run this code</a></b>
    </font>
</td></tr></table>
<p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/includestatic.spi</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b>begin included file&lt;br&gt;
changing value of x&lt;br&gt;
<font color="#0000CC">[[x=2]]</font>
end included file&lt;br&gt;
</b></font></pre>
  </font>
</td></tr></table>
<p>
<big><a name="mod_internal"></a><b>3.8.11. <font color=#ee0000><i>Internal modules</i></font></b></big><p>


These modules are used internally by Spce. Documentation is included for
those curious about Spyce internals; ordinarily you will never use these
modules directly.

The error module is implicitly loaded and provides error-handling
functionality. An error is any <a
href="#runtime_except">unhandled runtime exception</a> that
occurs <b>during Spyce processing</b>. This mechanism does not include
exceptions that are not related to Spyce processing (i.e. server-related
exceptions), that can be caused before or after Spyce processing by invalid
syntax, missing files and file access restrictions. To install a server-level
error handler use a <a href="#runtime_common">configuration
file</a>. The default page-level error handler can also be modified in the <a
href="#runtime_common">configuration file</a>. This module
allows the user to install page-level error handling code, overriding the
default page-level handler, by using one of the following functions: <p>
<ul>
<li><b>setStringHandler</b>( string ): <br> Installs a function that will
processes the given <b>string</b>, as Spyce code, for error handling.
</li><p>
<li><b>setFileHandler</b>( uri ): <br> Installs a function that will
processes the given <b>uri</b> for error handling. </li><p>
<li><b>setHandler</b>( fn ): <br> Installs the <b>fn</b> function for error
handling. The function is passed one parameter, a reference to the error
module. From this, all the error information as well as references to other
modules and Spyce objects can be accessed.</li><p>
</ul>
The error module provides the following information about an error: <p>
<ul>
<li><b>isError</b>(): <br> Returns whether an error is being handled.
</li><p>
<li><b>getMessage</b>(): <br> Return the error message; the string of the
object that was raised, or None if there is no current error. </li><p>
<li><b>getType</b>(): <br> Return the error type; the type of the object
that was raised, or None if there is no current error. </li><p>
<li><b>getFile</b>(): <br> Return the file where the error was raised, or
None if there is no current error. </li><p>
<li><b>getTraceback</b>(): <br> Return the stack trace as an array of
tuples, or None if there is no current error. Each tuple entry is of the
form: (file, line numbers, function name, code context).</li><p>
<li><b>getString</b>(): <br> Return the string of the entire error (the
string representation of the message, type, location and stack trace), or
None if there is no current error. </li><p>
</ul>
The default error handling function uses the following string handler:
<table border=0 align=center><tr><td>
<pre><font color="#000000"><b>
<font color="#CC00CC">[[.module name=transform]]</font>
<font color="#0000CC">[[transform.expr('html_encode')]]</font>
&lt;html&gt;
&lt;title&gt;Spyce exception: <font color="#CC0000">[[=error.getMessage()]]</font>&lt;/title&gt;
&lt;body&gt;
&lt;table cellspacing=10 border=0&gt;
  &lt;tr&gt;&lt;td colspan=2&gt;&lt;h1&gt;Spyce exception&lt;/h1&gt;&lt;/td&gt;&lt;/tr&gt;
  &lt;tr&gt;&lt;td valign=top align=right&gt;&lt;b&gt;File:&lt;/b&gt;&lt;/td&gt;&lt;td&gt;<font color="#CC0000">[[=error.getFile()]]</font>&lt;/tr&gt;
  &lt;tr&gt;&lt;td valign=top align=right&gt;&lt;b&gt;Message:&lt;/b&gt;&lt;/td&gt;
    &lt;td&gt;&lt;pre&gt;<font color="#CC0000">[[=error.getMessage()]]</font>&lt;/pre&gt;&lt;/tr&gt;
  &lt;tr&gt;&lt;td valign=top align=right&gt;&lt;b&gt;Stack:&lt;/b&gt;&lt;/td&gt;&lt;td&gt;
    <font color="#0000CC">[[\
      L = list(error.getTraceback())
      L.reverse()
    ]]</font>
    <font color="#0000CC">[[ for frame in L: { ]]</font>
      <font color="#CC0000">[[=frame[0] ]]</font>:<font color="#CC0000">[[=frame[1] ]]</font>, in <font color="#CC0000">[[=frame[2] ]]</font>:&lt;br&gt;
      &lt;table border=0&gt;&lt;tr&gt;&lt;td width=10&gt;&lt;/td&gt;&lt;td&gt;
        &lt;pre&gt;<font color="#CC0000">[[=frame[3] ]]</font>&lt;/pre&gt;
      &lt;/td&gt;&lt;/tr&gt;&lt;/table&gt;
    <font color="#0000CC">[[ } ]]</font>
    &lt;/td&gt;&lt;/tr&gt;
&lt;/table&gt;
&lt;/body&gt;&lt;/html&gt;
</b></font></pre>
</td></tr></table>
<p>
The example below shows the error module in use. Error handling can often be
used to send emails notifying webmasters of problems, as this example shows.
<p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/error.spy</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b><font color="#0000CC">[[error.setFileHandler('error.spi') ]]</font>
This is a page with an error...
<font color="#0000CC">[[ raise 'an error' ]]</font>
</b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/error.spy">Run this code</a></b>
    </font>
</td></tr></table>
<p>
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/error.spi</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b>&lt;h1&gt;Oops&lt;/h1&gt;
An error occurred while processing your request. 
We have logged this for our webmasters, and they 
will fix it shortly. We apologize for the inconvenience.
In the meantime, please use the parts of our site that 
actually do work... &lt;a href=&quot;somewhere&quot;&gt;somewhere&lt;/a&gt;.
<font color="#0000CC">[[\
  # could redirect the user immediately
  #response.getModule('redirect').external('somewhere.spy')

  # could send an email
  import time
  msg = '''
time: %s
error: %s
env: %s
other info...
''' % (
    time.asctime(time.localtime(time.time())), 
    error.getString(),
    request.env()
  )
  #function_to_send_email('webmaster@foo.com', msg)

  #or perform other generic error handling...
]]</font>
</b></font></pre>
  </font>
</td></tr></table>
<p>
This mechanism is not a subsititute for proper exception handling within the
code itself, and should not be abused. It does, however, serve as a useful
catch-all for bugs that slip through the cracks. <p>

The stdout module is loaded implicitly and redirects Python's <font
face=courier>sys.stdout</font> (in a thread-safe manner) to the appropriate
response object for the duration of Spyce processing. This allows one to use
<font face=courier>print</font>, without having to write <font
face=courier>print&nbsp;&gt;&gt;&nbsp;response,&nbsp;...</font>. The stdout
module provides a variable <font face=courier>stdout.stdout</font>, which
refers to the original stream, but is unlikely to be needed. It may also be
useful to know that <font face=courier>sys.stderr</font> is, under many
configurations, connected to the webserver error log. <p>
In addition, the stdout module provides the following functions for capturing
or redirecting output:
<ul>
<li><b>push</b>( [filename] ): <br> Begin capturing output. Namely, the current
output stream is pushed onto the stack and replaced with a memory buffer. An
optional <b>filename</b> may be associated with this operation (see pop()
method below). </li> <p>
<li><b>pop</b>(): <br> Close current output buffer, and return the captured
output as a string. If a filename was associated with the push(), then the
string will also be written to that file. </li> <p>
<li><b>capture</b>(f, [*args], [**kwargs] ): <br> Push the current stream,
call the given function <b>f</b> with any supplied arguments <b>*args</b>
and keyword arguments <b>**kwargs</b>, and then pop it back. Capture returns
a tuple (r,s), where r is the result returned by f and s is a string of its
output. </li> <p>
</ul> <p>
The example below show how the module is used:
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/stdout.spy</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b>&lt;html&gt;&lt;body&gt;
  <font color="#0000CC">[[ print '''Using the stdout module redirects 
    stdout to the response object, so you can use
    &lt;b&gt;print&lt;/b&gt;!''']]</font>&lt;br&gt;
  redirecting stdout can be used to...
  <font color="#0000CC">[[stdout.push()]]</font>
  <font color="#0000CC">[[print 'capture']]</font> out<font color="#CC0000">[[='put']]</font>
  <font color="#0000CC">[[cached = stdout.pop()]]</font>
  ... for later: &lt;br&gt;
  <font color="#CC0000">[[=cached]]</font>
&lt;/body&gt;&lt;/html&gt;
</b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/stdout.spy">Run this code</a></b>
    </font>
</td></tr></table>


This module is used internally by Spyce, not usually by users. Documentation is
included for those curious about Spyce internals. The spylambda module is
loaded implicitly and allows the definition of functions based on Spyce
scripts; see <a href="#lang_lambda">Spyce Lambdas</a>. The
spylambda module provides the following methods:
<ul>
<li><b>define</b>( args, code, [memoize] ): <br> Returns a function that
accepts the given <b>args</b> and executes the Spyce script defined by the
<b>code</b> parameter. Note that the code is compiled immediately and that
<font face=courier>spyce.spyceSyntaxError</font> or <font
face=courier>spyce.spycePythonError</font> exceptions can be thrown for
invalid code arguments. The optional <b>memoize</b> parameter sets whether
the spyce can or can not be memoized, with the default being false.
Memoizing a function means capturing the result and output and caching them,
keyed on the function parameters. Later, if a function is called again with
the same parameters, the cached information is returned, if it exists, and
the function may not actually be called. Thus, you should only memoize
functions that are truly functional, i.e. they do not have side-effects:
they only return a value and output data to the response object, and their
behaviour depends exclusively on their parameters. If you memoize code that
does have side-effects, those side-effects may not occur on every
invocation. </li> <p>
<li><b>__call__</b>( args, code, _spyceCache ): <br> This is an alias to the
define function. Because of the special method name, the spylambda module
object can be <a
href="http://www.python.org/doc/current/ref/callable-types.html">called as
if it were a function</a>. </li> <p>
</ul>

The taglib module is loaded implicitly and supports
<a href="#tag">Active Tags</a>
functionality. The taglib module provides the following
methods:
<ul>
<li><b>load</b>( libname, [libfrom], [libas] ): <br> Loads a tag library
class named <b>libname</b> from a file called <b>libfrom</b> in the search
path, and installed it under the tag prefix <b>libas</b>. The default for
libfrom is <font face=courier><i>libname</i>.py</font>. The default for
libas is <font face=courier><i>libname</i></font>. Once installed, a library
name is its unique tag prefix. </li> <p>
<li><b>unload</b>( libname ): <br> Unload a tag library that is installed
under the <b>libname</b> prefix. This is usually performed only at the end
of a request. </li> <p>
<li><b>tagPush</b>( libname, tagname, pair ): <br> Push a new tag object for
a <b>libname</b>:<b>tagname</b> tag onto the tag stack. The <b>pair</b>
parameter is a flag indicating whether this is a singleton or a paired tag.
</li> <p>
<li><b>tagPop</b>(): <br> Pop the current tag from the tag stack. </li> <p>
<li><b>getTag</b>(): <br> Return the current tag object. </li> <p>
<li><b>outPush</b>(): <br> Begin capturing the current output stream. This
is usually called by the tagBegin method. </li> <p>
<li><b>outPopCond</b>(): <br> End capturing the current output stream, and
return the captured contents. It will only "pop" once, even if called
multiple times for the same tag. This method is usually called by either the
tagEnd(), tagCatch, or tagPop() methods. </li> <p>
<li><b>tagBegin</b>( attrs ): <br> This method sets the tag output and
variable environment, and then calls the tag's <b>begin()</b> method with
the given <b>attrs</b> tag attribute dictionary. This method returns a flag,
and the tag body must be processed if and only if this flag is true. </li>
<p>
<li><b>tagBody</b>(): <br> This method sets the tag output and variable
environment, and then calls the tag's <b>body()</b> method with the captured
output of the body processing. If this method returns true, then the
processing of the body must be repeated. </li> <p>
<li><b>tagEnd</b>(): <br> This method sets the tag output and variable
environment, and then calls the tag's <b>end()</b> method. This method must
be called if the tagBegin() method completes successfully in order to
preserve tag semantics. </li> <p>
<li><b>tagCatch</b>(): <br> This method should be called if any of the
tagBegin, tagBody or tagEnd methods raise an exception. It calls the tag's
<b>catch()</b> method with the current exception. </li> <p>
</ul>

<big><a name="mod_new"></a><b>3.8.12. <font color=#ee0000><i>Writing Modules</i></font></b></big><p>


Writing your own Spyce modules is simple.
<p>
A Spyce modules is simply a Python class that exposes specific methods
to the Spyce server. The most important are <b>start</b>, <b>finish</b>,
and <b>init</b>. With these,
a Spyce module may access the
internal request and response structures or alter the behaviour of the
runtime engine in some way.
<p>Let us begin with a basic example
called myModule. It is a module that implements one function named foo().
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/myModule.py</b></font>
</td></tr><tr><td>
  <font face=courier>
    
<style>    
.STRING {
  color: #a0522d;
}
.COMMENT {
  color: #ff7448;
  font-family: serif;
}
.KEYWORD {
  color: #9e79af;
}
.FUNCTION {
  color: #0074ef;
}
</style>
<pre>
<span class="KEYWORD">from</span> <span class="NAME">spyceModule</span> <span class="KEYWORD">import</span> <span class="NAME">spyceModule</span><span class="NEWLINE">
</span><span class="NL">
</span><span class="KEYWORD">class</span> <span class="FUNCTION">myModule</span><span class="OP">(</span><span class="NAME">spyceModule</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">  </span><span class="KEYWORD">def</span> <span class="FUNCTION">foo</span><span class="OP">(</span><span class="NAME">self</span><span class="OP">)</span><span class="OP">:</span><span class="NEWLINE">
</span><span class="INDENT">    </span><span class="KEYWORD">print</span> <span class="STRING">'foo called'</span><span class="NEWLINE">
</span><span class="NL">
</span><span class="DEDENT"></span><span class="DEDENT"></span><span class="ENDMARKER"></span>
</pre>
    
  </font>
</td></tr></table>
<p>
Saving this code in <font face=courier>myModule.py</font> in the same
directory as the Spyce script, or somewhere on the module path, we could use
it as expected: <p>
<table align=center border=0><tr><td><font face=courier>

<b><pre>[[.import name=myModule]]
[[ myModule.foo() ]]
</pre></b>
</font></td></tr></table>
<p>
A Spyce module can be any Python class that derives from
<b>spyceModule.spyceModule</b>. When it is loaded, Spyce assigns it a
__file__ attribute indicating its source location.
Do not override the <b> __init__(...)</b>
method because it is inherited from spyceModule and has an fixed signature
that is expected by the Spyce engine's module loader. The inherited method
accepts a Spyce API object, a <a
href="http://www.python.org/doc/current/lib/module-Bastion.html">Bastion</a>
of <b>spyce.spyceWrapper</b>, an internal engine object, and stores it in
<b>self._api</b>. This is the building block for all the functionality that
any module provides. The available API methods of the wrapper are (listed in
spyceModule.spyceModuleAPI):
<ul>

<li> <b>getFilename</b>: Return filename of current Spyce</li>

<li> <b>getCode</b>: Return processed Spyce (i.e. Python) code</li>

<li> <b>getCodeRefs</b>: Return python-to-Spyce code line references</li>

<li> <b>getModRefs</b>: Return list of import references in Spyce code</li>

<li> <b>getServerObject</b>: Return unique (per engine instance) server object</li>

<li> <b>getServerGlobals</b>: Return server configuration globals</li>

<li> <b>getServerID</b>: Return unique server identifier</li>

<li> <b>getModules</b>: Return references to currently loaded modules</li>

<li> <b>getModule</b>: Get module reference. The module is dynamically loaded and initialised
    if it does not exist (ie. if it was not explicitly imported, but requested
    by another module during processing)</li>

<li> <b>setModule</b>: Add existing module (by reference) to Spyce namespace (used for includes)</li>

<li> <b>getGlobals</b>: Return the Spyce global namespace dictionary</li>

<li> <b>registerModuleCallback</b>: Register a callback for modules change</li>

<li> <b>unregisterModuleCallback</b>: Unregister a callback for modules change</li>

<li> <b>getRequest</b>: Return internal request object</li>

<li> <b>getResponse</b>: Return internal response object</li>

<li> <b>setResponse</b>: Set internal response object</li>

<li> <b>registerResponseCallback</b>: Register a callback for when internal response changes</li>

<li> <b>unregisterResponseCallback</b>: Unregister a callback for when internal response changes</li>

<li> <b>spyceString</b>: Return a spyceCode object of a string</li>

<li> <b>spyceFile</b>: Return a spyceCode object of a file</li>

<li> <b>spyceModule</b>: Return Spyce module class</li>

<li> <b>spyceTaglib</b>: Return Spyce taglib class</li>

<li> <b>setStdout</b>: Set the stdout stream (thread-safe)</li>

<li> <b>getStdout</b>: Get the stdout stream (thread-safe)</li>

</ul> <p>
For convenience, one can sub-class the <b>spyceModulePlus</b> class instead of
the regular <b>spyceModule</b>. The spyceModulePlus defines a
<b>self.modules</b> field, which can be used to acquire references to other
modules loaded into the Spyce environment. The <i>response</i> module, for
instance, would be referenced as <i>self.modules.response</i>. Modules are
loaded on demand, if necessary. The spyceModulePlus also contains a
<b>self.globals</b> field, which is a reference to the Spyce global namespace
dictionary, though this should rarely be needed. <p>
<b>Note:</b> It is not expected that many module writers will need the entire
API functionality. In fact, the vast majority of modules will use a small
portion of the API, if at all. Many of these functions are included for just
one of the standard Spyce modules that needs to perform some esoteric
function. <p>
Three Spyce module methods, <b>start()</b>, <b>init([args])</b> and
<b>finish(error)</b> are special in that they are automatically called by the
runtime during Spyce request startup, processing and cleanup, respectively.
The modules are started in the order in which module directives appear in the
file, before processing begins. The implicitly loaded modules are always
loaded first. The init method is called during Spyce processing at the
location of the module directive in the file, with the optional args attribute
is passed as the arguments of this call. Finally, after Spyce processing is
complete, the modules are finalized in reverse order. If there is an unhandled
exception, it will be wrapped in a spyce.spyceException object and passed as
the first parameter to finish(). During successful completion of Spyce
processing (i.e. without exception), the error parameter is None. The default
inherited start, init and finish methods from spyceModule are noops. <p>
<b>Note 2:</b> When writing a Spyce module, consider carefully why you are
selecting a Spyce module over a regular Python module. If it is just code,
that does not interact with the Spyce engine, then a regular Python <font
face=courier>import</font> instead of an Spyce <font
face=courier>[[.import]]</font> can just as easily bring in the necessary
code, and is preferred. In other words, choose a Spyce module only when there
is a need for per-request initialization or for one of the engine APIs. <p>
Module writers are encouraged to look at the existing standard modules as
examples and the definitions of the core Spyce objects in <font
face=courier>spyce.py</font> as well. If you write or use a novel Spyce
module that you think is of general use, please email your
<a href="https://svn.sourceforge.net/svnroot/spyce/trunk/spyce/contrib/">contribution</a>,
or a link to it. Also, please keep in mind that the standard modules are designed
with the goal of being minimalist. Much functionality is readily available
using the Python language libraries. If you think that they should be
expanded, also please send a note. <p>

<big><a name="tag"></a><b>3.9. <font color=#ee0000>Tags</font></b></big><p>


The previous chapter discussed the Spyce module facility, the standard Spyce
modules and how users can create their own modules to extend Spyce. Spyce
functionality can also be extended via active tags, which are defined in tag
libraries. This chapter describes what Spyce active tags are, and how they are
used. We then describe each of the standard active tag libraries and, finally,
how to define <a href="#tag_new2">new tags libraries</a>. <p>
It is important, from the outset, to define what an active tag actually does.
A few illustrative examples may help. The examples below all use tags that are
defined in the <a href="#tag_core">core tag library</a>,
that has been installed under the <b>spy</b> prefix, as is the default. <p>
<ul>
<li><font face=courier>&lt;spy:parent&nbsp;src="parent.spi"/&gt;</font> <br>
Wraps the current page in the parent template found at parent.spi in the
same directory.
<li><font face=courier> &lt;spy:for items="=range(5)"&gt; <br>
&nbsp;&nbsp;&lt;spy:print value="=foo"/&gt; <br> &lt;/spy:for&gt; </font>
<br> As expected, these tags will print the value of <b>foo</b>, set to
<font face=courier>bar</font> above, 5&nbsp;times. </li> <p>
</ul>
<b>Common mistake:</b> Don't use [[= ]] to send values to active tag attributes:
[[= ]] sends its result directly to the output stream. And since those tokens
are parsed with higher precedence than the tag markup, Spyce won't recognize
your tag at all and will print it verbatim to the client.
Instead, prefix an expression with =, as in "=range(5)" above, and Spyce will
<i>eval</i> it before sending it to the tag.
<p>
Note that the same output could have been achieved in many different ways, and
entirely without active tags. The manner in which you choose to organize your
script or application, and when you choose active tags over other
alternatives, is a matter of personal preference. Notice also that active tags
entirely control their output and what they do with their attributes and the
result of processing their bodies (in fact, whether the body of the tag is
even processed). Tags can even supply additional syntax constraints on their
attributes that will be enforced at compile-time. Most commonly a tag could
require that certain attributes exist, and possibly that it be used only as a
single or only as a paired (open and close) tag. Unlike early versions of
HTML, active tags must be strictly balanced, and this will be enforced by the
Spyce compiler. <p>
Below, each individual standard Spyce tag library is documented, followed by a
description of how one would write a <a href="#tag_new">new
active tag library</a>. The following general information will be useful for
reading that material.
<ul>
<li>Active tags are installed using the <font
face=courier>[[.taglib]]</font>
<a href="#lang_directive">directive</a>, under some prefix.
Tag libraries may also be be loaded globally in the config module; by default
the core and form libraries are preloaded.
Active tags are of the format <font
face=courier>&lt;pre:name&nbsp;...&nbsp;&gt;</font>, where <b>pre</b> is the
prefix under which the tag library was installed, and <b>name</b> is defined
by the tag library. In the following tag library documentation, the prefix
is omitted from the syntax. </li>
<li>The following notation is used in the documentation of the tag libraries
below:
<ul>
<li> &lt;name .../&gt; : The tag should be used as a singleton. </li>
<li> &lt;name ... &gt; ... &lt;/name&gt; : The tag should be used as an
open-close pair. </li>
<li> [ x (default)] : The attribute is optional. Attributes not enclosed in
brackets are required. </li>
<li> foo|<u>bar</u> : indicates that an attribute may be one of two
constant strings. The underlined value is the default. </li>
<li> <i>string</i> : an arbitrary string constant, never evaluated as Python </li>
<li> <i>exprstring</i> : may be a string constant, and may be of the form
<font face=courier>'=expr'</font>, where <font face=courier>expr</font> is
a Python expression that will be evaluated in the tag context. </li>
<li> <i>expr</i>: a Python expression. (Currently only the "data" parameters
of some form and core tags use this rather than exprstring.)
</li>
<li> <i>exports foo, *bar</i> Exports to the parent context
the variable foo and the variable
with the name given by the expression bar. Normally, implementation
details of tags will not affect the parent context, so you do not have
to worry about your variables being clobbered. Tags may, however,
export specific parts of their own context to the parent.
See, for example,
the let and for tags in the core taglib.
<b>Note:</b> exporting of variables whose name
cannot be determined at compile time is deprecated, and will be removed in Spyce 2.2.
</li>
</ul>
</ul> <p>
<big><a name="tag_core"></a><b>3.9.1. <font color=#ee0000><i>Core</i></font></b></big><p>


The core tag library is aliased as "spy" by default.
<p>
This library contains various frequently-used tags: the parent tag, login tags, 
and some tags for generating lists and tables from Python iterators.

<p>
<big><b>Parent Tag</b></big>
<ul>
  <li><font face=courier>&lt;<b><a name=parent>parent</a></b> [src=<i>url</i>] [other parameters] /&gt;</font>
  <br>
  Specifies a parent template to apply to the current page, which
  is passed to the parent as child._body.  Any extra parameters are also
  passed in the child dictionary.  If src is not given, 'parent.spi' used if it exists
  in the current directory; otherwise, the default parent
  is used as specified in the config module.
  <p>
  <table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/hello-templated.spy</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b><font color="#229922">&lt;spy:parent title=&quot;Hello, world!&quot; /&gt;</font>

<font color="#ff7448">[[-- Spyce can embed chunks of Python code, like this. --]]</font>
<font color="#0000CC">[[\
  import time
  t = time.ctime()
]]</font>

<font color="#ff7448">[[-- 
  pull the count from the GET variable.
  the int cast is necessary since request stores everything as a string 
--]]</font>
<font color="#0000CC">[[ for i in range(int(request.get1('count', 2))):{ ]]</font>
&lt;div&gt;Hello, world!&lt;/div&gt;
<font color="#0000CC">[[ } ]]</font>

The time is now <font color="#CC0000">[[= t ]]</font>.
</b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/hello-templated.spy">Run this code</a></b>
    </font>
</td></tr></table>

</ul>

<big><b>Login Tags</b></big>
<ul>
  <li><font face=courier>&lt;<b><a name=login>login</a></b> [validator=<i>function name</i>] /&gt;</font>
  <br>
  Generates a login form according to the template specified in your config file.
  If <b>validator</b> is not specified, the default validator from your config file is used.
  (<b>validator</b> may be the name of a function in a different Python module;
  just prefix it with the module name and Spyce will automaticall import it when
  necessary.)
  <p>
  <table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/login-optional.spy</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b>&lt;html&gt;&lt;body&gt;

<font color="#229922">&lt;f:form&gt;</font>
  <font color="#0000CC">[[ if request.login_id():{ ]]</font>
    You are logged in with user id <font color="#CC0000">[[= request.login_id() ]]</font>
    <font color="#229922">&lt;spy:logout /&gt;</font>
  <font color="#0000CC">[[ } else: { ]]</font>
    <font color="#229922">&lt;spy:login /&gt;</font>
    You are not logged in.  (You may login with username/password: spyce/spyce.)
  <font color="#0000CC">[[ } ]]</font>
  
  &lt;p&gt;
  (Here is some content that is the same before and after login.)
<font color="#229922">&lt;/f:form&gt;</font>

&lt;/body&gt;&lt;/html&gt;</b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/login-optional.spy">Run this code</a></b>
    </font>
</td></tr></table>


  <li><font face=courier>&lt;<b><a name=logout>logout</a></b> /&gt;</font>
  <br>
  Generates a logout button that will clear the cookie generated by <b>login</b>
  and <b>login_required</b>.
  <p>

  <li><font face=courier>&lt;<b><a name=login_required>login_required</a></b> [validator=<i>function name</i>] /&gt;</font>
  <br>
  If a valid login cookie is not present, generates a login form according to the 
	template specified in your config file, then halts execution of the current page.
  <p>
  (You may log in to this example as user <b>spyce</b>, password <b>spyce</b>.)
  <table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/login-required.spy</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b><font color="#229922">&lt;spy:parent title=&quot;Login example&quot; /&gt;</font>

<font color="#229922">&lt;f:form&gt;</font>
  <font color="#229922">&lt;spy:login_required /&gt;</font>

  You are logged in.
  <font color="#229922">&lt;spy:logout /&gt;</font>
<font color="#229922">&lt;/f:form&gt;</font>
</b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/login-required.spy">Run this code</a></b>
    </font>
</td></tr></table>

</ul>

<big><b>Convenience Tags</b></big>
<p>
These tags are shortcuts for creatings lists and tables.  As with 
the <a href="#tag_form">form tag library</a>, any python
iterator may be given as the data parameter.  Also as with the form tags,
any unrecognized parameters will be passed through to the generated HTML.

<ul>
  <li><font face=courier>&lt;<b><a name=ul>ul</a></b> data=<i>expr</i>] /&gt;</font>
  <br>
  Convenience tag for the common use of ul; equivalent to
  <blockquote>
  <tt><pre>
    &lt;ul>
    [[ for item in data:{ ]]
      &lt;li>[[= item ]]&lt;/li>
    [[ } ]]
    &lt;/ul>
  </pre></tt>
  </blockquote>

  <li><font face=courier>&lt;<b><a name=ol>ol</a></b> data=<i>expr</i>] /&gt;</font>
  <br>
  Like ul, but for ordered lists.<br><br>

  <li><font face=courier>&lt;<b><a name=dl>dl</a></b> data=<i>expr</i>] /&gt;</font>
  <br>
  Convenience tag for the common use of dl; equivalent to
  <blockquote>
  <tt><pre>
  &lt;dl>
  [[ for term, desc in data:{ ]]
    &lt;dt>[[= term ]]&lt;/dt>
    &lt;dd>[[= desc ]]&lt;/dd>
  [[ } ]]
  &lt;/dl>
  </pre></tt>
  </blockquote>

  <li><font face=courier>&lt;<b><a name=table>table</a></b> data=<i>expr</i>] /&gt;</font>
  <br>
  Convenience tag for the common use of table; equivalent to
  <blockquote>
  <tt><pre>
  &lt;table>
  [[ for row in data:{ ]]
    &lt;tr>
    [[ for cell in row:{ ]]
      &lt;td>[[= cell ]]&lt;/td>
    [[ } ]]
    &lt;/tr>
  [[ } ]]
  &lt;/table>
  </pre></tt>
  </blockquote>

</ul>

<big><a name="tag_form"></a><b>3.9.2. <font color=#ee0000><i>Form</i></font></b></big><p>


The form tag library is aliased as "spy" by default.
<p>
This library simplifies the generation and handling of forms by
automating away repetitive tasks. Let's take a look at a simple example:
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/formintro.spy</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b><font color="#229922">&lt;spy:parent title=&quot;Form tag intro&quot; /&gt;</font>

<font color="#229922">&lt;f:form&gt;</font>

&lt;div class=&quot;simpleform&quot;&gt;
  <font color="#229922">&lt;f:text name=&quot;text1&quot; label=&quot;Text input&quot; default=&quot;change me&quot; size=10 maxlength=30 /&gt;</font>
  <font color="#229922">&lt;f:text name=&quot;text2&quot; label=&quot;Text input 2&quot; value=&quot;change me&quot; size=10 maxlength=30 /&gt;</font>
&lt;/div&gt;

&lt;fieldset style=&quot;clear: both&quot;&gt;
  &lt;legend&gt;One or two?  Or both?&lt;/legend&gt;
  <font color="#229922">&lt;f:checkboxlist class=&quot;radio&quot; name=&quot;checkboxlist&quot; data=&quot;[(1, 'one'), (2, 'two')]&quot; /&gt;</font>
&lt;/fieldset&gt;

&lt;div style=&quot;clear: both&quot;&gt;<font color="#229922">&lt;f:submit /&gt;</font>&lt;/div&gt;

<font color="#229922">&lt;/f:form&gt;</font></b></font></pre>
  </font>
  </td></tr><tr><td align=right bgcolor="#cccccc">
    <font face="arial, helvetica" size="-1">
      <b><a href="/docs/examples/formintro.spy">Run this code</a></b>
    </font>
</td></tr></table>

<p>This demonstrates several properties of Spyce form tags:
<ul>
<li>Most tags take an optional label parameter; this is turned into an HTML label tag
associated with the form element itself.
<li>If you View Source in your browser while running this sample, you can
see that Spyce generates an id with the same value as the name parameter.
(You can override this by explicitly specifying a different id parameter,
if you need.)
<li>You can pass arbitrary parameters (such as the class parameter for &lt;f:form&gt;)
to a Spyce form tag; parameters that do not have special meaning to Spyce
will be passed through to the HTML output.
<li>Try changing the form values and submitting. By default, Spyce automatically
remembers the user input for you, unless you give a tag a <i>value</i>
parameter (or <i>selected</i> for collection elements), which has highest precedence.
Note the different behavior of text1 and text2 in this example.
<li>Spyce provides some higher-level tags such as checkboxlist that result in multiple
elements at the HTML level. For these tags, a "data" parameter is expected,
which is always interpreted as a Python expression.
Any iterable may be used as data, including generators and generator expressions
for those with recent Python versions. Typically data would come from the
database; here we're just using a literal list.
</ul>
<big><b>Handlers</b></big>
<p>
Active Handlers allow you to "attach" python functions to form submissions.
They are described in the
<a href="#tag_handlers">Active Handlers</a> manual page.
<p>
<big><b>Reference</b></big>
<p>
First, some general rules:
<p>The text displayed by a text-centric tag can come from one of three
places. In order of decreasing priority, these are
<ul>
<li>the <b>value</b> parameter
<li>the value submitted by the user is used
<li>the <b>default</b> parameter
</ul>
If none of these are found, the input will be empty.
<p>For determining whether option, radio, and checkbox tags are checked or selected,
a similar process is followed, with
<b>selected</b> and <b>checked</b> parameters as the highest-priority source.
The same parameters are used for select, radiolist, and checkboxlist tags;
the only difference is for the collection tags, you can also specify
multiple values in a Python list (or other iterable) in either the
<b>selected/checked</b> or <b>default</b> parameters.
<p>All tags except form and submit can be given names that tell Spyce how to
treat their submitted values when passing to an Active Handler function.
Adding ":int", ":float", ":bool", or ":list" is allowed. The first three
tell Spyce what kind of Python value to convert the submission to; ":list"
may be combined with these, or used separately, and tells Spyce to pass a
list of all values submitted instead of a single one.
(An example is given in the <a href="#tag_handlers">Active Handlers</a> page.)
Finally, here is the list of tags:
<ul>
<li><font face=courier>&lt;<b>form</b>
[method=<i>exprstring</i>]&nbsp;[action=<i>exprstring</i>]&nbsp;...&gt;&nbsp;&lt;/<b>form</b>&gt;</font>
<br> Begin a new form. The <b>method</b> parameter defaults
to 'POST'. The <b>action</b> parameter defaults to the current page.
</li> <p>
<li>
<font face=courier>&lt;<b><a name=submit>submit</a></b>
[handler=<i>exprstring</i>]&nbsp;[value=<i>exprstring</i>]&nbsp;...&nbsp;/&gt;
</font>
<br>Create a submit button. The <b>value</b> parameter is
emitted as the button text. If <b>handler</b> is given, Spyce will call the function(s)
it represents at the beginning of the page load after this button is clicked.
(Multiple function names may be separated with commas.)
<p>
If the handler is in a different [python] module, Spyce will automatically import it
before use.
<p>
A handler may take zero or more arguments.
For the first non-self argument (if present), Spyce always passes a
moduleFinder corresponding to the current
spyceWrapper object; it is customary to call this argument "api."
moduleFinder provides __getitem__ access to loaded modules; thus,
"api.request" would be the current request module. If a requested module
is not found, it is loaded.
<p>
(You can also directly access the wrapper with api._wrapper, providing
access to <a href="#mod_new">anything module authors have</a>,
but you will rarely if ever need to do this.)
<p>
For other handler function parameters, Spyce will pass the values for the
corresponding form input, or None if nothing was found in the GET or POST
variables.
<p>
See also the <a href="#tag_handlers">Active Handlers</a>
language section for a higher-level overview.
<p>
Limitation: currently, Active Handlers require resubmitting to the same spyce page;
of course, the handler method may perform an internal or external
<a href="#mod_redirect">redirect</a>.
</li> <p>
<li><font face=courier>&lt;<b>hidden</b>
name=<i>exprstring</i>&nbsp;[value=<i>exprstring</i>]&nbsp;[default=<i>exprstring</i>]&nbsp;.../&gt;</font>
<br> Create a hidden form field. The <b>name</b> parameter is evaluated and
emitted.
</li> <p>
<li><font face=courier>&lt;<b>text</b>
name=<i>exprstring</i>&nbsp;[value=<i>exprstring</i>]&nbsp;[default=<i>exprstring</i>]&nbsp;&nbsp;.../&gt;</font>
<br> Create a form text field. The <b>name</b> parameter is evaluated and
emitted.
</li> <p>
<li><font face=courier>&lt;<b>date</b>
name=<i>exprstring</i>&nbsp;[value=<i>exprstring</i>]&nbsp;[default=<i>exprstring</i>]&nbsp;[size=<i>exprstring</i>]&nbsp;[format=<i>exprstring</i>]&nbsp;.../&gt;</font>
<br> Create a form text field with a javascript date picker. Format defaults to MM/DD/YYYY. Maxlength is always len(format);
this is also the default size, but size may be overridden for aesthetics.
<li><font face=courier>&lt;<b>password</b>
name=<i>exprstring</i>&nbsp;[value=<i>exprstring</i>]&nbsp;[default=<i>exprstring</i>]&nbsp;[size=<i>exprstring</i>]&nbsp;[maxlength=<i>exprstring</i>]&nbsp;.../&gt;</font>
<br> Create a form password field. Parameters are the same as for <b>text</b>
fields, explained above. </li> <p>
<li><font face=courier>&lt;<b>textarea</b>
name=<i>exprstring</i>&nbsp;[value=<i>exprstring</i>]&nbsp;[rows=<i>exprstring</i>]&nbsp;[cols=<i>exprstring</i>]&nbsp;...&gt;default&lt;/<b>textarea</b>&gt;</font>
<br> Create a form textarea field. The <b>name</b> parameter is evaluated and
emitted. The <b>value</b> optional parameter is evaluated. A <b>default</b>
may be provided in the body of the tag. The value emitted is, in order of
decreasing priority: local tag value, value in submitted
request dictionary, local tag default. We search this list
for the first non-None value. The <b>rows</b> and <b>cols</b> optional
parameters are evaluated and emitted. </li> <p>
<li><font face=courier>&lt;<b>radio</b>
name=<i>exprstring</i>&nbsp;value=<i>exprstring</i>&nbsp;[checked]&nbsp;[default]&nbsp;.../&gt;</font>
<br> Create a form radio-box. The <b>name</b> and <b>value</b> parameters are
evaluated and emitted. A <b>checked</b> and <b>default</b> flags affect
whether this box is checked. The box is checked based on the following
values, in decreasing order of priority: tag value,
value in submitted request dictionary, tag default.
We search this list for the first non-None value. </li> <p>
<li><font face=courier>&lt;<b>checkbox</b>
name=<i>exprstring</i>&nbsp;value=<i>exprstring</i>&nbsp;[checked]&nbsp;[default]&nbsp;.../&gt;</font>
<br> Create a form check-box. Parameters are the same as for <b>radio</b>
fields, explained above. </li> <p>
<li><font face=courier>&lt;<b>select</b>
name=<i>exprstring</i>&nbsp;[selected=<i>exprstring</i>]&nbsp;[default=<i>exprstring</i>]&nbsp;[data=<i>expr</i>]&nbsp;...&gt;...&lt;/<b>select</b>&gt;</font>
<br> Create a form select block. The <b>name</b> parameter is
evaluated and emitted. The optional <b>data</b> should be an iterable of
(description, value) pairs.
</li><p>
<li><font face=courier>&lt;<b>option</b>
[text=<i>exprstring</i>]&nbsp;[value=<i>exprstring</i>]&nbsp;[selected]&nbsp;[default]&nbsp;.../&gt;</font>
<br> <font face=courier>&lt;<b>option</b>
[value=<i>exprstring</i>]&nbsp;[selected]&nbsp;[default]&nbsp;...&gt;text&lt;/<b>option</b>&gt;</font>
<br> Create a form selection option. This tag must be nested within a
<b>select</b> tag. The <b>text</b> optional parameter is evaluated and
emitted in the body of the tag. It can also be provided in the body of the
tag, as you might be used to seeing in HTML.
</li> <p>
<li><font face=courier>&lt;<b>radiolist</b>
name=<i>exprstring</i>&nbsp;data=<i>expr</i>&nbsp;[checked=<i>exprstring</i>]&nbsp;[default=<i>exprstring</i>]&nbsp;...&gt;...&lt;/<b>select</b>&gt;</font>
<br> Create multiple radio buttons from <b>data</b>, which should be an iterable of
(description, value) pairs.
</li><p>
<li><font face=courier>&lt;<b>checkboxlist</b>
name=<i>exprstring</i>&nbsp;data=<i>expr</i>&nbsp;[checked=<i>exprstring</i>]&nbsp;[default=<i>exprstring</i>]&nbsp;...&gt;...&lt;/<b>select</b>&gt;</font>
<br> Create multiple checkboxes from <b>data</b>, which should be an iterable of
(description, value) pairs.
</li><p>
</ul> <p>
Here is an example of all of these tags in use:
<table border=1 align=center>
<tr><td align=left bgcolor="#cccccc">
  <font face="arial, helvetica" size="-1"><b>examples/formtag.spy</b></font>
</td></tr><tr><td>
  <font face=courier>
    <pre style='font-family: courier,monospace; font-size: small'><font color="#000000"><b><font color="#229922">&lt;spy:parent title=&quot;Form tag example&quot; /&gt;</font>

<font color="#229922">&lt;f:form&gt;</font>

&lt;h2&gt;Primitive controls&lt;/h2&gt;

&lt;div class=&quot;simpleform&quot;&gt;
  <font color="#229922">&lt;f:text name=&quot;mytext&quot; label=&quot;Text&quot; default=&quot;some text&quot; size=10 maxlength=30 /&gt;</font>

  <font color="#229922">&lt;f:password name=&quot;mypass&quot; label=&quot;Password&quot; default=&quot;secret&quot; /&gt;</font>

  <font color="#229922">&lt;f:textarea name=&quot;mytextarea&quot; label=&quot;Textarea&quot; default=&quot;rimon&quot; rows=2 cols=50&gt;</font><font color="#229922">&lt;/f:textarea&gt;</font>

  &lt;label for=&quot;mycheck&quot;&gt;Checkbox&lt;/label&gt;<font color="#229922">&lt;f:checkbox name=mycheck value=check1 /&gt;</font>

  &lt;label for=&quot;myradio1&quot;&gt;Radio option 1&lt;/label&gt;<font color="#229922">&lt;f:radio name=myradio value=option1 /&gt;</font>
  &lt;label for=&quot;myradio2&quot;&gt;Radio option 2&lt;/label&gt;<font color="#229922">&lt;f:radio name=myradio value=option2 /&gt;</font>
&lt;/div&gt;

&lt;div style=&quot;clear: both&quot;&gt;
  &lt;h2 style=&quot;padding-top: 1em;&quot;&gt;Compound controls&lt;/h2&gt;
  <font color="#ff7448">[[-- a simple data source for the compound controls -- in practice