Mercurial > piecrust2

comparison docs/api/01_plugins.md @ 503:61d53d2163d6

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