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