doc/Plugins.md

   1 Friendica Addon/Plugin development
   2 ==========================
   3
   4 Please see the sample addon 'randplace' for a working example of using some of these features.
   5 The facebook addon provides an example of integrating both "addon" and "module" functionality.
   6 Addons work by intercepting event hooks - which must be registered.
   7 Modules work by intercepting specific page requests (by URL path).
   8
   9 Plugin names cannot contain spaces or other punctuation and are used as filenames and function names.
  10 You may supply a "friendly" name within the comment block.
  11 Each addon must contain both an install and an uninstall function based on the addon/plugin name.
  12 For instance "plugin1name_install()".
  13 These two functions take no arguments and are usually responsible for registering (and unregistering) event hooks that your plugin will require.
  14 The install and uninstall functions will also be called (i.e. re-installed) if the plugin changes after installation.
  15 Therefore your uninstall should not destroy data and install should consider that data may already exist.
  16 Future extensions may provide for "setup" amd "remove".
  17
  18 Plugins should contain a comment block with the four following parameters:
  19
  20         /*
  21         * Name: My Great Plugin
  22         * Description: This is what my plugin does. It's really cool
  23         * Version: 1.0
  24         * Author: John Q. Public <john@myfriendicasite.com>
  25         */
  26
  27 Register your plugin hooks during installation.
  28
  29     register_hook($hookname, $file, $function);
  30
  31 $hookname is a string and corresponds to a known Friendica hook.
  32
  33 $file is a pathname relative to the top-level Friendica directory.
  34 This *should* be 'addon/plugin_name/plugin_name.php' in most cases.
  35
  36 $function is a string and is the name of the function which will be executed when the hook is called.
  37
  38 Arguments
  39 ---
  40 Your hook callback functions will be called with at least one and possibly two arguments
  41
  42     function myhook_function(&$a, &$b) {
  43
  44     }
  45
  46
  47 If you wish to make changes to the calling data, you must declare them as reference variables (with '&') during function declaration.
  48
  49 ###$a
  50 $a is the Friendica 'App' class.
  51 It contains a wealth of information about the current state of Friendica:
  52
  53 * which module has been called,
  54 * configuration information,
  55 * the page contents at the point the hook was invoked,
  56 * profile and user information, etc.
  57
  58 It is recommeded you call this '$a' to match its usage elsewhere.
  59
  60 ###$b
  61 $b can be called anything you like.
  62 This is information specific to the hook currently being processed, and generally contains information that is being immediately processed or acted on that you can use, display, or alter.
  63 Remember to declare it with '&' if you wish to alter it.
  64
  65 Modules
  66 --------
  67
  68 Plugins/addons may also act as "modules" and intercept all page requests for a given URL path.
  69 In order for a plugin to act as a module it needs to define a function "plugin_name_module()" which takes no arguments and needs not do anything.
  70
  71 If this function exists, you will now receive all page requests for "http://my.web.site/plugin_name" - with any number of URL components as additional arguments.
  72 These are parsed into an array $a->argv, with a corresponding $a->argc indicating the number of URL components.
  73 So http://my.web.site/plugin/arg1/arg2 would look for a module named "plugin" and pass its module functions the $a App structure (which is available to many components).
  74 This will include:
  75
  76      $a->argc = 3
  77      $a->argv = array(0 => 'plugin', 1 => 'arg1', 2 => 'arg2');
  78
  79 Your module functions will often contain the function plugin_name_content(&$a), which defines and returns the page body content.
  80 They may also contain plugin_name_post(&$a) which is called before the _content function and typically handles the results of POST forms.
  81 You may also have plugin_name_init(&$a) which is called very early on and often does module initialisation.
  82
  83 Templates
  84 ----------
  85
  86 If your plugin needs some template, you can use the Friendica template system.
  87 Friendica uses [smarty3](http://www.smarty.net/) as a template engine.
  88
  89 Put your tpl files in the *templates/* subfolder of your plugin.
  90
  91 In your code, like in the function plugin_name_content(), load the template file and execute it passing needed values:
  92
  93     # load template file. first argument is the template name,
  94     # second is the plugin path relative to friendica top folder
  95     $tpl = get_markup_template('mytemplate.tpl', 'addon/plugin_name/');
  96
  97     # apply template. first argument is the loaded template,
  98     # second an array of 'name'=>'values' to pass to template
  99     $output = replace_macros($tpl,array(
 100         'title' => 'My beautiful plugin',
 101     ));
 102
 103 See also the wiki page [Quick Template Guide](https://github.com/friendica/friendica/wiki/Quick-Template-Guide).
 104
 105 Current hooks
 106 -------------
 107
 108 ###'authenticate'
 109 'authenticate' is called when a user attempts to login.
 110 $b is an array containing:
 111
 112         'username' => the supplied username
 113         'password' => the supplied password
 114     'authenticated' => set this to non-zero to authenticate the user.
 115     'user_record' => successful authentication must also return a valid user record from the database
 116
 117 ###'logged_in'
 118 'logged_in' is called after a user has successfully logged in.
 119 $b contains the $a->user array.
 120
 121 ###'display_item'
 122 'display_item' is called when formatting a post for display.
 123 $b is an array:
 124
 125         'item' => The item (array) details pulled from the database
 126         'output' => the (string) HTML representation of this item prior to adding it to the page
 127
 128 ###'post_local'
 129 * called when a status post or comment is entered on the local system
 130 * $b is the item array of the information to be stored in the database
 131 * Please note: body contents are bbcode - not HTML
 132
 133 ###'post_local_end'
 134 * called when a local status post or comment has been stored on the local system
 135 * $b is the item array of the information which has just been stored in the database
 136 * Please note: body contents are bbcode - not HTML
 137
 138 ###'post_remote'
 139 * called when receiving a post from another source. This may also be used to post local activity or system generated messages.
 140 * $b is the item array of information to be stored in the database and the item body is bbcode.
 141
 142 ###'settings_form'
 143 * called when generating the HTML for the user Settings page
 144 * $b is the (string) HTML of the settings page before the final '</form>' tag.
 145
 146 ###'settings_post'
 147 * called when the Settings pages are submitted
 148 * $b is the $_POST array
 149
 150 ###'plugin_settings'
 151 * called when generating the HTML for the addon settings page
 152 * $b is the (string) HTML of the addon settings page before the final '</form>' tag.
 153
 154 ###'plugin_settings_post'
 155 * called when the Addon Settings pages are submitted
 156 * $b is the $_POST array
 157
 158 ###'profile_post'
 159 * called when posting a profile page
 160 * $b is the $_POST array
 161
 162 ###'profile_edit'
 163 'profile_edit' is called prior to output of profile edit page.
 164 $b is an array containing:
 165
 166         'profile' => profile (array) record from the database
 167         'entry' => the (string) HTML of the generated entry
 168
 169 ###'profile_advanced'
 170 * called when the HTML is generated for the 'Advanced profile', corresponding to the 'Profile' tab within a person's profile page
 171 * $b is the (string) HTML representation of the generated profile
 172 * The profile array details are in $a->profile.
 173
 174 ###'directory_item'
 175 'directory_item' is called from the Directory page when formatting an item for display.
 176 $b is an array:
 177
 178         'contact' => contact (array) record for the person from the database
 179     'entry' => the (string) HTML of the generated entry
 180
 181 ###'profile_sidebar_enter'
 182 * called prior to generating the sidebar "short" profile for a page
 183 * $b is the person's profile array
 184
 185 ###'profile_sidebar'
 186 'profile_sidebar is called when generating the sidebar "short" profile for a page.
 187 $b is an array:
 188
 189         'profile' => profile (array) record for the person from the database
 190         'entry' => the (string) HTML of the generated entry
 191
 192 ###'contact_block_end'
 193 is called when formatting the block of contacts/friends on a profile sidebar has completed.
 194 $b is an array:
 195
 196         'contacts' => array of contacts
 197         'output' => the (string) generated HTML of the contact block
 198
 199 ###'bbcode'
 200 * called during conversion of bbcode to html
 201 * $b is a string converted text
 202
 203 ###'html2bbcode'
 204 * called during conversion of html to bbcode (e.g. remote message posting)
 205 * $b is a string converted text
 206
 207 ###'page_header'
 208 * called after building the page navigation section
 209 * $b is a string HTML of nav region
 210
 211 ###'personal_xrd'
 212 'personal_xrd' is called prior to output of personal XRD file.
 213 $b is an array:
 214
 215         'user' => the user record for the person
 216         'xml' => the complete XML to be output
 217
 218 ###'home_content'
 219 * called prior to output home page content, shown to unlogged users
 220 * $b is (string) HTML of section region
 221
 222 ###'contact_edit'
 223 is called when editing contact details on an individual from the Contacts page.
 224 $b is an array:
 225
 226         'contact' => contact record (array) of target contact
 227         'output' => the (string) generated HTML of the contact edit page
 228
 229 ###'contact_edit_post'
 230 * called when posting the contact edit page.
 231 * $b is the $_POST array
 232
 233 ###'init_1'
 234 * called just after DB has been opened and before session start
 235 * $b is not used or passed
 236
 237 ###'page_end'
 238 * called after HTML content functions have completed
 239 * $b is (string) HTML of content div
 240
 241 ###'avatar_lookup'
 242 'avatar_lookup' is called when looking up the avatar.
 243 $b is an array:
 244
 245         'size' => the size of the avatar that will be looked up
 246         'email' => email to look up the avatar for
 247         'url' => the (string) generated URL of the avatar
 248
 249 ###'emailer_send_prepare'
 250 'emailer_send_prepare' called from Emailer::send() before building the mime message.
 251 $b is an array, params to Emailer::send()
 252
 253         'fromName' => name of the sender
 254     'fromEmail' => email fo the sender
 255     'replyTo' => replyTo address to direct responses
 256     'toEmail' => destination email address
 257     'messageSubject' => subject of the message
 258     'htmlVersion' => html version of the message
 259     'textVersion' => text only version of the message
 260     'additionalMailHeader' => additions to the smtp mail header
 261
 262 ###'emailer_send'
 263 is called before calling PHP's mail().
 264 $b is an array, params to mail()
 265
 266         'to'
 267         'subject'
 268     'body'
 269     'headers'
 270
 271 Complete list of hook callbacks
 272 ---
 273
 274 Here is a complete list of all hook callbacks with file locations (as of 14-Feb-2012). Please see the source for details of any hooks not documented above.
 275
 276 boot.php:       call_hooks('login_hook',$o);
 277
 278 boot.php:       call_hooks('profile_sidebar_enter', $profile);
 279
 280 boot.php:       call_hooks('profile_sidebar', $arr);
 281
 282 boot.php:       call_hooks("proc_run", $arr);
 283
 284 include/contact_selectors.php:  call_hooks('network_to_name', $nets);
 285
 286 include/api.php:                                call_hooks('logged_in', $a->user);
 287
 288 include/api.php:                call_hooks('logged_in', $a->user);
 289
 290 include/queue.php:              call_hooks('queue_predeliver', $a, $r);
 291
 292 include/queue.php:                              call_hooks('queue_deliver', $a, $params);
 293
 294 include/text.php:       call_hooks('contact_block_end', $arr);
 295
 296 include/text.php:       call_hooks('smilie', $s);
 297
 298 include/text.php:       call_hooks('prepare_body_init', $item);
 299
 300 include/text.php:       call_hooks('prepare_body', $prep_arr);
 301
 302 include/text.php:       call_hooks('prepare_body_final', $prep_arr);
 303
 304 include/nav.php:        call_hooks('page_header', $a->page['nav']);
 305
 306 include/auth.php:               call_hooks('authenticate', $addon_auth);
 307
 308 include/bbcode.php:     call_hooks('bbcode',$Text);
 309
 310 include/oauth.php:              call_hooks('logged_in', $a->user);
 311
 312 include/acl_selectors.php:      call_hooks($a->module . '_pre_' . $selname, $arr);
 313
 314 include/acl_selectors.php:      call_hooks($a->module . '_post_' . $selname, $o);
 315
 316 include/acl_selectors.php:      call_hooks('contact_select_options', $x);
 317
 318 include/acl_selectors.php:      call_hooks($a->module . '_pre_' . $selname, $arr);
 319
 320 include/acl_selectors.php:      call_hooks($a->module . '_post_' . $selname, $o);
 321
 322 include/acl_selectors.php:      call_hooks($a->module . '_pre_' . $selname, $arr);
 323
 324 include/acl_selectors.php:      call_hooks($a->module . '_post_' . $selname, $o);
 325
 326 include/notifier.php:           call_hooks('notifier_normal',$target_item);
 327
 328 include/notifier.php:   call_hooks('notifier_end',$target_item);
 329
 330 include/items.php:      call_hooks('atom_feed', $atom);
 331
 332 include/items.php:              call_hooks('atom_feed_end', $atom);
 333
 334 include/items.php:      call_hooks('atom_feed_end', $atom);
 335
 336 include/items.php:      call_hooks('parse_atom', $arr);
 337
 338 include/items.php:      call_hooks('post_remote',$arr);
 339
 340 include/items.php:      call_hooks('atom_author', $o);
 341
 342 include/items.php:      call_hooks('atom_entry', $o);
 343
 344 include/bb2diaspora.php:        call_hooks('bb2diaspora',$Text);
 345
 346 include/cronhooks.php:  call_hooks('cron', $d);
 347
 348 include/security.php:           call_hooks('logged_in', $a->user);
 349
 350 include/html2bbcode.php:        call_hooks('html2bbcode', $text);
 351
 352 include/Contact.php:    call_hooks('remove_user',$r[0]);
 353
 354 include/Contact.php:    call_hooks('contact_photo_menu', $args);
 355
 356 include/conversation.php:       call_hooks('conversation_start',$cb);
 357
 358 include/conversation.php:                               call_hooks('render_location',$locate);
 359
 360 include/conversation.php:                               call_hooks('display_item', $arr);
 361
 362 include/conversation.php:                               call_hooks('render_location',$locate);
 363
 364 include/conversation.php:                               call_hooks('display_item', $arr);
 365
 366 include/conversation.php:       call_hooks('item_photo_menu', $args);
 367
 368 include/conversation.php:       call_hooks('jot_tool', $jotplugins);
 369
 370 include/conversation.php:       call_hooks('jot_networks', $jotnets);
 371
 372 include/plugin.php:if(! function_exists('call_hooks')) {
 373
 374 include/plugin.php:function call_hooks($name, &$data = null) {
 375
 376 index.php:      call_hooks('init_1');
 377
 378 index.php:call_hooks('app_menu', $arr);
 379
 380 index.php:call_hooks('page_end', $a->page['content']);
 381
 382 mod/photos.php: call_hooks('photo_post_init', $_POST);
 383
 384 mod/photos.php: call_hooks('photo_post_file',$ret);
 385
 386 mod/photos.php:         call_hooks('photo_post_end',$foo);
 387
 388 mod/photos.php:         call_hooks('photo_post_end',$foo);
 389
 390 mod/photos.php:         call_hooks('photo_post_end',$foo);
 391
 392 mod/photos.php: call_hooks('photo_post_end',intval($item_id));
 393
 394 mod/photos.php:         call_hooks('photo_upload_form',$ret);
 395
 396 mod/friendica.php:      call_hooks('about_hook', $o);
 397
 398 mod/editpost.php:       call_hooks('jot_tool', $jotplugins);
 399
 400 mod/editpost.php:       call_hooks('jot_networks', $jotnets);
 401
 402 mod/parse_url.php:      call_hooks('parse_link', $arr);
 403
 404 mod/home.php:   call_hooks('home_init',$ret);
 405
 406 mod/home.php:   call_hooks("home_content",$o);
 407
 408 mod/contacts.php:       call_hooks('contact_edit_post', $_POST);
 409
 410 mod/contacts.php:               call_hooks('contact_edit', $arr);
 411
 412 mod/settings.php:               call_hooks('plugin_settings_post', $_POST);
 413
 414 mod/settings.php:               call_hooks('connector_settings_post', $_POST);
 415
 416 mod/settings.php:       call_hooks('settings_post', $_POST);
 417
 418 mod/settings.php:               call_hooks('plugin_settings', $settings_addons);
 419
 420 mod/settings.php:               call_hooks('connector_settings', $settings_connectors);
 421
 422 mod/settings.php:       call_hooks('settings_form',$o);
 423
 424 mod/register.php:       call_hooks('register_account', $newuid);
 425
 426 mod/like.php:   call_hooks('post_local_end', $arr);
 427
 428 mod/xrd.php:    call_hooks('personal_xrd', $arr);
 429
 430 mod/item.php:   call_hooks('post_local_start', $_REQUEST);
 431
 432 mod/item.php:   call_hooks('post_local',$datarray);
 433
 434 mod/item.php:   call_hooks('post_local_end', $datarray);
 435
 436 mod/profile.php:                        call_hooks('profile_advanced',$o);
 437
 438 mod/profiles.php:       call_hooks('profile_post', $_POST);
 439
 440 mod/profiles.php:               call_hooks('profile_edit', $arr);
 441
 442 mod/tagger.php: call_hooks('post_local_end', $arr);
 443
 444 mod/cb.php:     call_hooks('cb_init');
 445
 446 mod/cb.php:     call_hooks('cb_post', $_POST);
 447
 448 mod/cb.php:     call_hooks('cb_afterpost');
 449
 450 mod/cb.php:     call_hooks('cb_content', $o);
 451
 452 mod/directory.php:                      call_hooks('directory_item', $arr);
 453