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. Der Sprachcode ist der Array-Schlüssel, der Array-Wert ist der dezimale Wert für die Wahrscheinlichkeit.
 112         'uri-id' => Die Uri-Id des Beitrags
 113
 114 **'addon_settings'** - wird aufgerufen, wenn die HTML-Ausgabe der Addon-Einstellungsseite generiert wird.
 115     $b ist die HTML-Ausgabe (String) der Addon-Einstellungsseite vor dem finalen "</form>"-Tag.
 116
 117 **'addon_settings_post'** - wird aufgerufen, wenn die Addon-Einstellungsseite geladen wird.
 118     $b ist der $_POST-Array
 119
 120 **'profile_post'** - wird aufgerufen, wenn die Profilseite angezeigt wird.
 121     $b ist der $_POST-Array
 122
 123 **'profile_edit'** - wird aufgerufen, bevor die Profil-Bearbeitungsseite angezeigt wird.
 124     $b ist ein Array
 125         'profile' => Profileintrag (Array) aus der Datenbank
 126         'entry' => die HTML-Ausgabe (string) des generierten Eintrags
 127
 128 **'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.
 129     $b ist die HTML-Ausgabe (String) des erstellten Profils
 130     (Die Details des Profil-Arrays sind in `App->profile`)
 131
 132 **'directory_item'** - wird von der Verzeichnisseite aufgerufen, wenn ein Item für die Anzeige formatiert wird.
 133     $b ist ein Array
 134         'contact' => Kontakteintrag (Array) einer Person aus der Datenbank
 135         'entry' => die HTML-Ausgabe (String) des generierten Eintrags
 136
 137 **'profile_sidebar_enter'** - wird aufgerufen, bevor die Sidebar "Kurzprofil" einer Seite erstellt wird.
 138     $b ist der Profil-Array einer Person
 139
 140 **'profile_sidebar'** - wird aufgerufen, wenn die Sidebar "Kurzprofil" einer Seite erstellt wird.
 141     $b ist ein Array
 142         'profile' => Kontakteintrag (Array) einer Person aus der Datenbank
 143         'entry' => die HTML-Ausgabe (String) des generierten Eintrags
 144
 145 **'contact_block_end'** - wird aufgerufen, wenn der Block "Kontakte/Freunde" der Profil-Sidebar komplett formatiert wurde.
 146     $b ist ein Array
 147           'contacts' => Array von "contacts"
 148           'output' => die HTML-Ausgabe (String) des Kontaktblocks
 149
 150 **'bbcode'** - wird während der Umwandlung von bbcode auf HTML aufgerufen.
 151     $b ist der konvertierte Text (String)
 152
 153 **'html2bbcode'** - wird während der Umwandlung von HTML zu bbcode aufgerufen (z.B. bei Nachrichtenbeiträgen).
 154     $b ist der konvertierte Text (String)
 155
 156 **'page_header'** - wird aufgerufen, nachdem der Bereich der Seitennavigation geladen wurde.
 157     $b ist die HTML-Ausgabe (String) der "nav"-Region
 158
 159 **'personal_xrd'** - wird aufgerufen, bevor die Ausgabe der persönlichen XRD-Datei erzeugt wird.
 160     $b ist ein Array
 161         'user' => die hinterlegten Einträge der Person
 162         'xml' => die komplette XML-Datei die ausgegeben wird
 163
 164 **'home_content'** - wird aufgerufen, bevor die Ausgabe des Homepage-Inhalts erstellt wird; wird nicht eingeloggten Nutzern angezeigt.
 165     $b ist die HTML-Ausgabe (String) der Auswahlregion
 166
 167 **'contact_edit'** - wird aufgerufen, wenn die Kontaktdetails vom Nutzer auf der "Kontakte"-Seite bearbeitet werden.
 168     $b ist ein Array
 169         'contact' => Kontakteintrag (Array) des abgezielten Kontakts
 170         'output' => die HTML-Ausgabe (String) der "Kontakt bearbeiten"-Seite
 171
 172 **'contact_edit_post'** - wird aufgerufen, wenn die "Kontakt bearbeiten"-Seite ausgegeben wird.
 173     $b ist der $_POST-Array
 174
 175 **'init_1'** - wird aufgerufen, kurz nachdem die Datenbank vor Beginn der Sitzung geöffnet wird.
 176     $b wird nicht genutzt
 177
 178 **'page_end'** - wird aufgerufen, nachdem die Funktion des HTML-Inhalts komplett abgeschlossen ist.
 179     $b ist die HTML-Ausgabe (String) vom Inhalt-"div"
 180
 181 **'avatar_lookup'** - wird aufgerufen, wenn der Avatar geladen wird.
 182     $b ist ein Array
 183         'size' => Größe des Avatars, der geladen wird
 184         'email' => Email-Adresse, um nach dem Avatar zu suchen
 185         'url' => generierte URL (String) des Avatars
 186
 187 **'nav_info'**
 188  - wird aufgerufen nachdem in include/nav,php der Inhalt des Navigations Menüs erzeugt wurde.
 189  - $b ist ein Array, das $nav wiederspiegelt.
 190
 191 Komplette Liste der Hook-Callbacks
 192 ---
 193
 194 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.
 195
 196 ### index.php
 197
 198     Hook::callAll('init_1');
 199     Hook::callAll('app_menu', $arr);
 200     Hook::callAll('page_content_top', DI::page()['content']);
 201     Hook::callAll($a->module.'_mod_init', $placeholder);
 202     Hook::callAll($a->module.'_mod_init', $placeholder);
 203     Hook::callAll($a->module.'_mod_post', $_POST);
 204     Hook::callAll($a->module.'_mod_content', $arr);
 205     Hook::callAll($a->module.'_mod_aftercontent', $arr);
 206     Hook::callAll('page_end', DI::page()['content']);
 207
 208 ### include/api.php
 209
 210     Hook::callAll('logged_in', $a->user);
 211     Hook::callAll('authenticate', $addon_auth);
 212     Hook::callAll('logged_in', $a->user);
 213
 214 ### include/enotify.php
 215
 216     Hook::callAll('enotify', $h);
 217     Hook::callAll('enotify_store', $datarray);
 218     Hook::callAll('enotify_mail', $datarray);
 219     Hook::callAll('check_item_notification', $notification_data);
 220
 221 ### src/Content/Conversation.php
 222
 223     Hook::callAll('conversation_start', $cb);
 224     Hook::callAll('render_location', $locate);
 225     Hook::callAll('display_item', $arr);
 226     Hook::callAll('display_item', $arr);
 227     Hook::callAll('item_photo_menu', $args);
 228     Hook::callAll('jot_tool', $jotplugins);
 229
 230 ### mod/directory.php
 231
 232     Hook::callAll('directory_item', $arr);
 233
 234 ### mod/xrd.php
 235
 236     Hook::callAll('personal_xrd', $arr);
 237
 238 ### mod/parse_url.php
 239
 240     Hook::callAll("parse_link", $arr);
 241
 242 ### src/Module/Delegation.php
 243
 244     Hook::callAll('home_init', $ret);
 245
 246 ### mod/acl.php
 247
 248     Hook::callAll('acl_lookup_end', $results);
 249
 250 ### mod/network.php
 251
 252     Hook::callAll('network_content_init', $arr);
 253     Hook::callAll('network_tabs', $arr);
 254
 255 ### mod/friendica.php
 256
 257     Hook::callAll('about_hook', $o);
 258
 259 ### mod/profiles.php
 260
 261     Hook::callAll('profile_post', $_POST);
 262     Hook::callAll('profile_edit', $arr);
 263
 264 ### mod/settings.php
 265
 266     Hook::callAll('addon_settings_post', $_POST);
 267     Hook::callAll('connector_settings_post', $_POST);
 268     Hook::callAll('display_settings_post', $_POST);
 269     Hook::callAll('addon_settings', $settings_addons);
 270     Hook::callAll('connector_settings', $settings_connectors);
 271     Hook::callAll('display_settings', $o);
 272
 273 ### mod/photos.php
 274
 275     Hook::callAll('photo_post_init', $_POST);
 276     Hook::callAll('photo_post_file', $ret);
 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', $foo);
 281     Hook::callAll('photo_post_end', intval($item_id));
 282     Hook::callAll('photo_upload_form', $ret);
 283
 284 ### mod/profile.php
 285
 286     Hook::callAll('profile_advanced', $o);
 287
 288 ### mod/home.php
 289
 290     Hook::callAll('home_init', $ret);
 291     Hook::callAll("home_content", $content);
 292
 293 ### mod/contacts.php
 294
 295     Hook::callAll('contact_edit_post', $_POST);
 296     Hook::callAll('contact_edit', $arr);
 297
 298 ### mod/tagger.php
 299
 300     Hook::callAll('post_local_end', $arr);
 301
 302 ### mod/uexport.php
 303
 304     Hook::callAll('uexport_options', $options);
 305
 306 ### mod/register.php
 307
 308     Hook::callAll('register_post', $arr);
 309     Hook::callAll('register_form', $arr);
 310
 311 ### mod/item.php
 312
 313     Hook::callAll('post_local_start', $_REQUEST);
 314     Hook::callAll('post_local', $datarray);
 315     Hook::callAll('post_local_end', $datarray);
 316
 317 ### src/Network/FKOAuth1.php
 318
 319     Hook::callAll('logged_in', $a->user);
 320
 321 ### src/Render/FriendicaSmartyEngine.php
 322
 323     Hook::callAll("template_vars", $arr);
 324
 325 ### src/Model/Item.php
 326
 327     Hook::callAll('detect_languages', $item);
 328     Hook::callAll('post_local', $item);
 329     Hook::callAll('post_remote', $item);
 330     Hook::callAll('post_local_end', $posted_item);
 331     Hook::callAll('post_remote_end', $posted_item);
 332     Hook::callAll('tagged', $arr);
 333     Hook::callAll('post_local_end', $new_item);
 334     Hook::callAll('put_item_in_cache', $hook_data);
 335     Hook::callAll('prepare_body_init', $item);
 336     Hook::callAll('prepare_body_content_filter', $hook_data);
 337     Hook::callAll('prepare_body', $hook_data);
 338     Hook::callAll('prepare_body_final', $hook_data);
 339
 340 ### src/Model/Contact.php
 341
 342     Hook::callAll('contact_photo_menu', $args);
 343     Hook::callAll('follow', $arr);
 344
 345 ### src/Model/Profile.php
 346
 347     Hook::callAll('profile_sidebar_enter', $profile);
 348     Hook::callAll('profile_sidebar', $arr);
 349     Hook::callAll('profile_tabs', $arr);
 350     Hook::callAll('zrl_init', $arr);
 351
 352 ### src/Model/Event.php
 353
 354     Hook::callAll('event_updated', $event['id']);
 355     Hook::callAll("event_created", $event['id']);
 356
 357 ### src/Model/User.php
 358
 359     Hook::callAll('register_account', $uid);
 360     Hook::callAll('remove_user', $user);
 361
 362 ### src/Content/ContactBlock.php
 363
 364     Hook::callAll('contact_block_end', $arr);
 365
 366 ### src/Content/Text/BBCode.php
 367
 368     Hook::callAll('bbcode', $text);
 369     Hook::callAll('bb2diaspora', $text);
 370
 371 ### src/Content/Text/HTML.php
 372
 373     Hook::callAll('html2bbcode', $message);
 374
 375 ### src/Content/Smilies.php
 376
 377     Hook::callAll('smilie', $params);
 378
 379 ### src/Content/Feature.php
 380
 381     Hook::callAll('isEnabled', $arr);
 382     Hook::callAll('get', $arr);
 383
 384 ### src/Content/ContactSelector.php
 385
 386     Hook::callAll('network_to_name', $nets);
 387
 388 ### src/Content/OEmbed.php
 389
 390     Hook::callAll('oembed_fetch_url', $embedurl, $j);
 391
 392 ### src/Content/Nav.php
 393
 394     Hook::callAll('page_header', DI::page()['nav']);
 395     Hook::callAll('nav_info', $nav);
 396
 397 ### src/Core/Authentication.php
 398
 399     Hook::callAll('logged_in', $a->user);
 400
 401 ### src/Core/Protocol.php
 402
 403     Hook::callAll('support_follow', $hook_data);
 404     Hook::callAll('support_revoke_follow', $hook_data);
 405     Hook::callAll('unfollow', $hook_data);
 406     Hook::callAll('revoke_follow', $hook_data);
 407     Hook::callAll('block', $hook_data);
 408     Hook::callAll('unblock', $hook_data);
 409     Hook::callAll('support_probe', $hook_data);
 410
 411 ### src/Core/Logger/Factory.php
 412
 413     Hook::callAll('logger_instance', $data);
 414
 415 ### src/Core/StorageManager
 416
 417     Hook::callAll('storage_instance', $data);
 418     Hook::callAll('storage_config', $data);
 419
 420 ### src/Module/Notifications/Ping.php
 421
 422     Hook::callAll('network_ping', $arr);
 423
 424 ### src/Module/PermissionTooltip.php
 425
 426     Hook::callAll('lockview_content', $item);
 427
 428 ### src/Module/Post/Edit.php
 429
 430     Hook::callAll('jot_tool', $jotplugins);
 431
 432 ### src/Worker/Directory.php
 433
 434     Hook::callAll('globaldir_update', $arr);
 435
 436 ### src/Worker/Notifier.php
 437
 438     Hook::callAll('notifier_end', $target_item);
 439
 440 ### src/Module/Login.php
 441
 442     Hook::callAll('authenticate', $addon_auth);
 443     Hook::callAll('login_hook', $o);
 444
 445 ### src/Module/Logout.php
 446
 447     Hook::callAll("logging_out");
 448
 449 ### src/Object/Post.php
 450
 451     Hook::callAll('render_location', $locate);
 452     Hook::callAll('display_item', $arr);
 453
 454 ### src/Core/ACL.php
 455
 456     Hook::callAll('contact_select_options', $x);
 457     Hook::callAll($a->module.'_pre_'.$selname, $arr);
 458     Hook::callAll($a->module.'_post_'.$selname, $o);
 459     Hook::callAll($a->module.'_pre_'.$selname, $arr);
 460     Hook::callAll($a->module.'_post_'.$selname, $o);
 461     Hook::callAll('jot_networks', $jotnets);
 462
 463 ### src/Core/Authentication.php
 464
 465     Hook::callAll('logged_in', $a->user);
 466
 467 ### src/Core/Hook.php
 468
 469     self::callSingle(self::getApp(), 'hook_fork', $fork_hook, $hookdata);
 470
 471 ### src/Core/Worker.php
 472
 473     Hook::callAll("proc_run", $arr);
 474
 475 ### src/Util/Emailer.php
 476
 477     Hook::callAll('emailer_send_prepare', $email);
 478     Hook::callAll("emailer_send", $hookdata);
 479
 480 ### src/Util/Map.php
 481
 482     Hook::callAll('generate_map', $arr);
 483     Hook::callAll('generate_named_map', $arr);
 484     Hook::callAll('Map::getCoordinates', $arr);
 485
 486 ### src/Util/Network.php
 487
 488     Hook::callAll('avatar_lookup', $avatar);
 489
 490 ### src/Util/ParseUrl.php
 491
 492     Hook::callAll("getsiteinfo", $siteinfo);
 493
 494 ### src/Protocol/DFRN.php
 495
 496     Hook::callAll('atom_feed_end', $atom);
 497     Hook::callAll('atom_feed_end', $atom);
 498
 499 ### src/Protocol/Email.php
 500
 501     Hook::callAll('email_getmessage', $message);
 502     Hook::callAll('email_getmessage_end', $ret);