Page Sources

A page source is a component that retrieves pages from somewhere, and gives them to the rest of the application for processing. A typical blog would have 2 sources: one for the blog posts, and one for the other pages (like the main page, an “about” page, some archives, etc.).

To provide new page sources, you need to override the getSources method of your plugin, and return source types (not instances!).

class MyPlugin(PieCrustPlugin):
    name = 'myplugin'

    def getSources(self):
        return [
                MyCustomSource]

Basic Implementation

To implement a page source, you need to inherit from the PageSource class:

from piecrust.sources.base import PageSource

class MyCustomSource(PageSource):
    def __init__(self, app, name, config):
        super(MyCustomSource, self).__init__(app, name, config)
        # Other stuff...

There are 3 methods you need to override for a basic, functioning page source.

• buildPageFactories(self): you should be returning a list of PageFactory objects here – one for each page inside the given source. Your source instance has access to its configuration settings from the website’s config.yml, and to the current PieCrust application, among other things. A PageFactory object describes how a page should be created. It has a ref_path (i.e. a source-specific path which, for a simple source, could just be the relative path of the page file inside the source’s directory), and some metadata. See “Source Metadata” later on this page.

• resolveRef(self, ref_path): you should return a tuple that describes the page found at ref_path. The tuple contains the full path of the page file, and the source metadata for it.

• findPageFactory(self, metadata, mode): this is mostly useful when running PieCrust as a dynamic CMS (which incidentally is also the case when previewing with chef serve). Based on the route metadata provided, the source is expected to do its best to find a matching page, and return a PageFactory for it.

The mode can either be MODE_PARSING or MODE_CREATING. The first mode expects you to return a PageFactory for an existing page. That’s the mode that will always be given while running chef serve. The second mode expects you to return a factory for a non-existing page. That’s the mode that will be given when running chef prepare, i.e. when the application wants to create a new page for a source, and needs to know exactly what file to create.

Source Metadata

Mixins