Mercurial > piecrust2

comparison docs/api/02_components/02_sources.md @ 526:9b8b47fb1068

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
bug: Forgot to add a new file like a big n00b.
author Ludovic Chabant <ludovic@chabant.com>
date Tue, 28 Jul 2015 21:36:59 -0700
parents 20fcadaaf871
children
comparison
equal deleted inserted replaced
525:4a26f3dfb92b 526:9b8b47fb1068
1 --- 1 ---
2 title: Page Sources 2 title: Page Sources
3 --- 3 ---
4 4
5 `TODO` 5 A page source is a component that retrieves pages from _somewhere_, and gives
6 them to the rest of the application for processing. A typical blog would have 2
7 sources: one for the blog posts, and one for the other pages (like the main
8 page, an "_about_" page, some archives, etc.).
6 9
10 To provide new page sources, you need to override the `getSources` method of
11 your plugin, and return source _types_ (not instances!).
12
13
14 ```python
15 class MyPlugin(PieCrustPlugin):
16 name = 'myplugin'
17
18 def getSources(self):
19 return [
20 MyCustomSource]
21 ```
22
23
24 ## Basic Implementation
25
26 To implement a page source, you need to inherit from the `PageSource` class:
27
28 ```python
29 from piecrust.sources.base import PageSource
30
31 class MyCustomSource(PageSource):
32 def __init__(self, app, name, config):
33 super(MyCustomSource, self).__init__(app, name, config)
34 # Other stuff...
35
36 ```
37
38 There are 3 methods you need to override for a basic, functioning page source.
39
40 * `buildPageFactories(self)`: you should be returning a list of `PageFactory`
41 objects here -- one for each page inside the given source. Your source
42 instance has access to its configuration settings from the website's
43 `config.yml`, and to the current `PieCrust` application, among other things.
44 A `PageFactory` object describes how a page should be created. It has a
45 `ref_path` (_i.e._ a source-specific path which, for a simple source, could
46 just be the relative path of the page file inside the source's directory), and
47 some `metadata`. See "_Source Metadata_" later on this page.
48
49 * `resolveRef(self, ref_path)`: you should return a tuple that describes the
50 page found at `ref_path`. The tuple contains the full path of the page file,
51 and the _source metadata_ for it.
52
53 * `findPageFactory(self, metadata, mode)`: this is mostly useful when running
54 PieCrust as a dynamic CMS (which incidentally is also the case when previewing
55 with `chef serve`). Based on the _route metadata_ provided, the source is
56 expected to do its best to find a matching page, and return a `PageFactory`
57 for it.
58
59 The `mode` can either be `MODE_PARSING` or `MODE_CREATING`. The first mode
60 expects you to return a `PageFactory` for an existing page. That's the mode
61 that will always be given while running `chef serve`. The second mode expects
62 you to return a factory for a _non-existing_ page. That's the mode that will
63 be given when running `chef prepare`, _i.e._ when the application wants to
64 create a new page for a source, and needs to know exactly what file to create.
65
66
67 ## Source Metadata
68
69
70
71 ## Mixins
72
73