Paj's Home: Web Apps: Pipp: Documentation

Documentation

(Under construction)

Introduction

A pipp website starts as source code, which is a set 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 builds on demand.

.pip files are essentially HTML files with 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 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/

Concepts

in_root, out_root state exports, dependencies and children

Files in project

    index is always index.pip
    xsl is always pipp.xsl
    out_root is always "out", just inside in_root
    state is always pipp.xml (doesn't need to be present)

Paths are relative to the current file. Absolute paths are relative to the in-root

Dependencies: globs and gtitle font/pattern are not tracked. everything else should be.

Pipp Files

pipp exports body 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 ... Note: XML namespaces were avoided, so you don't need to include namespace definitions in all .pip files.

Stylesheet

process /pipp/body do whatever rewrites you want - graphical h1's, save typing, html workarounds

State XML

<page src="...">
  <exports>
    ...
  </exports>
  <depends>
    ...
  </depends>
  <children>
    ...
  </children>
</page>

The state XML enables pages to share state. The site has a hierarcial structure. A page can export values, and import. Imports search up the parent nodes. This lets you define generic stuff, at the top, and override as needed. The state is generated during a full run, as all parents of a page are build before the page, searching up always works.

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

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 view of the site map. The specified stylesheet is applied to the sitemap XML and the output is included in the current document.
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.