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 höchstens einem Argumenten aufgerufen
  42
  43     function myhook_function(&$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 $b kann frei benannt werden.
  50 Diese Information ist speziell auf den Hook bezogen, der aktuell bearbeitet wird, und beinhaltet normalerweise Daten, die du sofort nutzen, anzeigen oder bearbeiten kannst.
  51 Achte darauf, diese mit "&" zu deklarieren, wenn du sie bearbeiten willst.
  52
  53
  54 Module
  55 ---
  56
  57 Addons können auch als "Module" agieren und alle Seitenanfragen für eine bestimte URL abfangen.
  58 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.
  59
  60 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.
  61 Diese werden in das App\Arguments Objekt geparst.
  62 So würde `http://example.com/addon/arg1/arg2` dies ergeben:
  63 ```php
  64 DI::args()->getArgc(); // = 3
  65 DI::args()->get(0); // = 'addon'
  66 DI::args()->get(1); // = 'arg1'
  67 DI::args()->get(2); // = 'arg2'
  68 ```
  69
  70 Deine Modulfunktionen umfassen oft die Funktion `addon_name_content()`, welche den Seiteninhalt definiert und zurückgibt.
  71 Sie können auch `addon_name_post()` umfassen, welches vor der content-Funktion aufgerufen wird und normalerweise die Resultate der POST-Formulare handhabt.
  72 Du kannst ebenso `addon_name_init()` nutzen, was oft frühzeitig aufgerufen wird und das Modul initialisert.
  73
  74
  75 Derzeitige Hooks
  76 ---
  77
  78 **'authenticate'** - wird aufgerufen, wenn sich der User einloggt.
  79     $b ist ein Array
  80         'username' => der übertragene Nutzername
  81         'password' => das übertragene Passwort
  82         'authenticated' => setze das auf einen anderen Wert als "0", damit der User sich authentifiziert
  83         'user_record' => die erfolgreiche Authentifizierung muss auch einen gültigen Nutzereintrag aus der Datenbank zurückgeben
  84
  85 **'logged_in'** - wird aufgerufen, sobald ein Nutzer sich erfolgreich angemeldet hat.
  86     $b beinhaltet den `App->user`
  87
  88
  89 **'display_item'** - wird aufgerufen, wenn ein Beitrag für die Anzeige formatiert wird.
  90     $b ist ein Array
  91         'item' => Die Item-Details (Array), die von der Datenbank ausgegeben werden
  92         'output' => Die HTML-Ausgabe (String) des Items, bevor es zur Seite hinzugefügt wird
  93
  94 **'post_local'** - wird aufgerufen, wenn der Statusbeitrag oder ein Kommentar im lokalen System eingetragen wird.
  95     $b ist das Item-Array der Information, die in der Datenbank hinterlegt wird.
  96         {Bitte beachte: der Seiteninhalt ist bbcode - nicht HTML)
  97
  98 **'post_local_end'** - wird aufgerufen, wenn ein lokaler Statusbeitrag oder Kommentar im lokalen System gespeichert wird.
  99     $b ist das Item-Array einer Information, die gerade in der Datenbank gespeichert wurden.
 100         {Bitte beachte: der Seiteninhalt ist bbcode - nicht HTML)
 101
 102 **'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.
 103     $b ist das Item-Array einer Information, die in der Datenbank und im Item gespeichert ist.
 104         {Bitte beachte: der Seiteninhalt ist bbcode - nicht HTML)
 105
 106 **'detect_languages'**
 107 Wird nach der Sprachenerkennung aufgerufen.
 108 Dieser Hook kann dafür verwendet werden, alternative Erkennungsfunktionen einzubinden.
 109 `$data` ist ein Array:
 110         'text' => Der analysierte Text.
 111         'detected' => (Eingabe/Ausgabe) Das Array mit den erkannten Sprachen.
 112
 113 **'addon_settings'** - wird aufgerufen, wenn die HTML-Ausgabe der Addon-Einstellungsseite generiert wird.
 114     $b ist die HTML-Ausgabe (String) der Addon-Einstellungsseite vor dem finalen "</form>"-Tag.
 115
 116 **'addon_settings_post'** - wird aufgerufen, wenn die Addon-Einstellungsseite geladen wird.
 117     $b ist der $_POST-Array
 118
 119 **'profile_post'** - wird aufgerufen, wenn die Profilseite angezeigt wird.
 120     $b ist der $_POST-Array
 121
 122 **'profile_edit'** - wird aufgerufen, bevor die Profil-Bearbeitungsseite angezeigt wird.
 123     $b ist ein Array
 124         'profile' => Profileintrag (Array) aus der Datenbank
 125         'entry' => die HTML-Ausgabe (string) des generierten Eintrags
 126
 127 **'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.
 128     $b ist die HTML-Ausgabe (String) des erstellten Profils
 129     (Die Details des Profil-Arrays sind in `App->profile`)
 130
 131 **'directory_item'** - wird von der Verzeichnisseite aufgerufen, wenn ein Item für die Anzeige formatiert wird.
 132     $b ist ein Array
 133         'contact' => Kontakteintrag (Array) einer Person aus der Datenbank
 134         'entry' => die HTML-Ausgabe (String) des generierten Eintrags
 135
 136 **'profile_sidebar_enter'** - wird aufgerufen, bevor die Sidebar "Kurzprofil" einer Seite erstellt wird.
 137     $b ist der Profil-Array einer Person
 138
 139 **'profile_sidebar'** - wird aufgerufen, wenn die Sidebar "Kurzprofil" einer Seite erstellt wird.
 140     $b ist ein Array
 141         'profile' => Kontakteintrag (Array) einer Person aus der Datenbank
 142         'entry' => die HTML-Ausgabe (String) des generierten Eintrags
 143
 144 **'contact_block_end'** - wird aufgerufen, wenn der Block "Kontakte/Freunde" der Profil-Sidebar komplett formatiert wurde.
 145     $b ist ein Array
 146           'contacts' => Array von "contacts"
 147           'output' => die HTML-Ausgabe (String) des Kontaktblocks
 148
 149 **'bbcode'** - wird während der Umwandlung von bbcode auf HTML aufgerufen.
 150     $b ist der konvertierte Text (String)
 151
 152 **'html2bbcode'** - wird während der Umwandlung von HTML zu bbcode aufgerufen (z.B. bei Nachrichtenbeiträgen).
 153     $b ist der konvertierte Text (String)
 154
 155 **'page_header'** - wird aufgerufen, nachdem der Bereich der Seitennavigation geladen wurde.
 156     $b ist die HTML-Ausgabe (String) der "nav"-Region
 157
 158 **'personal_xrd'** - wird aufgerufen, bevor die Ausgabe der persönlichen XRD-Datei erzeugt wird.
 159     $b ist ein Array
 160         'user' => die hinterlegten Einträge der Person
 161         'xml' => die komplette XML-Datei die ausgegeben wird
 162
 163 **'home_content'** - wird aufgerufen, bevor die Ausgabe des Homepage-Inhalts erstellt wird; wird nicht eingeloggten Nutzern angezeigt.
 164     $b ist die HTML-Ausgabe (String) der Auswahlregion
 165
 166 **'contact_edit'** - wird aufgerufen, wenn die Kontaktdetails vom Nutzer auf der "Kontakte"-Seite bearbeitet werden.
 167     $b ist ein Array
 168         'contact' => Kontakteintrag (Array) des abgezielten Kontakts
 169         'output' => die HTML-Ausgabe (String) der "Kontakt bearbeiten"-Seite
 170
 171 **'contact_edit_post'** - wird aufgerufen, wenn die "Kontakt bearbeiten"-Seite ausgegeben wird.
 172     $b ist der $_POST-Array
 173
 174 **'init_1'** - wird aufgerufen, kurz nachdem die Datenbank vor Beginn der Sitzung geöffnet wird.
 175     $b wird nicht genutzt
 176
 177 **'page_end'** - wird aufgerufen, nachdem die Funktion des HTML-Inhalts komplett abgeschlossen ist.
 178     $b ist die HTML-Ausgabe (String) vom Inhalt-"div"
 179
 180 **'avatar_lookup'** - wird aufgerufen, wenn der Avatar geladen wird.
 181     $b ist ein Array
 182         'size' => Größe des Avatars, der geladen wird
 183         'email' => Email-Adresse, um nach dem Avatar zu suchen
 184         'url' => generierte URL (String) des Avatars
 185
 186 **'nav_info'**
 187  - wird aufgerufen nachdem in include/nav,php der Inhalt des Navigations Menüs erzeugt wurde.
 188  - $b ist ein Array, das $nav wiederspiegelt.
 189
 190 Komplette Liste der Hook-Callbacks
 191 ---
 192
 193 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.
 194
 195 ### index.php
 196
 197     Hook::callAll('init_1');
 198     Hook::callAll('app_menu', $arr);
 199     Hook::callAll('page_content_top', DI::page()['content']);
 200     Hook::callAll($a->module.'_mod_init', $placeholder);
 201     Hook::callAll($a->module.'_mod_init', $placeholder);
 202     Hook::callAll($a->module.'_mod_post', $_POST);
 203     Hook::callAll($a->module.'_mod_content', $arr);
 204     Hook::callAll($a->module.'_mod_aftercontent', $arr);
 205     Hook::callAll('page_end', DI::page()['content']);
 206
 207 ### include/api.php
 208
 209     Hook::callAll('logged_in', $a->user);
 210     Hook::callAll('authenticate', $addon_auth);
 211     Hook::callAll('logged_in', $a->user);
 212
 213 ### include/enotify.php
 214
 215     Hook::callAll('enotify', $h);
 216     Hook::callAll('enotify_store', $datarray);
 217     Hook::callAll('enotify_mail', $datarray);
 218     Hook::callAll('check_item_notification', $notification_data);
 219
 220 ### src/Content/Conversation.php
 221
 222     Hook::callAll('conversation_start', $cb);
 223     Hook::callAll('render_location', $locate);
 224     Hook::callAll('display_item', $arr);
 225     Hook::callAll('display_item', $arr);
 226     Hook::callAll('item_photo_menu', $args);
 227     Hook::callAll('jot_tool', $jotplugins);
 228
 229 ### mod/directory.php
 230
 231     Hook::callAll('directory_item', $arr);
 232
 233 ### mod/xrd.php
 234
 235     Hook::callAll('personal_xrd', $arr);
 236
 237 ### mod/parse_url.php
 238
 239     Hook::callAll("parse_link", $arr);
 240
 241 ### src/Module/Delegation.php
 242
 243     Hook::callAll('home_init', $ret);
 244
 245 ### mod/acl.php
 246
 247     Hook::callAll('acl_lookup_end', $results);
 248
 249 ### mod/network.php
 250
 251     Hook::callAll('network_content_init', $arr);
 252     Hook::callAll('network_tabs', $arr);
 253
 254 ### mod/friendica.php
 255
 256     Hook::callAll('about_hook', $o);
 257
 258 ### mod/profiles.php
 259
 260     Hook::callAll('profile_post', $_POST);
 261     Hook::callAll('profile_edit', $arr);
 262
 263 ### mod/settings.php
 264
 265     Hook::callAll('addon_settings_post', $_POST);
 266     Hook::callAll('connector_settings_post', $_POST);
 267     Hook::callAll('display_settings_post', $_POST);
 268     Hook::callAll('addon_settings', $settings_addons);
 269     Hook::callAll('connector_settings', $settings_connectors);
 270     Hook::callAll('display_settings', $o);
 271
 272 ### mod/photos.php
 273
 274     Hook::callAll('photo_post_init', $_POST);
 275     Hook::callAll('photo_post_file', $ret);
 276     Hook::callAll('photo_post_end', $foo);
 277     Hook::callAll('photo_post_end', $foo);
 278     Hook::callAll('photo_post_end', $foo);
 279     Hook::callAll('photo_post_end', $foo);
 280     Hook::callAll('photo_post_end', intval($item_id));
 281     Hook::callAll('photo_upload_form', $ret);
 282
 283 ### mod/profile.php
 284
 285     Hook::callAll('profile_advanced', $o);
 286
 287 ### mod/home.php
 288
 289     Hook::callAll('home_init', $ret);
 290     Hook::callAll("home_content", $content);
 291
 292 ### mod/contacts.php
 293
 294     Hook::callAll('contact_edit_post', $_POST);
 295     Hook::callAll('contact_edit', $arr);
 296
 297 ### mod/tagger.php
 298
 299     Hook::callAll('post_local_end', $arr);
 300
 301 ### mod/uexport.php
 302
 303     Hook::callAll('uexport_options', $options);
 304
 305 ### mod/register.php
 306
 307     Hook::callAll('register_post', $arr);
 308     Hook::callAll('register_form', $arr);
 309
 310 ### mod/item.php
 311
 312     Hook::callAll('post_local_start', $_REQUEST);
 313     Hook::callAll('post_local', $datarray);
 314     Hook::callAll('post_local_end', $datarray);
 315
 316 ### src/Network/FKOAuth1.php
 317
 318     Hook::callAll('logged_in', $a->user);
 319
 320 ### src/Render/FriendicaSmartyEngine.php
 321
 322     Hook::callAll("template_vars", $arr);
 323
 324 ### src/Model/Item.php
 325
 326     Hook::callAll('detect_languages', $item);
 327     Hook::callAll('post_local', $item);
 328     Hook::callAll('post_remote', $item);
 329     Hook::callAll('post_local_end', $posted_item);
 330     Hook::callAll('post_remote_end', $posted_item);
 331     Hook::callAll('tagged', $arr);
 332     Hook::callAll('post_local_end', $new_item);
 333     Hook::callAll('put_item_in_cache', $hook_data);
 334     Hook::callAll('prepare_body_init', $item);
 335     Hook::callAll('prepare_body_content_filter', $hook_data);
 336     Hook::callAll('prepare_body', $hook_data);
 337     Hook::callAll('prepare_body_final', $hook_data);
 338
 339 ### src/Model/Contact.php
 340
 341     Hook::callAll('contact_photo_menu', $args);
 342     Hook::callAll('follow', $arr);
 343
 344 ### src/Model/Profile.php
 345
 346     Hook::callAll('profile_sidebar_enter', $profile);
 347     Hook::callAll('profile_sidebar', $arr);
 348     Hook::callAll('profile_tabs', $arr);
 349     Hook::callAll('zrl_init', $arr);
 350
 351 ### src/Model/Event.php
 352
 353     Hook::callAll('event_updated', $event['id']);
 354     Hook::callAll("event_created", $event['id']);
 355
 356 ### src/Model/User.php
 357
 358     Hook::callAll('register_account', $uid);
 359     Hook::callAll('remove_user', $user);
 360
 361 ### src/Content/ContactBlock.php
 362
 363     Hook::callAll('contact_block_end', $arr);
 364
 365 ### src/Content/Text/BBCode.php
 366
 367     Hook::callAll('bbcode', $text);
 368     Hook::callAll('bb2diaspora', $text);
 369
 370 ### src/Content/Text/HTML.php
 371
 372     Hook::callAll('html2bbcode', $message);
 373
 374 ### src/Content/Smilies.php
 375
 376     Hook::callAll('smilie', $params);
 377
 378 ### src/Content/Feature.php
 379
 380     Hook::callAll('isEnabled', $arr);
 381     Hook::callAll('get', $arr);
 382
 383 ### src/Content/ContactSelector.php
 384
 385     Hook::callAll('network_to_name', $nets);
 386
 387 ### src/Content/OEmbed.php
 388
 389     Hook::callAll('oembed_fetch_url', $embedurl, $j);
 390
 391 ### src/Content/Nav.php
 392
 393     Hook::callAll('page_header', DI::page()['nav']);
 394     Hook::callAll('nav_info', $nav);
 395
 396 ### src/Core/Authentication.php
 397
 398     Hook::callAll('logged_in', $a->user);
 399
 400 ### src/Core/Protocol.php
 401
 402     Hook::callAll('support_follow', $hook_data);
 403     Hook::callAll('support_revoke_follow', $hook_data);
 404     Hook::callAll('unfollow', $hook_data);
 405     Hook::callAll('revoke_follow', $hook_data);
 406     Hook::callAll('block', $hook_data);
 407     Hook::callAll('unblock', $hook_data);
 408     Hook::callAll('support_probe', $hook_data);
 409
 410 ### src/Core/Logger/Factory.php
 411
 412     Hook::callAll('logger_instance', $data);
 413
 414 ### src/Core/StorageManager
 415
 416     Hook::callAll('storage_instance', $data);
 417     Hook::callAll('storage_config', $data);
 418
 419 ### src/Module/Notifications/Ping.php
 420
 421     Hook::callAll('network_ping', $arr);
 422
 423 ### src/Module/PermissionTooltip.php
 424
 425     Hook::callAll('lockview_content', $item);
 426
 427 ### src/Module/Post/Edit.php
 428
 429     Hook::callAll('jot_tool', $jotplugins);
 430
 431 ### src/Worker/Directory.php
 432
 433     Hook::callAll('globaldir_update', $arr);
 434
 435 ### src/Worker/Notifier.php
 436
 437     Hook::callAll('notifier_end', $target_item);
 438
 439 ### src/Module/Login.php
 440
 441     Hook::callAll('authenticate', $addon_auth);
 442     Hook::callAll('login_hook', $o);
 443
 444 ### src/Module/Logout.php
 445
 446     Hook::callAll("logging_out");
 447
 448 ### src/Object/Post.php
 449
 450     Hook::callAll('render_location', $locate);
 451     Hook::callAll('display_item', $arr);
 452
 453 ### src/Core/ACL.php
 454
 455     Hook::callAll('contact_select_options', $x);
 456     Hook::callAll($a->module.'_pre_'.$selname, $arr);
 457     Hook::callAll($a->module.'_post_'.$selname, $o);
 458     Hook::callAll($a->module.'_pre_'.$selname, $arr);
 459     Hook::callAll($a->module.'_post_'.$selname, $o);
 460     Hook::callAll('jot_networks', $jotnets);
 461
 462 ### src/Core/Authentication.php
 463
 464     Hook::callAll('logged_in', $a->user);
 465
 466 ### src/Core/Hook.php
 467
 468     self::callSingle(self::getApp(), 'hook_fork', $fork_hook, $hookdata);
 469
 470 ### src/Core/Worker.php
 471
 472     Hook::callAll("proc_run", $arr);
 473
 474 ### src/Util/Emailer.php
 475
 476     Hook::callAll('emailer_send_prepare', $email);
 477     Hook::callAll("emailer_send", $hookdata);
 478
 479 ### src/Util/Map.php
 480
 481     Hook::callAll('generate_map', $arr);
 482     Hook::callAll('generate_named_map', $arr);
 483     Hook::callAll('Map::getCoordinates', $arr);
 484
 485 ### src/Util/Network.php
 486
 487     Hook::callAll('avatar_lookup', $avatar);
 488
 489 ### src/Util/ParseUrl.php
 490
 491     Hook::callAll("getsiteinfo", $siteinfo);
 492
 493 ### src/Protocol/DFRN.php
 494
 495     Hook::callAll('atom_feed_end', $atom);
 496     Hook::callAll('atom_feed_end', $atom);
 497
 498 ### src/Protocol/Email.php
 499
 500     Hook::callAll('email_getmessage', $message);
 501     Hook::callAll('email_getmessage_end', $ret);