Documentation - Language
2.3. Spyce Directives
Syntax: [[. directive ]]
Spyce directives directly affect the operation of the Spyce compiler. There
is a limited set of directives, listed and explained below:
[[.compact mode=mode]] :
Spyce can output the static HTML strings in various modes of compaction,
which can both save bandwidth and improve download times without visibly
affecting the output. Compaction of static HTML strings is performed once
when the input Spyce file is compiled, and there is no additional run-time
overhead beyond that. Dynamically generated content from Python code tags
and expressions is not compacted nor altered in any way. Spyce can operate
in one of the compaction modes listed below. One can use the compact
tag to change the compaction mode from that point in the file forwards.
- off: No compaction is performed. Every space and newline in the
static HTML strings is preserved.
- space: Space compaction involves reducing any consecutive runs
of spaces or tabs down to a single space. Any spaces or tabs at the
beginning of a line are eliminated. These transformations will not affect
HTML output, barring the <pre> tag, but can considerably reduce the
size of the emitted text.
- line: Line compaction eliminates any (invisible) trailing
whitespace at the end of lines. More significantly it improves the indented
presentation of HTML, by ignoring any lines that do not contain any static
text or expression tags. Namely, it removes all the whitespace, including
the line break, surrounding the code or directives on that line. This
compaction method usually "does the right thing", and produces nice HTML
without requiring tricky indentation tricks by the developer. It is,
therefore, the initial compaction mode.
- full: Full compaction applies both space and line compaction. If
the optional mode attribute is omitted, full compaction mode is the
default value assumed.
[[.import name=name from=file as=name args=arguments]] :
The import directive loads and defines a Spyce module into the global
context. (The [[.module ... ]]directive
is synonymous.) A Spyce module is a
Python file, written specifically to interact with Spyce. The name
parameter is required, specifying the name of the Python class to load. The
file parameter is optional, specifying the file where the named class
is to be found. If omitted, file will equal name.py. The file path can be absolute or
relative. Relative paths are scanned in the Spyce home, user-configurable server path directories and current
script directory, in that order. Users are encouraged to name or prefix their
modules uniquely so as not to be masked by system modules or tag libraries.
The as parameter is optional, and specifies the name under which the
module will be installed in the global context. If omitted, this parameter
defaults to the name parameter. Lastly, the optional args parameter
provides arguments to be passed to the module initialization function. All
Spyce modules are start()ed before Spyce processing begins,
init()ed at the point where the directive is placed in the code, and
finish()ed after Spyce processing terminates. It is convention to
place modules at, or near, the very top of the file unless the location of
initialization is relevant for the functioning of the specific module.
[[.import names="name1,name2,..."]] :
An alternative syntax allows convenient loading of multiple Spyce modules.
One can not specify non-standard module file locations, nor rename the
modules using this syntax.
[[.taglib name=name from=file as=name]] :
The taglib directive loads a Spyce tag library. A Spyce tag library is a Python file, written
specifically to interact with Spyce. The name parameter specifies
the name of the Python class to load if using a 1.x-style taglib;
otherwise it is ignored. The file parameter is
optional, specifying the file where the named class is to be found. If
omitted, file will equal name.py. The file
path can be absolute or relative. Relative paths are scanned in the Spyce
home, user-configurable server
path directories and current script directory, in that order. Users are
encouraged to name or prefix their tag libraries uniquely so as not to be
masked by system tag libraries and modules. The as parameter is
optional, and specifies the unique tag prefix that will be used to identify
the tags from this library. If omitted, this parameter defaults to the name
parameter. It is convention to place tag library directives at, or near, the
very top of the file. The tags only become active after the point of the tag
Also note that the configuration parameter globaltags allows you
to set up tag libraries globally, freeing you from having to specify the
taglib directive on each page that uses a tag. By default, globaltags
installs core under the spy: prefix, and form under the f: prefix.
(Tag libraries specified in globaltags are only loaded if the Spyce compiler
determines they are actually used on the page, so there is no performance
difference between globaltags and manually setting up taglib for each page.)
There are some additional directives that are only legal when
defining an active tag library.
It is important to note that Spyce directives are processed at compile
time, not during the execution of the script, much like directives in C, and
other languages. In other words, they are processed as the Python code for the
Spyce script is being produced, not as it is being executed. Consequently, it
is not possible to include runtime values as parameters to the various