docs/source/plugins.rst

   1 =========
   2  Plugins
   3 =========
   4
   5 GNU MediaGoblin supports plugins that, when installed, allow you to
   6 augment MediaGoblin's 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. Since these plugins don't come with
  22 MediaGoblin, you must first install them, then add them to your
  23 configuration.
  24
  25
  26 Installing plugins
  27 ==================
  28
  29 MediaGoblin core plugins don't need to be installed. For core plugins,
  30 you can skip installation!
  31
  32 If the plugin is not a core plugin and is packaged and available on
  33 the Python Package Index, then you can install the plugin with pip::
  34
  35     pip install <plugin-name>
  36
  37 For example, if we wanted to install the plugin named
  38 "mediagoblin-restrictfive", we would do::
  39
  40     pip install mediagoblin-restrictfive
  41
  42 .. Note::
  43
  44    If you're using a virtual environment, make sure to activate the
  45    virtual environment before installing with pip. Otherwise the
  46    plugin may get installed in a different environment.
  47
  48 Once you've installed the plugin software, you need to tell
  49 MediaGoblin that this is a plugin you want MediaGoblin to use. To do
  50 that, you edit the ``mediagoblin.ini`` file and add the plugin as a
  51 subsection of the plugin section.
  52
  53 For example, say the "mediagoblin-restrictfive" plugin had the Python
  54 package path ``restrictfive``, then you would add ``restrictfive`` to
  55 the ``plugins`` section as a subsection::
  56
  57     [plugins]
  58
  59     [[restrictfive]]
  60
  61
  62 Configuring plugins
  63 ===================
  64
  65 Generally, configuration goes in the ``.ini`` file. Configuration for
  66 a specific plugin, goes in a subsection of the ``plugins`` section.
  67
  68 Example 1: Core MediaGoblin plugin
  69
  70 If you wanted to use the core MediaGoblin flatpages plugin, the module
  71 for that is ``mediagoblin.plugins.flatpages`` and you would add that
  72 to your ``.ini`` file like this::
  73
  74     [plugins]
  75
  76     [[mediagoblin.plugins.flatpages]]
  77     # configuration for flatpages plugin here!
  78
  79 Example 2: Plugin that is not a core MediaGoblin plugin
  80
  81 If you installed a hypothetical restrictfive plugin which is in the
  82 module ``restrictfive``, your ``.ini`` file might look like this (with
  83 comments making the bits clearer)::
  84
  85     [plugins]
  86
  87     [[restrictfive]]
  88     # configuration for restrictfive here!
  89
  90 Check the plugin's documentation for what configuration options are
  91 available.
  92
  93
  94 Removing plugins
  95 ================
  96
  97 To remove a plugin, use ``pip uninstall``. For example::
  98
  99     pip uninstall mediagoblin-restrictfive
 100
 101 .. Note::
 102
 103    If you're using a virtual environment, make sure to activate the
 104    virtual environment before uninstalling with pip. Otherwise the
 105    plugin may get installed in a different environment.