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