Improved documentation formatting (of Plugins.md)
This commit is contained in:
Andrej Stieben
parent
4d0778bfe1
commit
acefb84681
2 changed files with 92 additions and 84 deletions
101
doc/Plugins.md
101
doc/Plugins.md
|
|
@ -1,5 +1,7 @@
|
|||
Friendica Addon/Plugin development
|
||||
==========================
|
||||
==============
|
||||
|
||||
* [Home](help)
|
||||
|
||||
Please see the sample addon 'randplace' for a working example of using some of these features.
|
||||
Addons work by intercepting event hooks - which must be registered.
|
||||
|
|
@ -16,12 +18,12 @@ Future extensions may provide for "setup" amd "remove".
|
|||
|
||||
Plugins should contain a comment block with the four following parameters:
|
||||
|
||||
/*
|
||||
* Name: My Great Plugin
|
||||
* Description: This is what my plugin does. It's really cool
|
||||
* Version: 1.0
|
||||
* Author: John Q. Public <john@myfriendicasite.com>
|
||||
*/
|
||||
/*
|
||||
* Name: My Great Plugin
|
||||
* Description: This is what my plugin does. It's really cool.
|
||||
* Version: 1.0
|
||||
* Author: John Q. Public <john@myfriendicasite.com>
|
||||
*/
|
||||
|
||||
Register your plugin hooks during installation.
|
||||
|
||||
|
|
@ -45,7 +47,7 @@ Your hook callback functions will be called with at least one and possibly two a
|
|||
|
||||
If you wish to make changes to the calling data, you must declare them as reference variables (with '&') during function declaration.
|
||||
|
||||
###$a
|
||||
#### $a
|
||||
$a is the Friendica 'App' class.
|
||||
It contains a wealth of information about the current state of Friendica:
|
||||
|
||||
|
|
@ -56,13 +58,13 @@ It contains a wealth of information about the current state of Friendica:
|
|||
|
||||
It is recommeded you call this '$a' to match its usage elsewhere.
|
||||
|
||||
###$b
|
||||
#### $b
|
||||
$b can be called anything you like.
|
||||
This is information specific to the hook currently being processed, and generally contains information that is being immediately processed or acted on that you can use, display, or alter.
|
||||
Remember to declare it with '&' if you wish to alter it.
|
||||
|
||||
Modules
|
||||
--------
|
||||
---
|
||||
|
||||
Plugins/addons may also act as "modules" and intercept all page requests for a given URL path.
|
||||
In order for a plugin to act as a module it needs to define a function "plugin_name_module()" which takes no arguments and needs not do anything.
|
||||
|
|
@ -72,15 +74,15 @@ These are parsed into an array $a->argv, with a corresponding $a->argc indicatin
|
|||
So http://my.web.site/plugin/arg1/arg2 would look for a module named "plugin" and pass its module functions the $a App structure (which is available to many components).
|
||||
This will include:
|
||||
|
||||
$a->argc = 3
|
||||
$a->argv = array(0 => 'plugin', 1 => 'arg1', 2 => 'arg2');
|
||||
$a->argc = 3
|
||||
$a->argv = array(0 => 'plugin', 1 => 'arg1', 2 => 'arg2');
|
||||
|
||||
Your module functions will often contain the function plugin_name_content(&$a), which defines and returns the page body content.
|
||||
They may also contain plugin_name_post(&$a) which is called before the _content function and typically handles the results of POST forms.
|
||||
You may also have plugin_name_init(&$a) which is called very early on and often does module initialisation.
|
||||
|
||||
Templates
|
||||
----------
|
||||
---
|
||||
|
||||
If your plugin needs some template, you can use the Friendica template system.
|
||||
Friendica uses [smarty3](http://www.smarty.net/) as a template engine.
|
||||
|
|
@ -104,140 +106,140 @@ See also the wiki page [Quick Template Guide](https://github.com/friendica/frien
|
|||
Current hooks
|
||||
-------------
|
||||
|
||||
###'authenticate'
|
||||
### 'authenticate'
|
||||
'authenticate' is called when a user attempts to login.
|
||||
$b is an array containing:
|
||||
|
||||
'username' => the supplied username
|
||||
'password' => the supplied password
|
||||
'username' => the supplied username
|
||||
'password' => the supplied password
|
||||
'authenticated' => set this to non-zero to authenticate the user.
|
||||
'user_record' => successful authentication must also return a valid user record from the database
|
||||
|
||||
###'logged_in'
|
||||
### 'logged_in'
|
||||
'logged_in' is called after a user has successfully logged in.
|
||||
$b contains the $a->user array.
|
||||
|
||||
###'display_item'
|
||||
### 'display_item'
|
||||
'display_item' is called when formatting a post for display.
|
||||
$b is an array:
|
||||
|
||||
'item' => The item (array) details pulled from the database
|
||||
'output' => the (string) HTML representation of this item prior to adding it to the page
|
||||
|
||||
###'post_local'
|
||||
### 'post_local'
|
||||
* called when a status post or comment is entered on the local system
|
||||
* $b is the item array of the information to be stored in the database
|
||||
* Please note: body contents are bbcode - not HTML
|
||||
|
||||
###'post_local_end'
|
||||
### 'post_local_end'
|
||||
* called when a local status post or comment has been stored on the local system
|
||||
* $b is the item array of the information which has just been stored in the database
|
||||
* Please note: body contents are bbcode - not HTML
|
||||
|
||||
###'post_remote'
|
||||
### 'post_remote'
|
||||
* called when receiving a post from another source. This may also be used to post local activity or system generated messages.
|
||||
* $b is the item array of information to be stored in the database and the item body is bbcode.
|
||||
|
||||
###'settings_form'
|
||||
### 'settings_form'
|
||||
* called when generating the HTML for the user Settings page
|
||||
* $b is the (string) HTML of the settings page before the final '</form>' tag.
|
||||
|
||||
###'settings_post'
|
||||
### 'settings_post'
|
||||
* called when the Settings pages are submitted
|
||||
* $b is the $_POST array
|
||||
|
||||
###'plugin_settings'
|
||||
### 'plugin_settings'
|
||||
* called when generating the HTML for the addon settings page
|
||||
* $b is the (string) HTML of the addon settings page before the final '</form>' tag.
|
||||
|
||||
###'plugin_settings_post'
|
||||
### 'plugin_settings_post'
|
||||
* called when the Addon Settings pages are submitted
|
||||
* $b is the $_POST array
|
||||
|
||||
###'profile_post'
|
||||
### 'profile_post'
|
||||
* called when posting a profile page
|
||||
* $b is the $_POST array
|
||||
|
||||
###'profile_edit'
|
||||
### 'profile_edit'
|
||||
'profile_edit' is called prior to output of profile edit page.
|
||||
$b is an array containing:
|
||||
|
||||
'profile' => profile (array) record from the database
|
||||
'entry' => the (string) HTML of the generated entry
|
||||
|
||||
###'profile_advanced'
|
||||
### 'profile_advanced'
|
||||
* called when the HTML is generated for the 'Advanced profile', corresponding to the 'Profile' tab within a person's profile page
|
||||
* $b is the (string) HTML representation of the generated profile
|
||||
* The profile array details are in $a->profile.
|
||||
|
||||
###'directory_item'
|
||||
### 'directory_item'
|
||||
'directory_item' is called from the Directory page when formatting an item for display.
|
||||
$b is an array:
|
||||
|
||||
'contact' => contact (array) record for the person from the database
|
||||
'entry' => the (string) HTML of the generated entry
|
||||
|
||||
###'profile_sidebar_enter'
|
||||
### 'profile_sidebar_enter'
|
||||
* called prior to generating the sidebar "short" profile for a page
|
||||
* $b is the person's profile array
|
||||
|
||||
###'profile_sidebar'
|
||||
### 'profile_sidebar'
|
||||
'profile_sidebar is called when generating the sidebar "short" profile for a page.
|
||||
$b is an array:
|
||||
|
||||
'profile' => profile (array) record for the person from the database
|
||||
'entry' => the (string) HTML of the generated entry
|
||||
|
||||
###'contact_block_end'
|
||||
### 'contact_block_end'
|
||||
is called when formatting the block of contacts/friends on a profile sidebar has completed.
|
||||
$b is an array:
|
||||
|
||||
'contacts' => array of contacts
|
||||
'output' => the (string) generated HTML of the contact block
|
||||
|
||||
###'bbcode'
|
||||
### 'bbcode'
|
||||
* called during conversion of bbcode to html
|
||||
* $b is a string converted text
|
||||
|
||||
###'html2bbcode'
|
||||
### 'html2bbcode'
|
||||
* called during conversion of html to bbcode (e.g. remote message posting)
|
||||
* $b is a string converted text
|
||||
|
||||
###'page_header'
|
||||
### 'page_header'
|
||||
* called after building the page navigation section
|
||||
* $b is a string HTML of nav region
|
||||
|
||||
###'personal_xrd'
|
||||
### 'personal_xrd'
|
||||
'personal_xrd' is called prior to output of personal XRD file.
|
||||
$b is an array:
|
||||
|
||||
'user' => the user record for the person
|
||||
'xml' => the complete XML to be output
|
||||
|
||||
###'home_content'
|
||||
### 'home_content'
|
||||
* called prior to output home page content, shown to unlogged users
|
||||
* $b is (string) HTML of section region
|
||||
|
||||
###'contact_edit'
|
||||
### 'contact_edit'
|
||||
is called when editing contact details on an individual from the Contacts page.
|
||||
$b is an array:
|
||||
|
||||
'contact' => contact record (array) of target contact
|
||||
'output' => the (string) generated HTML of the contact edit page
|
||||
|
||||
###'contact_edit_post'
|
||||
### 'contact_edit_post'
|
||||
* called when posting the contact edit page.
|
||||
* $b is the $_POST array
|
||||
|
||||
###'init_1'
|
||||
### 'init_1'
|
||||
* called just after DB has been opened and before session start
|
||||
* $b is not used or passed
|
||||
|
||||
###'page_end'
|
||||
### 'page_end'
|
||||
* called after HTML content functions have completed
|
||||
* $b is (string) HTML of content div
|
||||
|
||||
###'avatar_lookup'
|
||||
### 'avatar_lookup'
|
||||
'avatar_lookup' is called when looking up the avatar.
|
||||
$b is an array:
|
||||
|
||||
|
|
@ -245,11 +247,11 @@ $b is an array:
|
|||
'email' => email to look up the avatar for
|
||||
'url' => the (string) generated URL of the avatar
|
||||
|
||||
###'emailer_send_prepare'
|
||||
### 'emailer_send_prepare'
|
||||
'emailer_send_prepare' called from Emailer::send() before building the mime message.
|
||||
$b is an array, params to Emailer::send()
|
||||
|
||||
'fromName' => name of the sender
|
||||
'fromName' => name of the sender
|
||||
'fromEmail' => email fo the sender
|
||||
'replyTo' => replyTo address to direct responses
|
||||
'toEmail' => destination email address
|
||||
|
|
@ -258,20 +260,20 @@ $b is an array, params to Emailer::send()
|
|||
'textVersion' => text only version of the message
|
||||
'additionalMailHeader' => additions to the smtp mail header
|
||||
|
||||
###'emailer_send'
|
||||
### 'emailer_send'
|
||||
is called before calling PHP's mail().
|
||||
$b is an array, params to mail()
|
||||
|
||||
'to'
|
||||
'subject'
|
||||
'to'
|
||||
'subject'
|
||||
'body'
|
||||
'headers'
|
||||
|
||||
###'nav_info'
|
||||
### 'nav_info'
|
||||
is called after the navigational menu is build in include/nav.php.
|
||||
$b is an array containing $nav from nav.php.
|
||||
|
||||
###'template_vars'
|
||||
### 'template_vars'
|
||||
is called before vars are passed to the template engine to render the page.
|
||||
The registered function can add,change or remove variables passed to template.
|
||||
$b is an array with:
|
||||
|
|
@ -463,4 +465,3 @@ mod/cb.php: call_hooks('cb_afterpost');
|
|||
mod/cb.php: call_hooks('cb_content', $o);
|
||||
|
||||
mod/directory.php: call_hooks('directory_item', $arr);
|
||||
|
||||
|
|
|
|||
|
|
@ -1,27 +1,27 @@
|
|||
**Friendica Addon/Plugin-Entwicklung**
|
||||
Friendica Addon/Plugin-Entwicklung
|
||||
==============
|
||||
|
||||
* [Zur Startseite der Hilfe](help)
|
||||
|
||||
Bitte schau dir das Beispiel-Addon "randplace" für ein funktionierendes Beispiel für manche der hier aufgeführten Funktionen an.
|
||||
Das Facebook-Addon bietet ein Beispiel dafür, die "addon"- und "module"-Funktion gemeinsam zu integrieren.
|
||||
Addons arbeiten, indem sie Event Hooks abfangen. Module arbeiten, indem bestimmte Seitenanfragen (durch den URL-Pfad) abgefangen werden
|
||||
Bitte schau dir das Beispiel-Addon "randplace" für ein funktionierendes Beispiel für manche der hier aufgeführten Funktionen an.
|
||||
Das Facebook-Addon bietet ein Beispiel dafür, die "addon"- und "module"-Funktion gemeinsam zu integrieren.
|
||||
Addons arbeiten, indem sie Event Hooks abfangen. Module arbeiten, indem bestimmte Seitenanfragen (durch den URL-Pfad) abgefangen werden
|
||||
|
||||
Plugin-Namen können keine Leerstellen oder andere Interpunktionen enthalten und werden als Datei- und Funktionsnamen genutzt.
|
||||
Du kannst einen lesbaren Namen im Kommentarblock eintragen.
|
||||
Jedes Addon muss beides beinhalten - eine Installations- und eine Deinstallationsfunktion, die auf dem Addon-/Plugin-Namen basieren; z.B. "plugin1name_install()".
|
||||
Diese beiden Funktionen haben keine Argumente und sind dafür verantwortlich, Event Hooks zu registrieren und abzumelden (unregistering), die dein Plugin benötigt.
|
||||
Die Installations- und Deinstallationsfunktionfunktionen werden auch ausgeführt (z.B. neu installiert), wenn sich das Plugin nach der Installation ändert - somit sollte deine Deinstallationsfunktion keine Daten zerstört und deine Installationsfunktion sollte bestehende Daten berücksichtigen.
|
||||
Plugin-Namen können keine Leerstellen oder andere Interpunktionen enthalten und werden als Datei- und Funktionsnamen genutzt.
|
||||
Du kannst einen lesbaren Namen im Kommentarblock eintragen.
|
||||
Jedes Addon muss beides beinhalten - eine Installations- und eine Deinstallationsfunktion, die auf dem Addon-/Plugin-Namen basieren; z.B. "plugin1name_install()".
|
||||
Diese beiden Funktionen haben keine Argumente und sind dafür verantwortlich, Event Hooks zu registrieren und abzumelden (unregistering), die dein Plugin benötigt.
|
||||
Die Installations- und Deinstallationsfunktionfunktionen werden auch ausgeführt (z.B. neu installiert), wenn sich das Plugin nach der Installation ändert - somit sollte deine Deinstallationsfunktion keine Daten zerstört und deine Installationsfunktion sollte bestehende Daten berücksichtigen.
|
||||
Zukünftige Extensions werden möglicherweise "Setup" und "Entfernen" anbieten.
|
||||
|
||||
Plugins sollten einen Kommentarblock mit den folgenden vier Parametern enthalten:
|
||||
|
||||
/*
|
||||
* Name: My Great Plugin
|
||||
* Description: This is what my plugin does. It's really cool
|
||||
* Version: 1.0
|
||||
* Author: John Q. Public <john@myfriendicasite.com>
|
||||
*/
|
||||
/*
|
||||
* Name: My Great Plugin
|
||||
* Description: This is what my plugin does. It's really cool
|
||||
* Version: 1.0
|
||||
* Author: John Q. Public <john@myfriendicasite.com>
|
||||
*/
|
||||
|
||||
Registriere deine Plugin-Hooks während der Installation.
|
||||
|
||||
|
|
@ -29,45 +29,50 @@ Registriere deine Plugin-Hooks während der Installation.
|
|||
|
||||
$hookname ist ein String und entspricht einem bekannten Friendica-Hook.
|
||||
|
||||
$file steht für den Pfadnamen, der relativ zum Top-Level-Friendicaverzeichnis liegt.
|
||||
$file steht für den Pfadnamen, der relativ zum Top-Level-Friendicaverzeichnis liegt.
|
||||
Das *sollte* "addon/plugin_name/plugin_name.php' sein.
|
||||
|
||||
$function ist ein String und der Name der Funktion, die ausgeführt wird, wenn der Hook aufgerufen wird.
|
||||
|
||||
Argumente
|
||||
---
|
||||
|
||||
Deine Hook-Callback-Funktion wird mit mindestens einem und bis zu zwei Argumenten aufgerufen
|
||||
|
||||
function myhook_function(&$a, &$b) {
|
||||
|
||||
}
|
||||
|
||||
Wenn du Änderungen an den aufgerufenen Daten vornehmen willst, musst du diese als Referenzvariable (mit "&") während der Funktionsdeklaration deklarieren.
|
||||
Wenn du Änderungen an den aufgerufenen Daten vornehmen willst, musst du diese als Referenzvariable (mit "&") während der Funktionsdeklaration deklarieren.
|
||||
|
||||
$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.
|
||||
Es ist empfohlen, diese Funktion "$a" zu nennen, um seine Nutzung an den Gebrauch an anderer Stelle anzugleichen.
|
||||
$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.
|
||||
Es ist empfohlen, diese Funktion "$a" zu nennen, um seine Nutzung an den Gebrauch an anderer Stelle anzugleichen.
|
||||
|
||||
$b kann frei benannt werden.
|
||||
Diese Information ist speziell auf den Hook bezogen, der aktuell bearbeitet wird, und beinhaltet normalerweise Daten, die du sofort nutzen, anzeigen oder bearbeiten kannst.
|
||||
Achte darauf, diese mit "&" zu deklarieren, wenn du sie bearbeiten willst.
|
||||
$b kann frei benannt werden.
|
||||
Diese Information ist speziell auf den Hook bezogen, der aktuell bearbeitet wird, und beinhaltet normalerweise Daten, die du sofort nutzen, anzeigen oder bearbeiten kannst.
|
||||
Achte darauf, diese mit "&" zu deklarieren, wenn du sie bearbeiten willst.
|
||||
|
||||
|
||||
**Module**
|
||||
Module
|
||||
---
|
||||
|
||||
Plugins/Addons können auch als "Module" agieren und alle Seitenanfragen für eine bestimte URL abfangen.
|
||||
Um ein Plugin als Modul zu nutzen, ist es nötig, die Funktion "plugin_name_module()" zu definieren, die keine Argumente benötigt und nichts weiter machen muss.
|
||||
Plugins/Addons können auch als "Module" agieren und alle Seitenanfragen für eine bestimte URL abfangen.
|
||||
Um ein Plugin als Modul zu nutzen, ist es nötig, die Funktion "plugin_name_module()" zu definieren, die keine Argumente benötigt und nichts weiter machen muss.
|
||||
|
||||
Wenn diese Funktion existiert, wirst du nun alle Seitenanfragen für "http://my.web.site/plugin_name" erhalten - mit allen URL-Komponenten als zusätzliche Argumente.
|
||||
Diese werden in ein Array $a->argv geparst und stimmen mit $a->argc überein, wobei sie die Anzahl der URL-Komponenten abbilden.
|
||||
Wenn diese Funktion existiert, wirst du nun alle Seitenanfragen für "http://my.web.site/plugin_name" erhalten - mit allen URL-Komponenten als zusätzliche Argumente.
|
||||
Diese werden in ein Array $a->argv geparst und stimmen mit $a->argc überein, wobei sie die Anzahl der URL-Komponenten abbilden.
|
||||
So würde http://my.web.site/plugin/arg1/arg2 nach einem Modul "plugin" suchen und seiner Modulfunktion die $a-App-Strukur übergeben (dies ist für viele Komponenten verfügbar). Das umfasst:
|
||||
|
||||
$a->argc = 3
|
||||
$a->argv = array(0 => 'plugin', 1 => 'arg1', 2 => 'arg2');
|
||||
$a->argc = 3
|
||||
$a->argv = array(0 => 'plugin', 1 => 'arg1', 2 => 'arg2');
|
||||
|
||||
Deine Modulfunktionen umfassen oft die Funktion plugin_name_content(&$a), welche den Seiteninhalt definiert und zurückgibt.
|
||||
Sie können auch plugin_name_post(&$a) umfassen, welches vor der content-Funktion aufgerufen wird und normalerweise die Resultate der POST-Formulare handhabt.
|
||||
Deine Modulfunktionen umfassen oft die Funktion plugin_name_content(&$a), welche den Seiteninhalt definiert und zurückgibt.
|
||||
Sie können auch plugin_name_post(&$a) umfassen, welches vor der content-Funktion aufgerufen wird und normalerweise die Resultate der POST-Formulare handhabt.
|
||||
Du kannst ebenso plugin_name_init(&$a) nutzen, was oft frühzeitig aufgerufen wird und das Modul initialisert.
|
||||
|
||||
|
||||
**Derzeitige Hooks:**
|
||||
Derzeitige Hooks
|
||||
---
|
||||
|
||||
**'authenticate'** - wird aufgerufen, wenn sich der User einloggt.
|
||||
$b ist ein Array
|
||||
|
|
@ -180,6 +185,9 @@ Du kannst ebenso plugin_name_init(&$a) nutzen, was oft frühzeitig aufgerufen wi
|
|||
- wird aufgerufen nachdem in include/nav,php der Inhalt des Navigations Menüs erzeugt wurde.
|
||||
- $b ist ein Array, das $nav wiederspiegelt.
|
||||
|
||||
Komplette Liste der Hook-Callbacks
|
||||
---
|
||||
|
||||
Eine komplette Liste aller Hook-Callbacks mit den zugehörigen Dateien (am 14-Feb-2012 generiert): Bitte schau in die Quellcodes für Details zu Hooks, die oben nicht dokumentiert sind.
|
||||
|
||||
boot.php: call_hooks('login_hook',$o);
|
||||
|
|
@ -204,7 +212,7 @@ include/text.php: call_hooks('contact_block_end', $arr);
|
|||
|
||||
include/text.php: call_hooks('smilie', $s);
|
||||
|
||||
include/text.php: call_hooks('prepare_body_init', $item);
|
||||
include/text.php: call_hooks('prepare_body_init', $item);
|
||||
|
||||
include/text.php: call_hooks('prepare_body', $prep_arr);
|
||||
|
||||
|
|
@ -359,4 +367,3 @@ mod/cb.php: call_hooks('cb_afterpost');
|
|||
mod/cb.php: call_hooks('cb_content', $o);
|
||||
|
||||
mod/directory.php: call_hooks('directory_item', $arr);
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue