Commit | Line | Data |
---|---|---|
29b6f917 WKG |
1 | ========= |
2 | Plugins | |
3 | ========= | |
4 | ||
355fd677 WKG |
5 | GNU MediaGoblin supports plugins that allow you to augment MediaGoblin's |
6 | behavior. | |
29b6f917 WKG |
7 | |
8 | This chapter covers discovering, installing, configuring and removing | |
9 | plugins. | |
10 | ||
11 | ||
12 | Discovering plugins | |
13 | =================== | |
14 | ||
15 | MediaGoblin comes with core plugins. Core plugins are located in the | |
16 | ``mediagoblin.plugins`` module of the MediaGoblin code. Because they | |
17 | come with MediaGoblin, you don't have to install them, but you do have | |
18 | to add them to your config file if you're interested in using them. | |
19 | ||
20 | You can also write your own plugins and additionally find plugins | |
355fd677 WKG |
21 | elsewhere on the Internet. Once you find a plugin you like, you need |
22 | to first install it, then add it to your configuration. | |
23 | ||
2530ef7a | 24 | .. todo: how do you find plugins on the internet? |
29b6f917 WKG |
25 | |
26 | ||
27 | Installing plugins | |
28 | ================== | |
29 | ||
355fd677 WKG |
30 | Core plugins |
31 | ------------ | |
32 | ||
33 | MediaGoblin core plugins don't need to be installed because they come | |
34 | with MediaGoblin. Further, when you upgrade MediaGoblin, you will also | |
35 | get updates to the core plugins. | |
36 | ||
37 | ||
38 | Other plugins | |
39 | ------------- | |
29b6f917 | 40 | |
355fd677 WKG |
41 | If the plugin is available on the `Python Package Index |
42 | <http://pypi.python.org/pypi>`_, then you can install the plugin with pip:: | |
29b6f917 WKG |
43 | |
44 | pip install <plugin-name> | |
45 | ||
46 | For example, if we wanted to install the plugin named | |
7989cd6e SS |
47 | "mediagoblin-licenses" (which allows you to customize the licenses you |
48 | offer for your media), we would do:: | |
29b6f917 | 49 | |
7989cd6e | 50 | pip install mediagoblin-licenses |
29b6f917 WKG |
51 | |
52 | .. Note:: | |
53 | ||
54 | If you're using a virtual environment, make sure to activate the | |
7989cd6e SS |
55 | virtual environment before installing with pip. Otherwise the plugin |
56 | may get installed in a different environment than the one MediaGoblin | |
57 | is installed in. Also make sure, you use e.g. pip-2.7 if your default | |
58 | python (and thus pip) is python 3 (e.g. in Ubuntu). | |
29b6f917 WKG |
59 | |
60 | Once you've installed the plugin software, you need to tell | |
61 | MediaGoblin that this is a plugin you want MediaGoblin to use. To do | |
62 | that, you edit the ``mediagoblin.ini`` file and add the plugin as a | |
63 | subsection of the plugin section. | |
64 | ||
7989cd6e SS |
65 | For example, say the "mediagoblin-licenses" plugin has the Python |
66 | package path ``mediagoblin_licenses``, then you would add ``mediagoblin_licenses`` to | |
29b6f917 WKG |
67 | the ``plugins`` section as a subsection:: |
68 | ||
69 | [plugins] | |
70 | ||
7989cd6e SS |
71 | [[mediagoblin_licenses]] |
72 | license_01=abbrev1, name1, http://url1 | |
73 | license_02=abbrev2, name1, http://url2 | |
29b6f917 WKG |
74 | |
75 | ||
76 | Configuring plugins | |
77 | =================== | |
78 | ||
355fd677 WKG |
79 | Configuration for a plugin goes in the subsection for that plugin. Core |
80 | plugins are documented in the administration guide. Other plugins | |
81 | should come with documentation that tells you how to configure them. | |
29b6f917 WKG |
82 | |
83 | Example 1: Core MediaGoblin plugin | |
84 | ||
85 | If you wanted to use the core MediaGoblin flatpages plugin, the module | |
7a690a5a CAW |
86 | for that is ``mediagoblin.plugins.flatpagesfile`` and you would add |
87 | that to your ``.ini`` file like this:: | |
29b6f917 WKG |
88 | |
89 | [plugins] | |
90 | ||
7a690a5a CAW |
91 | [[mediagoblin.plugins.flatpagesfile]] |
92 | # configuration for flatpagesfile plugin here! | |
93 | about-view = '/about', about.html | |
94 | terms-view = '/terms', terms.html | |
95 | ||
96 | (Want to know more about the flatpagesfile plugin? See | |
97 | :ref:`flatpagesfile-chapter`) | |
29b6f917 WKG |
98 | |
99 | Example 2: Plugin that is not a core MediaGoblin plugin | |
100 | ||
101 | If you installed a hypothetical restrictfive plugin which is in the | |
102 | module ``restrictfive``, your ``.ini`` file might look like this (with | |
103 | comments making the bits clearer):: | |
104 | ||
105 | [plugins] | |
106 | ||
107 | [[restrictfive]] | |
108 | # configuration for restrictfive here! | |
109 | ||
110 | Check the plugin's documentation for what configuration options are | |
111 | available. | |
112 | ||
113 | ||
114 | Removing plugins | |
115 | ================ | |
116 | ||
117 | To remove a plugin, use ``pip uninstall``. For example:: | |
118 | ||
7989cd6e | 119 | pip uninstall mediagoblin-licenses |
29b6f917 WKG |
120 | |
121 | .. Note:: | |
122 | ||
123 | If you're using a virtual environment, make sure to activate the | |
124 | virtual environment before uninstalling with pip. Otherwise the | |
125 | plugin may get installed in a different environment. | |
355fd677 WKG |
126 | |
127 | ||
128 | Upgrading plugins | |
129 | ================= | |
130 | ||
131 | Core plugins | |
132 | ------------ | |
133 | ||
134 | Core plugins get upgraded automatically when you upgrade MediaGoblin | |
135 | because they come with MediaGoblin. | |
136 | ||
137 | ||
138 | Other plugins | |
139 | ------------- | |
140 | ||
141 | For plugins that you install with pip, you can upgrade them with pip:: | |
142 | ||
143 | pip install -U <plugin-name> | |
144 | ||
145 | The ``-U`` tells pip to upgrade the package. | |
05d8f314 WKG |
146 | |
147 | ||
148 | Troubleshooting plugins | |
149 | ======================= | |
150 | ||
151 | Sometimes plugins just don't work right. When you're having problems | |
152 | with plugins, think about the following: | |
153 | ||
154 | 1. Check the log files. | |
155 | ||
156 | Some plugins will log errors to the log files and you can use that | |
157 | to diagnose the problem. | |
158 | ||
159 | 2. Try running MediaGoblin without that plugin. | |
160 | ||
161 | It's easy to disable a plugin from MediaGoblin. Add a ``-`` to the | |
162 | name in your config file. | |
163 | ||
164 | For example, change:: | |
165 | ||
3a438f5e | 166 | [[mediagoblin.plugins.flatpagesfile]] |
05d8f314 WKG |
167 | |
168 | to:: | |
169 | ||
3a438f5e | 170 | [[-mediagoblin.plugins.flatpagesfile]] |
05d8f314 | 171 | |
3a438f5e | 172 | That'll prevent the ``mediagoblin.plugins.flatpagesfile`` plugin from |
05d8f314 WKG |
173 | loading. |
174 | ||
175 | 3. If it's a core plugin that comes with MediaGoblin, ask us for help! | |
176 | ||
177 | If it's a plugin you got from somewhere else, ask them for help! |