Mercurial > piecrust2

annotate docs/api/01_plugins.md @ 982:492b66482f12

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