Mercurial > piecrust2

comparison docs/pages/code.md @ 313:9188b362069e

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