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.flatpages`` and you would add that
  83 to your ``.ini`` file like this::
  84
  85     [plugins]
  86
  87     [[mediagoblin.plugins.flatpages]]
  88     # configuration for flatpages plugin here!
  89     directory = /srv/mediagoblin/flatpages
  90
  91 Example 2: Plugin that is not a core MediaGoblin plugin
  92
  93 If you installed a hypothetical restrictfive plugin which is in the
  94 module ``restrictfive``, your ``.ini`` file might look like this (with
  95 comments making the bits clearer)::
  96
  97     [plugins]
  98
  99     [[restrictfive]]
 100     # configuration for restrictfive here!
 101
 102 Check the plugin's documentation for what configuration options are
 103 available.
 104
 105
 106 Removing plugins
 107 ================
 108
 109 To remove a plugin, use ``pip uninstall``. For example::
 110
 111     pip uninstall mediagoblin-restrictfive
 112
 113 .. Note::
 114
 115    If you're using a virtual environment, make sure to activate the
 116    virtual environment before uninstalling with pip. Otherwise the
 117    plugin may get installed in a different environment.
 118
 119
 120 Upgrading plugins
 121 =================
 122
 123 Core plugins
 124 ------------
 125
 126 Core plugins get upgraded automatically when you upgrade MediaGoblin
 127 because they come with MediaGoblin.
 128
 129
 130 Other plugins
 131 -------------
 132
 133 For plugins that you install with pip, you can upgrade them with pip::
 134
 135     pip install -U <plugin-name>
 136
 137 The ``-U`` tells pip to upgrade the package.