docs/source/siteadmin/plugins.rst

   1 =========
   2  Plugins
   3 =========
   4
   5 GNU MediaGoblin supports plugins that allow you to augment MediaGoblin's
   6 behavior.
   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
  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
  24 .. todo: how do you find plugins on the internet?
  25
  26
  27 Installing plugins
  28 ==================
  29
  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 -------------
  40
  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::
  43
  44     pip install <plugin-name>
  45
  46 For example, if we wanted to install the plugin named
  47 "mediagoblin-restrictfive", we would do::
  48
  49     pip install mediagoblin-restrictfive
  50
  51 .. Note::
  52
  53    If you're using a virtual environment, make sure to activate the
  54    virtual environment before installing with pip. Otherwise the
  55    plugin may get installed in a different environment than the one
  56    MediaGoblin is installed in.
  57
  58 Once you've installed the plugin software, you need to tell
  59 MediaGoblin that this is a plugin you want MediaGoblin to use. To do
  60 that, you edit the ``mediagoblin.ini`` file and add the plugin as a
  61 subsection of the plugin section.
  62
  63 For example, say the "mediagoblin-restrictfive" plugin had the Python
  64 package path ``restrictfive``, then you would add ``restrictfive`` to
  65 the ``plugins`` section as a subsection::
  66
  67     [plugins]
  68
  69     [[restrictfive]]
  70
  71
  72 Configuring plugins
  73 ===================
  74
  75 Configuration for a plugin goes in the subsection for that plugin. Core
  76 plugins are documented in the administration guide. Other plugins
  77 should come with documentation that tells you how to configure them.
  78
  79 Example 1: Core MediaGoblin plugin
  80
  81 If you wanted to use the core MediaGoblin flatpages plugin, the module
  82 for that is ``mediagoblin.plugins.flatpagesfile`` and you would add
  83 that to your ``.ini`` file like this::
  84
  85     [plugins]
  86
  87     [[mediagoblin.plugins.flatpagesfile]]
  88     # configuration for flatpagesfile plugin here!
  89     about-view = '/about', about.html
  90     terms-view = '/terms', terms.html
  91
  92 (Want to know more about the flatpagesfile plugin?  See
  93 :ref:`flatpagesfile-chapter`)
  94
  95 Example 2: Plugin that is not a core MediaGoblin plugin
  96
  97 If you installed a hypothetical restrictfive plugin which is in the
  98 module ``restrictfive``, your ``.ini`` file might look like this (with
  99 comments making the bits clearer)::
 100
 101     [plugins]
 102
 103     [[restrictfive]]
 104     # configuration for restrictfive here!
 105
 106 Check the plugin's documentation for what configuration options are
 107 available.
 108
 109
 110 Removing plugins
 111 ================
 112
 113 To remove a plugin, use ``pip uninstall``. For example::
 114
 115     pip uninstall mediagoblin-restrictfive
 116
 117 .. Note::
 118
 119    If you're using a virtual environment, make sure to activate the
 120    virtual environment before uninstalling with pip. Otherwise the
 121    plugin may get installed in a different environment.
 122
 123
 124 Upgrading plugins
 125 =================
 126
 127 Core plugins
 128 ------------
 129
 130 Core plugins get upgraded automatically when you upgrade MediaGoblin
 131 because they come with MediaGoblin.
 132
 133
 134 Other plugins
 135 -------------
 136
 137 For plugins that you install with pip, you can upgrade them with pip::
 138
 139     pip install -U <plugin-name>
 140
 141 The ``-U`` tells pip to upgrade the package.
 142
 143
 144 Troubleshooting plugins
 145 =======================
 146
 147 Sometimes plugins just don't work right. When you're having problems
 148 with plugins, think about the following:
 149
 150 1. Check the log files.
 151
 152    Some plugins will log errors to the log files and you can use that
 153    to diagnose the problem.
 154
 155 2. Try running MediaGoblin without that plugin.
 156
 157    It's easy to disable a plugin from MediaGoblin. Add a ``-`` to the
 158    name in your config file.
 159
 160    For example, change::
 161
 162        [[mediagoblin.plugins.flatpagesfile]]
 163
 164    to::
 165
 166        [[-mediagoblin.plugins.flatpagesfile]]
 167
 168    That'll prevent the ``mediagoblin.plugins.flatpagesfile`` plugin from
 169    loading.
 170
 171 3. If it's a core plugin that comes with MediaGoblin, ask us for help!
 172
 173    If it's a plugin you got from somewhere else, ask them for help!