Python Website Pyramid Users Guide

Legacy Wiki Page

This page was migrated from the old MoinMoin-based wiki. Information may be outdated or no longer applicable. For current documentation, see python.org.

This page is now largely irrelevant – the website no longer uses Pyramid to build.

Pyramid User’s Guide

Overview

Pyramid deals with fragments (of html) that can contain any number of slots, each identified by a name. Data are mapped into each slot in the fragment through a dictionary-like interface. A fragment is created by combining an html template and a data mapping. Created fragments may also have slots in them, allowing for further substitutions, and so on.

Fragments can map more complex structures than simple names. A slot can be filled by a list (using parameterised template html for each item in the list), for example. Even more flexibly, specific html tags can cause custom renderers (that can transform the html) to be invoked. Typical uses of of pyramid only use simple lists and mappings, but more is there when you need it.

The system’s power comes from applying the same technique at multiple levels, allowing templating tasks of arbitrary complexity to be implemented without imposing arbitrary restrictions on html structure.

The final aspect of the system, that allows sites to be built around a common templated structure, is the ability for data items and templates to be inherited from parent directories. A single html ‘skin’ can be defined at the root of a directory structure. Each child fragment will, if unable to find the specified template in its own directory, search back towards the root directory looking for the required template.

Table of Contents

• Pyramid User’s Guide

  • Overview

  • Introduction

  • The Templating System

    • Slots

    • Data Items

    • Patterns

    • Renderers

  • Data Structure

    • fragment

    • rest & restfile

    • url

  • Using Pyramid

  • Viewing the Generated Pages

  • Adding Pages to the Python Site - Full Description

    • Adding initial files

      • index.yml

      • content.yml

      • content.html

    • Creating the Restructured Text Content

  • Alternative Ways to Add Pages

    • Using htfiles within pyramid

      • index.yml

      • content.yml

    • Using htfiles sourced directly from the pydotorg tree

      • index.yml

      • content.yml

    • Creating htfile pages from the command line

    • Getting content out of wiki pages

  • How the navigation works

    • index.yml

    • one/index.yml

  • Adding Special Features

    • Sidebars

      • construction of typical content page

      • Adding a sidebar to the content.html

    • More complicated structures

    • Continuing navigation as a sidebar

  • Pyramid and the Python Site

    • Don’t be scared by the homepage setup!!

    • FAQ’s

      • How do I include Images and other static assets?

      • A lot of links seem to be wrong?

    • Can you tell me about the Homepage now?

      • index.yml

      • homepage.yml

      • sidebar.yml

      • success.yml

      • quote.yml

      • using-python-for.yml

    • written-in-python.yml

Introduction

A simple example template, which perhaps would be used on the news page of a site for a list of news items, should demonstrate the basic concepts. Here is the data structure

# file = news.yml
--- !fragment
template: news.html
local:
  heading: The News
  welcome-message: Welcome to the news
  news: here is the news

and here is the html template:

# file = news.html
<h2><n:slot name="heading" /></h2>
<n:slot name="welcome-message" />
<div class="news">
  <n:slot name="news" />
</div>

The !fragment in the data structure is a type identifier that tells the yaml parser that a data structure is expected. In this case the fragment data structure should have template, local and global keys.

The template key points to a filename for the html template to be used. The local and global keys point to the two data structures to be used.

To work out the data structure to be used to the website, the local data and global data are merged, with local data taking priority. (note for later: if the item is in a sub-directory of a site, the parents global data is also merged, this will be covered in a subsequent section).

The template will look for each fragments slot name in the keys of the merged data item. The heading, welcome message and news will be taken and inserted into the appropriate slots.

The result will be the following html:

<h2>The News</h2>
Welcome to the news
<div class="news">
  here is the news
</div>

If we wished to use a standalone template for the news item we would repeat the initial html template but change the ‘news’ key from a string to a !fragment type:

# file = news.yml
--- !fragment
template: news.html
local:
  heading: The News
  welcome-message: Welcome to the news
  news: !fragment newsitem.yml

# file = news.html
<h2><n:slot name="heading" /></h2>