doc/de/Addons.md

   1 Friendica Addon/Entwicklung
   2 ==============
   3
   4 * [Zur Startseite der Hilfe](help)
   5
   6 Bitte schau dir das Beispiel-Addon "randplace" für ein funktionierendes Beispiel für manche der hier aufgeführten Funktionen an.
   7 Das Facebook-Addon bietet ein Beispiel dafür, die "addon"- und "module"-Funktion gemeinsam zu integrieren.
   8 Addons arbeiten, indem sie Event Hooks abfangen.
   9 Module arbeiten, indem bestimmte Seitenanfragen (durch den URL-Pfad) abgefangen werden.
  10
  11 Addon-Namen können keine Leerstellen oder andere Interpunktionen enthalten und werden als Datei- und Funktionsnamen genutzt.
  12 Du kannst einen lesbaren Namen im Kommentarblock eintragen.
  13 Jedes Addon muss beides beinhalten - eine Installations- und eine Deinstallationsfunktion, die auf dem Addon-Namen basieren; z.B. "addon1name_install()".
  14 Diese beiden Funktionen haben keine Argumente und sind dafür verantwortlich, Event Hooks zu registrieren und abzumelden (unregistering), die dein Addon benötigt.
  15 Die Installations- und Deinstallationsfunktionfunktionen werden auch ausgeführt (z.B. neu installiert), wenn sich das Addon nach der Installation ändert - somit sollte deine Deinstallationsfunktion keine Daten zerstört und deine Installationsfunktion sollte bestehende Daten berücksichtigen.
  16 Zukünftige Extensions werden möglicherweise "Setup" und "Entfernen" anbieten.
  17
  18 Addons sollten einen Kommentarblock mit den folgenden vier Parametern enthalten:
  19
  20     /*
  21      * Name: My Great Addon
  22      * Description: This is what my addon does. It's really cool.
  23      * Version: 1.0
  24      * Author: John Q. Public <john@myfriendicasite.com>
  25      */
  26
  27 Registriere deine Addon-Hooks während der Installation.
  28
  29     \Friendica\Core\Hook::register($hookname, $file, $function);
  30
  31 $hookname ist ein String und entspricht einem bekannten Friendica-Hook.
  32
  33 $file steht für den Pfadnamen, der relativ zum Top-Level-Friendicaverzeichnis liegt.
  34 Das *sollte* "addon/addon_name/addon_name.php' sein.
  35
  36 $function ist ein String und der Name der Funktion, die ausgeführt wird, wenn der Hook aufgerufen wird.
  37
  38 Argumente
  39 ---
  40
  41 Deine Hook-Callback-Funktion wird mit mindestens einem und bis zu zwei Argumenten aufgerufen
  42
  43     function myhook_function(App $a, &$b) {
  44
  45     }
  46
  47 Wenn du Änderungen an den aufgerufenen Daten vornehmen willst, musst du diese als Referenzvariable (mit "&") während der Funktionsdeklaration deklarieren.
  48
  49 $a ist die Friendica "App"-Klasse, die eine Menge an Informationen über den aktuellen Friendica-Status beinhaltet, u.a. welche Module genutzt werden, Konfigurationsinformationen, Inhalte der Seite zum Zeitpunkt des Hook-Aufrufs.
  50 Es ist empfohlen, diese Funktion "$a" zu nennen, um seine Nutzung an den Gebrauch an anderer Stelle anzugleichen.
  51
  52 $b kann frei benannt werden.
  53 Diese Information ist speziell auf den Hook bezogen, der aktuell bearbeitet wird, und beinhaltet normalerweise Daten, die du sofort nutzen, anzeigen oder bearbeiten kannst.
  54 Achte darauf, diese mit "&" zu deklarieren, wenn du sie bearbeiten willst.
  55
  56
  57 Module
  58 ---
  59
  60 Addons können auch als "Module" agieren und alle Seitenanfragen für eine bestimte URL abfangen.
  61 Um ein Addon als Modul zu nutzen, ist es nötig, die Funktion "addon_name_module()" zu definieren, die keine Argumente benötigt und nichts weiter machen muss.
  62
  63 Wenn diese Funktion existiert, wirst du nun alle Seitenanfragen für "http://example.com/addon_name" erhalten - mit allen URL-Komponenten als zusätzliche Argumente.
  64 Diese werden in das App\Arguments Objekt geparst.
  65 So würde `http://example.com/addon/arg1/arg2` dies ergeben:
  66 ```php
  67 DI::args()->getArgc(); // = 3
  68 DI::args()->get(0); // = 'addon'
  69 DI::args()->get(1); // = 'arg1'
  70 DI::args()->get(2); // = 'arg2'
  71 ```
  72
  73 Deine Modulfunktionen umfassen oft die Funktion addon_name_content(App $a), welche den Seiteninhalt definiert und zurückgibt.
  74 Sie können auch addon_name_post(App $a) umfassen, welches vor der content-Funktion aufgerufen wird und normalerweise die Resultate der POST-Formulare handhabt.
  75 Du kannst ebenso addon_name_init(App $a) nutzen, was oft frühzeitig aufgerufen wird und das Modul initialisert.
  76
  77
  78 Derzeitige Hooks
  79 ---
  80
  81 **'authenticate'** - wird aufgerufen, wenn sich der User einloggt.
  82     $b ist ein Array
  83         'username' => der übertragene Nutzername
  84         'password' => das übertragene Passwort
  85         'authenticated' => setze das auf einen anderen Wert als "0", damit der User sich authentifiziert
  86         'user_record' => die erfolgreiche Authentifizierung muss auch einen gültigen Nutzereintrag aus der Datenbank zurückgeben
  87
  88 **'logged_in'** - wird aufgerufen, sobald ein Nutzer sich erfolgreich angemeldet hat.
  89     $b beinhaltet den $a->Nutzer-Array
  90
  91
  92 **'display_item'** - wird aufgerufen, wenn ein Beitrag für die Anzeige formatiert wird.
  93     $b ist ein Array
  94         'item' => Die Item-Details (Array), die von der Datenbank ausgegeben werden
  95         'output' => Die HTML-Ausgabe (String) des Items, bevor es zur Seite hinzugefügt wird
  96
  97 **'post_local'** - wird aufgerufen, wenn der Statusbeitrag oder ein Kommentar im lokalen System eingetragen wird.
  98     $b ist das Item-Array der Information, die in der Datenbank hinterlegt wird.
  99         {Bitte beachte: der Seiteninhalt ist bbcode - nicht HTML)
 100
 101 **'post_local_end'** - wird aufgerufen, wenn ein lokaler Statusbeitrag oder Kommentar im lokalen System gespeichert wird.
 102     $b ist das Item-Array einer Information, die gerade in der Datenbank gespeichert wurden.
 103         {Bitte beachte: der Seiteninhalt ist bbcode - nicht HTML)
 104
 105 **'post_remote'** - wird aufgerufen, wenn ein Beitrag aus einer anderen Quelle empfangen wird. Dies kann auch genutzt werden, um lokale Aktivitäten oder systemgenerierte Nachrichten zu veröffentlichen/posten.
 106     $b ist das Item-Array einer Information, die in der Datenbank und im Item gespeichert ist.
 107         {Bitte beachte: der Seiteninhalt ist bbcode - nicht HTML)
 108
 109 **'settings_form'** - wird aufgerufen, wenn die HTML-Ausgabe für die Einstellungsseite generiert wird.
 110     $b ist die HTML-Ausgabe (String) der Einstellungsseite vor dem finalen "</form>"-Tag.
 111
 112 **'settings_post'** - wird aufgerufen, wenn die Einstellungsseiten geladen werden.
 113     $b ist der $_POST-Array
 114
 115 **'addon_settings'** - wird aufgerufen, wenn die HTML-Ausgabe der Addon-Einstellungsseite generiert wird.
 116     $b ist die HTML-Ausgabe (String) der Addon-Einstellungsseite vor dem finalen "</form>"-Tag.
 117
 118 **'addon_settings_post'** - wird aufgerufen, wenn die Addon-Einstellungsseite geladen wird.
 119     $b ist der $_POST-Array
 120
 121 **'profile_post'** - wird aufgerufen, wenn die Profilseite angezeigt wird.
 122     $b ist der $_POST-Array
 123
 124 **'profile_edit'** - wird aufgerufen, bevor die Profil-Bearbeitungsseite angezeigt wird.
 125     $b ist ein Array
 126         'profile' => Profileintrag (Array) aus der Datenbank
 127         'entry' => die HTML-Ausgabe (string) des generierten Eintrags
 128
 129 **'profile_advanced'** - wird aufgerufen, wenn die HTML-Ausgabe für das "Advanced profile" generiert wird; stimmt mit dem "Profil"-Tab auf der Profilseite der Nutzer überein.
 130     $b ist die HTML-Ausgabe (String) des erstellten Profils
 131     (Die Details des Profil-Arrays sind in $a->profile)
 132
 133 **'directory_item'** - wird von der Verzeichnisseite aufgerufen, wenn ein Item für die Anzeige formatiert wird.
 134     $b ist ein Array
 135         'contact' => Kontakteintrag (Array) einer Person aus der Datenbank
 136         'entry' => die HTML-Ausgabe (String) des generierten Eintrags
 137
 138 **'profile_sidebar_enter'** - wird aufgerufen, bevor die Sidebar "Kurzprofil" einer Seite erstellt wird.
 139     $b ist der Profil-Array einer Person
 140
 141 **'profile_sidebar'** - wird aufgerufen, wenn die Sidebar "Kurzprofil" einer Seite erstellt wird.
 142     $b ist ein Array
 143         'profile' => Kontakteintrag (Array) einer Person aus der Datenbank
 144         'entry' => die HTML-Ausgabe (String) des generierten Eintrags
 145
 146 **'contact_block_end'** - wird aufgerufen, wenn der Block "Kontakte/Freunde" der Profil-Sidebar komplett formatiert wurde.
 147     $b ist ein Array
 148           'contacts' => Array von "contacts"
 149           'output' => die HTML-Ausgabe (String) des Kontaktblocks
 150
 151 **'bbcode'** - wird während der Umwandlung von bbcode auf HTML aufgerufen.
 152     $b ist der konvertierte Text (String)
 153
 154 **'html2bbcode'** - wird während der Umwandlung von HTML zu bbcode aufgerufen (z.B. bei Nachrichtenbeiträgen).
 155     $b ist der konvertierte Text (String)
 156
 157 **'page_header'** - wird aufgerufen, nachdem der Bereich der Seitennavigation geladen wurde.
 158     $b ist die HTML-Ausgabe (String) der "nav"-Region
 159
 160 **'personal_xrd'** - wird aufgerufen, bevor die Ausgabe der persönlichen XRD-Datei erzeugt wird.
 161     $b ist ein Array
 162         'user' => die hinterlegten Einträge der Person
 163         'xml' => die komplette XML-Datei die ausgegeben wird
 164
 165 **'home_content'** - wird aufgerufen, bevor die Ausgabe des Homepage-Inhalts erstellt wird; wird nicht eingeloggten Nutzern angezeigt.
 166     $b ist die HTML-Ausgabe (String) der Auswahlregion
 167
 168 **'contact_edit'** - wird aufgerufen, wenn die Kontaktdetails vom Nutzer auf der "Kontakte"-Seite bearbeitet werden.
 169     $b ist ein Array
 170         'contact' => Kontakteintrag (Array) des abgezielten Kontakts
 171         'output' => die HTML-Ausgabe (String) der "Kontakt bearbeiten"-Seite
 172
 173 **'contact_edit_post'** - wird aufgerufen, wenn die "Kontakt bearbeiten"-Seite ausgegeben wird.
 174     $b ist der $_POST-Array
 175
 176 **'init_1'** - wird aufgerufen, kurz nachdem die Datenbank vor Beginn der Sitzung geöffnet wird.
 177     $b wird nicht genutzt
 178
 179 **'page_end'** - wird aufgerufen, nachdem die Funktion des HTML-Inhalts komplett abgeschlossen ist.
 180     $b ist die HTML-Ausgabe (String) vom Inhalt-"div"
 181
 182 **'avatar_lookup'** - wird aufgerufen, wenn der Avatar geladen wird.
 183     $b ist ein Array
 184         'size' => Größe des Avatars, der geladen wird
 185         'email' => Email-Adresse, um nach dem Avatar zu suchen
 186         'url' => generierte URL (String) des Avatars
 187
 188 **'nav_info'**
 189  - wird aufgerufen nachdem in include/nav,php der Inhalt des Navigations Menüs erzeugt wurde.
 190  - $b ist ein Array, das $nav wiederspiegelt.
 191
 192 Komplette Liste der Hook-Callbacks
 193 ---
 194
 195 Eine komplette Liste aller Hook-Callbacks mit den zugehörigen Dateien (am 01-Apr-2018 generiert): Bitte schau in die Quellcodes für Details zu Hooks, die oben nicht dokumentiert sind.
 196
 197 ### index.php
 198
 199     Hook::callAll('init_1');
 200     Hook::callAll('app_menu', $arr);
 201     Hook::callAll('page_content_top', DI::page()['content']);
 202     Hook::callAll($a->module.'_mod_init', $placeholder);
 203     Hook::callAll($a->module.'_mod_init', $placeholder);
 204     Hook::callAll($a->module.'_mod_post', $_POST);
 205     Hook::callAll($a->module.'_mod_content', $arr);
 206     Hook::callAll($a->module.'_mod_aftercontent', $arr);
 207     Hook::callAll('page_end', DI::page()['content']);
 208
 209 ### include/api.php
 210
 211     Hook::callAll('logged_in', $a->user);
 212     Hook::callAll('authenticate', $addon_auth);
 213     Hook::callAll('logged_in', $a->user);
 214
 215 ### include/enotify.php
 216
 217     Hook::callAll('enotify', $h);
 218     Hook::callAll('enotify_store', $datarray);
 219     Hook::callAll('enotify_mail', $datarray);
 220     Hook::callAll('check_item_notification', $notification_data);
 221
 222 ### src/Content/Conversation.php
 223
 224     Hook::callAll('conversation_start', $cb);
 225     Hook::callAll('render_location', $locate);
 226     Hook::callAll('display_item', $arr);
 227     Hook::callAll('display_item', $arr);
 228     Hook::callAll('item_photo_menu', $args);
 229     Hook::callAll('jot_tool', $jotplugins);
 230
 231 ### mod/directory.php
 232
 233     Hook::callAll('directory_item', $arr);
 234
 235 ### mod/xrd.php
 236
 237     Hook::callAll('personal_xrd', $arr);
 238
 239 ### mod/parse_url.php
 240
 241     Hook::callAll("parse_link", $arr);
 242
 243 ### src/Module/Delegation.php
 244
 245     Hook::callAll('home_init', $ret);
 246
 247 ### mod/acl.php
 248
 249     Hook::callAll('acl_lookup_end', $results);
 250
 251 ### mod/network.php
 252
 253     Hook::callAll('network_content_init', $arr);
 254     Hook::callAll('network_tabs', $arr);
 255
 256 ### mod/friendica.php
 257
 258     Hook::callAll('about_hook', $o);
 259
 260 ### mod/profiles.php
 261
 262     Hook::callAll('profile_post', $_POST);
 263     Hook::callAll('profile_edit', $arr);
 264
 265 ### mod/settings.php
 266
 267     Hook::callAll('addon_settings_post', $_POST);
 268     Hook::callAll('connector_settings_post', $_POST);
 269     Hook::callAll('display_settings_post', $_POST);
 270     Hook::callAll('settings_post', $_POST);
 271     Hook::callAll('addon_settings', $settings_addons);
 272     Hook::callAll('connector_settings', $settings_connectors);
 273     Hook::callAll('display_settings', $o);
 274     Hook::callAll('settings_form', $o);
 275
 276 ### mod/photos.php
 277
 278     Hook::callAll('photo_post_init', $_POST);
 279     Hook::callAll('photo_post_file', $ret);
 280     Hook::callAll('photo_post_end', $foo);
 281     Hook::callAll('photo_post_end', $foo);
 282     Hook::callAll('photo_post_end', $foo);
 283     Hook::callAll('photo_post_end', $foo);
 284     Hook::callAll('photo_post_end', intval($item_id));
 285     Hook::callAll('photo_upload_form', $ret);
 286
 287 ### mod/profile.php
 288
 289     Hook::callAll('profile_advanced', $o);
 290
 291 ### mod/home.php
 292
 293     Hook::callAll('home_init', $ret);
 294     Hook::callAll("home_content", $content);
 295
 296 ### mod/poke.php
 297
 298     Hook::callAll('post_local_end', $arr);
 299
 300 ### mod/contacts.php
 301
 302     Hook::callAll('contact_edit_post', $_POST);
 303     Hook::callAll('contact_edit', $arr);
 304
 305 ### mod/tagger.php
 306
 307     Hook::callAll('post_local_end', $arr);
 308
 309 ### mod/uexport.php
 310
 311     Hook::callAll('uexport_options', $options);
 312
 313 ### mod/register.php
 314
 315     Hook::callAll('register_post', $arr);
 316     Hook::callAll('register_form', $arr);
 317
 318 ### mod/item.php
 319
 320     Hook::callAll('post_local_start', $_REQUEST);
 321     Hook::callAll('post_local', $datarray);
 322     Hook::callAll('post_local_end', $datarray);
 323
 324 ### mod/editpost.php
 325
 326     Hook::callAll('jot_tool', $jotplugins);
 327
 328 ### src/Network/FKOAuth1.php
 329
 330     Hook::callAll('logged_in', $a->user);
 331
 332 ### src/Render/FriendicaSmartyEngine.php
 333
 334     Hook::callAll("template_vars", $arr);
 335
 336 ### src/Model/Item.php
 337
 338     Hook::callAll('post_local', $item);
 339     Hook::callAll('post_remote', $item);
 340     Hook::callAll('post_local_end', $posted_item);
 341     Hook::callAll('post_remote_end', $posted_item);
 342     Hook::callAll('tagged', $arr);
 343     Hook::callAll('post_local_end', $new_item);
 344     Hook::callAll('put_item_in_cache', $hook_data);
 345     Hook::callAll('prepare_body_init', $item);
 346     Hook::callAll('prepare_body_content_filter', $hook_data);
 347     Hook::callAll('prepare_body', $hook_data);
 348     Hook::callAll('prepare_body_final', $hook_data);
 349
 350 ### src/Model/Contact.php
 351
 352     Hook::callAll('contact_photo_menu', $args);
 353     Hook::callAll('follow', $arr);
 354
 355 ### src/Model/Profile.php
 356
 357     Hook::callAll('profile_sidebar_enter', $profile);
 358     Hook::callAll('profile_sidebar', $arr);
 359     Hook::callAll('profile_tabs', $arr);
 360     Hook::callAll('zrl_init', $arr);
 361
 362 ### src/Model/Event.php
 363
 364     Hook::callAll('event_updated', $event['id']);
 365     Hook::callAll("event_created", $event['id']);
 366
 367 ### src/Model/User.php
 368
 369     Hook::callAll('register_account', $uid);
 370     Hook::callAll('remove_user', $user);
 371
 372 ### src/Content/ContactBlock.php
 373
 374     Hook::callAll('contact_block_end', $arr);
 375
 376 ### src/Content/Text/BBCode.php
 377
 378     Hook::callAll('bbcode', $text);
 379     Hook::callAll('bb2diaspora', $text);
 380
 381 ### src/Content/Text/HTML.php
 382
 383     Hook::callAll('html2bbcode', $message);
 384
 385 ### src/Content/Smilies.php
 386
 387     Hook::callAll('smilie', $params);
 388
 389 ### src/Content/Feature.php
 390
 391     Hook::callAll('isEnabled', $arr);
 392     Hook::callAll('get', $arr);
 393
 394 ### src/Content/ContactSelector.php
 395
 396     Hook::callAll('network_to_name', $nets);
 397
 398 ### src/Content/OEmbed.php
 399
 400     Hook::callAll('oembed_fetch_url', $embedurl, $j);
 401
 402 ### src/Content/Nav.php
 403
 404     Hook::callAll('page_header', DI::page()['nav']);
 405     Hook::callAll('nav_info', $nav);
 406
 407 ### src/Core/Authentication.php
 408
 409     Hook::callAll('logged_in', $a->user);
 410
 411 ### src/Core/Protocol.php
 412
 413     Hook::callAll('support_follow', $hook_data);
 414     Hook::callAll('support_revoke_follow', $hook_data);
 415     Hook::callAll('unfollow', $hook_data);
 416     Hook::callAll('revoke_follow', $hook_data);
 417     Hook::callAll('block', $hook_data);
 418     Hook::callAll('unblock', $hook_data);
 419
 420 ### src/Core/StorageManager
 421
 422     Hook::callAll('storage_instance', $data);
 423     Hook::callAll('storage_config', $data);
 424
 425 ### src/Module/Notifications/Ping.php
 426
 427     Hook::callAll('network_ping', $arr);
 428
 429 ### src/Module/PermissionTooltip.php
 430
 431     Hook::callAll('lockview_content', $item);
 432
 433 ### src/Worker/Directory.php
 434
 435     Hook::callAll('globaldir_update', $arr);
 436
 437 ### src/Worker/Notifier.php
 438
 439     Hook::callAll('notifier_end', $target_item);
 440
 441 ### src/Module/Login.php
 442
 443     Hook::callAll('authenticate', $addon_auth);
 444     Hook::callAll('login_hook', $o);
 445
 446 ### src/Module/Logout.php
 447
 448     Hook::callAll("logging_out");
 449
 450 ### src/Object/Post.php
 451
 452     Hook::callAll('render_location', $locate);
 453     Hook::callAll('display_item', $arr);
 454
 455 ### src/Core/ACL.php
 456
 457     Hook::callAll('contact_select_options', $x);
 458     Hook::callAll($a->module.'_pre_'.$selname, $arr);
 459     Hook::callAll($a->module.'_post_'.$selname, $o);
 460     Hook::callAll($a->module.'_pre_'.$selname, $arr);
 461     Hook::callAll($a->module.'_post_'.$selname, $o);
 462     Hook::callAll('jot_networks', $jotnets);
 463
 464 ### src/Core/Authentication.php
 465
 466     Hook::callAll('logged_in', $a->user);
 467
 468 ### src/Core/Hook.php
 469
 470     self::callSingle(self::getApp(), 'hook_fork', $fork_hook, $hookdata);
 471
 472 ### src/Core/L10n/L10n.php
 473
 474     Hook::callAll('poke_verbs', $arr);
 475
 476 ### src/Core/Worker.php
 477
 478     Hook::callAll("proc_run", $arr);
 479
 480 ### src/Util/Emailer.php
 481
 482     Hook::callAll('emailer_send_prepare', $email);
 483     Hook::callAll("emailer_send", $hookdata);
 484
 485 ### src/Util/Map.php
 486
 487     Hook::callAll('generate_map', $arr);
 488     Hook::callAll('generate_named_map', $arr);
 489     Hook::callAll('Map::getCoordinates', $arr);
 490
 491 ### src/Util/Network.php
 492
 493     Hook::callAll('avatar_lookup', $avatar);
 494
 495 ### src/Util/ParseUrl.php
 496
 497     Hook::callAll("getsiteinfo", $siteinfo);
 498
 499 ### src/Protocol/DFRN.php
 500
 501     Hook::callAll('atom_feed_end', $atom);
 502     Hook::callAll('atom_feed_end', $atom);
 503
 504 ### src/Protocol/Email.php
 505
 506     Hook::callAll('email_getmessage', $message);
 507     Hook::callAll('email_getmessage_end', $ret);