Mercurial > piecrust2

annotate docs/pages/code.md @ 380:f33712c4cfab

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
routing: Fix bugs with matching URLs with correct route but missing metadata. When matching a route like `/foo/%slug%` against an URL like `/foo`, the route will (correctly) return a match, but it will be completely missing the `slug` metadata, resulting in problems elsewhere. This change makes it so that any missing route metadata will be filled in with an empty string. And because this means generated URLs may differ from the incoming URL when using trailing slashes (`/foo/` _vs._ `/foo`), we make the assert in the chef server handle those discrepancies.
author Ludovic Chabant <ludovic@chabant.com>
date Sun, 10 May 2015 00:34:21 -0700
parents 9188b362069e
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
243
26e59f837558 docs: Add embryo of a documentation website.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
1 ---
26e59f837558 docs: Add embryo of a documentation website.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
2 title: Code
26e59f837558 docs: Add embryo of a documentation website.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
3 header_class: code
26e59f837558 docs: Add embryo of a documentation website.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
4 ---
26e59f837558 docs: Add embryo of a documentation website.
Ludovic Chabant <ludovic@chabant.com>
parents:
diff changeset
5
313
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
6 ## PieCrust plugins
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
7
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
8 To create a PieCrust plugin, you need to do a few things:
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
9
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
10 * Create a correct `setuptools` package.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
11 * Implement a sub-class of `PieCrustPlugin`.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
12 * Write a couple lines of boilerplate code.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
13
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
14
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
15 ### Packaging plugins
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
16
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
17 PieCrust plugins are expected to be available on [Pypi][] for better integration
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
18 with `chef` commands. For instance, the `chef plugins list -a` will list all
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
19 PieCrust plugins from Pypi.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
20
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
21 A PieCrust plugin package must:
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
22
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
23 * Be named `PieCrust-FooBar`, where `FooBar` is the name of the plugin.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
24 * Have a module named `piecrust_foobar`, which is basically the lower-case
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
25 version of the package name, with an underscore instead of a dash.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
26
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
27 You can refer to the [`setuptools` documentation][st] for more information.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
28
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
29
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
30 ### The plugin class
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
31
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
32 A PieCrust plugin is an instance of a class that derives from `PieCrustPlugin`.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
33 The only required thing you need to override is the name of the plugin:
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
34
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
35 from piecrust.plugins.base import PieCrustPlugin
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
36
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
37 class FooBarPlugin(PieCrustPlugin):
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
38 name = 'FooBar'
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
39
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
40 The plugin class has a whole bunch of functions returning whatever your plugin
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
41 may want to extend: formatters, template engines, `chef` commands, sources, etc.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
42 Each one of those returns an array of instances or classes, depending on the
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
43 situation.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
44
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
45 Check the `piecrust.plugins.builtin.BuiltInPlugin` to see how all PieCrust
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
46 functionality is implemented.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
47
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
48
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
49 ### Boilerplate code
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
50
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
51 Now we have a plugin class, and a Pypi package that PieCrust can find if needed.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
52 All we need is a way to tell PieCrust how to find your plugin class in that
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
53 package.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
54
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
55 In the required `piecrust_foobar` module, you need to define a
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
56 `__piecrust_plugin__` global variable that points to your plugin class:
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
57
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
58 __piecrust_plugin__ = FooBarPlugin
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
59
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
60 That's what PieCrust will use to instantiate your plugin.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
61
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
62
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
63 ### Loading the plugin
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
64
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
65 Now you can add your plugin to a PieCrust website by adding this to the website
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
66 configuration:
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
67
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
68 site:
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
69 plugins: foobar
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
70
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
71 PieCrust will prepend `piecrust_` to each specified plugin name and attempt to
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
72 load that as a module (`import piecrust_foobar`). If this succeeds, it will look
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
73 for a `__piecrust_plugin__` in that module, and expect its value to be a class
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
74 that inherits from `PieCrustPlugin`. If everything's OK, it will instantiate
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
75 that class and query it for various services and components when necessary.
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
76
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
77
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
78 [pypi]: https://pypi.python.org/pypi
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
79 [st]: http://pythonhosted.org/setuptools/
9188b362069e docs: Add documentation on making a plugin.
Ludovic Chabant <ludovic@chabant.com>
parents: 243
diff changeset
80