Mercurial > piecrust2

annotate docs/api/02_components/02_sources.md @ 1130:71627dd7d2f1 3.1.1

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