Mercurial > piecrust2

annotate docs/api/02_components/02_sources.md @ 1051:971b4d67e82a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
serve: Fix problems with assets disappearing between servings. When an asset file changes, its source's pipeline is re-run. But that created a bake record that only had that pipeline's output, so the other outputs were incorrectly considered empty and therefore any stray files were removed. Now we copy over bake records for the pipelines we don't run.
author Ludovic Chabant <ludovic@chabant.com>
date Fri, 26 Jan 2018 18:05:02 -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