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