spyce
         
home     documentation     download     Spyce logo


Documentation - Modules
Prev: 3.8.9 - Compress Up: 3.8 - Modules Next: 3.8.11 - Internal modules
3.8.10. Include

Many websites carry a theme across their various pages, which is often achieved by including a common header or footer. This is best done with a parent template from the spy:parent tag, but you can also do this with the include module for backwards compatibility with Spyce 1.x.

Another option to consider for repeating a common task is a custom active tag.

The include module can also pretty print Spyce code or include the contents of anything in your filesystem.

  • spyce( file, [context] ):
    Dynamically includes the specified file (corresponding to the Spyce document root, not filesystem), 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'].

    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 (from the filesystem -- use spyceUtil.url2file(url, request.filename) if you need to turn a url into a filesystem path) are returned. If the binary parameter is true, the file is opened in binary mode. By default, text mode is used.

    Be careful not to blindly trust the user to specify which file to dump, since anything your Spyce process has access to in the filesystem is fair game.

  • spycecode( file ):
    Contents of the file (relative to the Spyce document root) 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

examples/include.spi 
begin include<br>
context: [[=include.context ]]<br>
from: [[=request.stack()[-2] ]]<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

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

Prev: 3.8.9 - Compress Up: 3.8 - Modules Next: 3.8.11 - Internal modules

Spyce logo
Python Server Pages
version 2.1.3 		Spyce Powered SourceForge Logo