spyce
home
license
community
download
examples
resources
wishlist
contrib (@sf)
documentation
intro
lang
runtime
modules
tags
install
exits
sourceforge
statistics
freshmeat

Documentation - Modules
[[ Spyce ]]
Python Server Pages
by Rimon Barr

Prev: 4.6 - Taglib Up: 4 - Modules Next: 4.8 - Transform

4.7. Include

Many websites carry a theme across their various pages, which is often achieved by including a common header or footer. The include module provides exactly this functionality, and more. For example, it can also be used to define dynamic site-wide constants, and other similar globals that can not otherwise be initialized with static include directives (due to their dynamic nature). For example, language specific constants may be selected dynamically from the required language include file, based on a GET or POST language parameter or, better yet, from the Accept-Language request header. This module also provides other functions that are similar in nature. For example, it can currently pretty print Spyce code. In the future, it will be able to generate the Spyce and Spyce Powered logo, and possibly other similar trinkets.

  • spyce( file, [context] ):
    Dynamically includes the specified file, and processes it as Spyce code. The return value is that of the included Spyce file. One can optionally provide a context value to the included file. If omitted, the value defaults to None. All currently imported modules are passed along into the included file without re-initialization. However, for each explicit [[.import ]] tag in the included file, a new module is initialized and also finalized up at the end of processing. The include module provides three fields for use inside included files:

    • include.context: This field stores the value passed in at the point of inclusion. Note that if the value is one that is passed by reference (as is the case with object, list, and dictionary types), then the context may be used to pass information back to the including file, in addition to the return value.
    • include.vars: If the include context is of type dictionary, then the vars field is initialized, otherwise it is None. The vars field provides attribute-based access to the context dictionary, merely for convenience. In other words, include.vars.x is equivalent to include.context['x'].
    • include.fromFile: stores the name of the file name from which this file was included.
    Note that either the locals() or globals() dictionaries may be passed in as include contexts. However, be advised that due to Python optimizations of local variable access, any updates to the locals() dictionary may not be reflected in the local namespace under all circumstances and all versions of Python. In fact, this is the reason why the context has been made explicit, and does not simply grab the locals() dictionary. It may, however, safely be used for read access. With respect to the globals() dictionary, it is not advised to pollute this namespace.
  • spyceStr( file, [context] ):
    Same as spyce(), but performs no output and instead returns the processed included Spyce file as a string.
  • dump( file, [binary] ):
    Contents of the file are returned. If the binary parameter is true, the file is opened in binary mode. By default, text mode is used.
  • spycecode( file ):
    Contents of the file are returned as HTML formatted Spyce code.
The example below (taken from this documentation file), uses a common header template only requiring two context variables to change the title and the highlighted link:
  [[.import name=include]]
  [[include.spyce('inc/head.spi', 
      {'pagename': 'Documentation', 
       'page': 'manual.html'}) ]]

In head.spi, we use this information to set the title:

  [[.import name=include]]
  <title>[[=include.context['pagename'] ]]</title>

By convention, included files are given the extension .spi.

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.

examples/include.spy
[[.import name=include]]
<html><body>
  main file<br>
  <hr>
  [[
    context = {'foo': 'old value'}
    result=include.spyce('include.spi', context)
  ]]
  <hr>
  main file again<br>
  context: [[=context]]<br>
  return value: [[=result]]<br>
</body></html>
Run this code.
(requires Spyce-enabled web server)

examples/include.spi
begin include<br>
context: [[=include.context ]]<br>
from: [[=include.fromFile ]]<br>
foo was [[=include.vars.foo]]<br>
setting foo to 'new value' [[include.vars.foo = 'new value']]<br>
returing 'retval'<br>
end include<br>
[[ return 'retval' ]]

examples/includestatic.spy
<html><body>
  [[x=1]]
  main file<br>
  x=[[=x]]<br>
  <hr>
  [[.include file="includestatic.spi"]]
  <hr>
  main file again<br>
  x=[[=x]]
</body></html>
Run this code.
(requires Spyce-enabled web server)

examples/includestatic.spi
begin included file<br>
changing value of x<br>
[[x=2]]
end included file<br>


Prev: 4.6 - Taglib Up: 4 - Modules Next: 4.8 - Transform


© 2002-05 Rimon Barr
email: rimon@acm.org
Spyce Powered SourceForge Logo [[ Spyce ]]
Python Server Pages
version 1.3.13