PLUGINS.txt

   1 Plugins
   2 =======
   3
   4 GNU social supports a simple but
   5 powerful plugin architecture. Important events in the code are named,
   6 like 'StartNoticeSave', and other software can register interest
   7 in those events. When the events happen, the other software is called
   8 and has a choice of accepting or rejecting the events.
   9
  10 In the simplest case, you can add a function to config.php and use the
  11 Event::addHandler() function to hook an event:
  12
  13     function AddGoogleLink($action)
  14     {
  15         $action->menuItem('http://www.google.com/', _('Google'), _('Search engine'));
  16         return true;
  17     }
  18
  19     Event::addHandler('EndPrimaryNav', 'AddGoogleLink');
  20
  21 This adds a menu item to the end of the main navigation menu. You can
  22 see the list of existing events, and parameters that handlers must
  23 implement, in EVENTS.txt.
  24
  25 The Plugin class in lib/plugin.php makes it easier to write more
  26 complex plugins. Sub-classes can just create methods named
  27 'onEventName', where 'EventName' is the name of the event (case
  28 matters!). These methods will be automatically registered as event
  29 handlers by the Plugin constructor (which you must call from your own
  30 class's constructor).
  31
  32 Several example plugins are included in the plugins/ directory. You
  33 can enable a plugin with the following line in config.php:
  34
  35     addPlugin('Example', array('param1' => 'value1',
  36                                'param2' => 'value2'));
  37
  38 This will look for and load files named 'ExamplePlugin.php' or
  39 'Example/ExamplePlugin.php' either in the plugins/ directory (for
  40 plugins that ship with GNU social) or in the local/ directory (for
  41 plugins you write yourself or that you get from somewhere else) or
  42 local/plugins/.
  43
  44 Plugins are documented in their own directories.