Paj's Home: Web Applications: Pipp: Documentation

Unfinished Content This page needs some work; contributions are welcome!

Introduction

A Pipp site starts as source code, which is a directory of .pip files and supporting files, such as images. Running Pipp builds the source into static HTML for deployment to a web server. The web server does not need to have Pipp installed. For convenience during development, Pipp also has a built-in web server that performs on-demand building.

.pip files are very similar to HTML files, but have extra tags that are processed by Pipp. The build process involves applying an XSLT stylesheet to each .pip file. The stylesheet is tailored to each individual website, and based on a standard template included with Pipp. Pipp provides a number of XSLT extension functions to be called from the template; these assist with common web development tasks. Pipp also provides the framework for calling the XSLT transforms as needed.

Manual Installation

Note: If you're using Windows, it is easier to use the Pipp Windows Installer. Manual installation is required on other platforms, and if you want to use the development version, or modify the Pipp source code.

The following dependencies are required:

Python
4Suite
Python Imaging Library
Pygments
wxPython (only needed for the Windows tool tray app)

Installation procedure:

Download Pipp Source Code
Extract the archive into a suitable directory
Add the directory to your path

To check this worked, at a command prompt or shell window, type "pipp.py -?". This should produce a help screen describing the command line options.

To launch example site...

Go into the directory and type "pipp.py -s ."
Browse to http://127.0.0.1:8080/

Development Version

You can get a checkout of the latest development version from the Subversion repository at Google Code:

svn checkout http://pipp.googlecode.com/svn/trunk/ pipp

Be aware that this may not be as stable as the release version.

Directory Layout

The directory for a Pipp site always has the following:

index.pip - the front page
pipp.xsl - the stylesheet used to transform .pip files to .html files
pipp.xml - this is generated by Pipp and contains information on all the pages in the site
out - a directory created by Pipp, that contains the generated web site

Within .pip files, relative and absolute paths can be used. Absolute paths start from the project root directory; it is not possible to reference files outside this. This is deliberate, to encourage self-contained source code. If necessary, you can use symbolic links to work around this restriction.

.pip Files

A simple .pip file looks like:

<pipp>
    <title>My Page</title>
    <style>blue-white</style>
    ...
    <body>
        This is my content
        ...
    </body>
</pipp>

TBD: explain exports and body

Inside the body, the following tags will be processed by Pipp, in addition to any specific rules the site stylesheet: TBD - explain these (link to XSLT API?)

pipp-child @src
pipp-file @src
pipp-child-file @src @title
pipp-code @src
pipp-map-view @src
pipp-img @src ...
pipp-thumb @src @width/@height ...

It was decided to avoid requiring XML namespaces in .pip files. This avoids including a namespace definition in every .pip file.

Exported Variables

A page can export any variables it likes. If "link" is not explicitly exported, Pipp automatically exports the absolute path to the output HTML file. In general, all pages will export "title".

Site Stylesheet

Two things: Your page template Any rewrites you want, e.g. graphical h1 Don't start from scratch - use either minimal_pipp.xsl or copy a more detailed example.

pipp.xml Format

<page src="/mypage.pip">
    <exports>
        <myvariable>my value</myvariable>
        ...
    </exports>
    <depends>
        <depend>/pipp.xsl</depend>
        ...
    </depends>
    <edepends>
        <depend>/index.pip:title</depend>
        ...
    </edepends>
    <children>
        <page>
        ...
        <.page>
        ...
    </children>
</page>

Command Line

Usage: pipp.py [options] project_root

Options:
  -h, --help            show this help message and exit
  -s, --serve           Start a web server that publishes the project; this is
                        useful for development
  -p PORT, --port=PORT  Specify port for the web server (default 8080)
  -l LISTEN, --listen=LISTEN
                        Specify the listening address for the web server
                        (default 127.0.0.1)
  -f, --full            Initiate a full rebuild of the project
  -v, --verbose         Produce more verbose output

Tooltray App

XSLT API

pipp:child(file_name): Include the file in the website; it will appear in the site hierarchy as a child of the current file. The file must be valid XML as it will be parsed as a .pip file.
pipp:child-file(file_name, title): Copy the file from in-root to out-root. This is similar to pipp:file, however the file will be included in the site hierarchy as a child of the current file. This is the usual way to include download packages in the website.
pipp:code(file_name, code, lexer, docss): Include a syntax-highlighted source code file in the HTML output. The highlighting is done by Pygments. You can specify either the name of a file to use, or a string. The "lexer" parameter specifies the pygments lexer to use; this must be specified for inline blocks. For files, if not specified, it is determined automatically using the file extension. If "docss" is set to "1", a CSS file with the pygments default colours is automatically generated. If you do not specify docss, you need to include your own CSS rules.
pipp:export(name, value): Add a variable to the current file's export table. Other files will be able to access this variable using pipp:import, pipp:import-join or pipp:map-view. Multiple variables with the same name are permitted but not recommended. It is very common to export the file's title, so site maps and navigation bars can be created.
pipp:export-depend(path, name): Marks the current file as dependent on a variable exported from another file. This needs to be called appropriately in XSLT templates used by map-view, for dependencies to work correctly. It doesn't need to be called from the main stylesheet; pipp:import and pipp:import-join mark the dependency automatically.
pipp:file(file_name): Copy the file from in-root to out-root. The file will not appear in the site hierarchy. This is the usual way to include images or other binary files in the website. file_name can be a directory, which is copied in full, including all files and subdirectories.
pipp:file-name(): Return the absolute path to the current output file.
pipp:file-time(time_format): Return the modification date and time of the current input file. The time_format parameter must be a format string suitible for passing to the Python time.strftime function.
pipp:gtitle(font, height, texture, bgcolor, text): Generate an image containing styled text. The font is a path to a .ttf file, the height is is pixels and the texture is a path to a image file. The bgcolor should be set to roughly the colour of the background the image will appear on; this is necessary to make anti-aliasing work correctly.
pipp:image-width(file_name): Return the width of the image, in pixels. The formats supported are those supported for reading by the Python Imaging Library.
pipp:image-height(file_name): Return the height of the image, in pixels. The formats supported are those supported for reading by the Python Imaging Library.
pipp:import(name): Retrieve a variable from the current file's export table. If it is not defined in the current file, search up the site hierachy. If none of the ancestors define the variable then raise an error. This is useful for controling properties that are usually passed from parent to child, such as CSS stylesheet names.
pipp:import-join(name, separator): Retrieve a variable from the current file and its ancestors' export table. All the variable values are joined into a single string using the separator, with the value from the root file appearing first. This is useful for constructing a long title string, which informs the used of their position in the hierarchy.
pipp:map-view(xslt_file): Generate a customised view of the page hierarchy. This is useful for automatically generating navigation bars, site maps, contents pages and more. The specified stylesheet is applied to pipp.xml and the output is included in the current document. For partial builds to work correctly, the stylesheet must explictly register dependencies, by calling pipp:export-depend.
pipp:relative-path(file_name): Return a relative path to the file. This is usually only useful with absolute file names as relative file name are return unchanged. Using relative paths makes reorganising the website much easier compared to absolute paths.
pipp:thumbnail(file_name, width, height): Generate a thumbnail of the image with the specified size. The function returns the file name of the generate image. If the original image is called xxx.yyy the thumbnail will be called xxx_thumb.yyy. The formats supported are those supported for writing by the Python Imaging Library. You may specify width or height explicitly, or pass one value as zero. If you only specify one dimension, the other will be calculated to preserve the aspect ratio of the original image.

Paul Johnston, distributed under the BSD License Updated:10 Jun 2009