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-licenses" (which allows you to customize the licenses you
  48 offer for your media), we would do::
  49
  50     pip install mediagoblin-licenses
  51
  52 .. Note::
  53
  54    If you're using a virtual environment, make sure to activate the
  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).
  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
  65 For example, say the "mediagoblin-licenses" plugin has the Python
  66 package path ``mediagoblin_licenses``, then you would add ``mediagoblin_licenses`` to
  67 the ``plugins`` section as a subsection::
  68
  69     [plugins]
  70
  71     [[mediagoblin_licenses]]
  72     license_01=abbrev1, name1, http://url1
  73     license_02=abbrev2, name1, http://url2
  74
  75
  76 Configuring plugins
  77 ===================
  78
  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.
  82
  83 Example 1: Core MediaGoblin plugin
  84
  85 If you wanted to use the core MediaGoblin flatpages plugin, the module
  86 for that is ``mediagoblin.plugins.flatpagesfile`` and you would add
  87 that to your ``.ini`` file like this::
  88
  89     [plugins]
  90
  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`)
  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
 119     pip uninstall mediagoblin-licenses
 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.
 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.
 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
 166        [[mediagoblin.plugins.flatpagesfile]]
 167
 168    to::
 169
 170        [[-mediagoblin.plugins.flatpagesfile]]
 171
 172    That'll prevent the ``mediagoblin.plugins.flatpagesfile`` plugin from
 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!