mirror of
https://github.com/friendica/friendica
synced 2024-11-09 16:22:56 +00:00
Improve Addons documentation
This commit is contained in:
Hypolite Petovan
parent
ffc8b2a79a
commit
796056a6fe
1 changed files with 231 additions and 217 deletions
448
doc/Addons.md
448
doc/Addons.md
|
|
@ -28,8 +28,7 @@ Addons should contain a comment block with the four following parameters:
|
|||
Please also add a README or README.md file to the addon directory.
|
||||
It will be displayed in the admin panel and should include some further information in addition to the header information.
|
||||
|
||||
PHP addon hooks
|
||||
---
|
||||
## PHP addon hooks
|
||||
|
||||
Register your addon hooks during installation.
|
||||
|
||||
|
|
@ -42,7 +41,7 @@ This *should* be 'addon/*addon_name*/*addon_name*.php' in most cases.
|
|||
|
||||
$function is a string and is the name of the function which will be executed when the hook is called.
|
||||
|
||||
#### Arguments
|
||||
### Arguments
|
||||
Your hook callback functions will be called with at least one and possibly two arguments
|
||||
|
||||
function myhook_function(App $a, &$b) {
|
||||
|
|
@ -50,10 +49,10 @@ 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.
|
||||
If you wish to make changes to the calling data, you must declare them as reference variables (with `&`) during function declaration.
|
||||
|
||||
##### $a
|
||||
$a is the Friendica 'App' class.
|
||||
#### $a
|
||||
$a is the Friendica `App` class.
|
||||
It contains a wealth of information about the current state of Friendica:
|
||||
|
||||
* which module has been called,
|
||||
|
|
@ -61,54 +60,64 @@ It contains a wealth of information about the current state of Friendica:
|
|||
* the page contents at the point the hook was invoked,
|
||||
* profile and user information, etc.
|
||||
|
||||
It is recommeded you call this '$a' to match its usage elsewhere.
|
||||
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.
|
||||
Remember to declare it with `&` if you wish to alter it.
|
||||
|
||||
JavaScript addon hooks
|
||||
---
|
||||
## JavaScript addon hooks
|
||||
|
||||
### PHP part
|
||||
|
||||
#### PHP part
|
||||
Make sure your JavaScript addon file (addon/*addon_name*/*addon_name*.js) is listed in the document response.
|
||||
|
||||
In your addon install function, add:
|
||||
|
||||
Addon::registerHook('template_vars', 'addon/<addon_name>/<addon_name>.php', '<addon_name>_template_vars');
|
||||
```php
|
||||
Addon::registerHook('template_vars', __FILE__, '<addon_name>_template_vars');
|
||||
```
|
||||
|
||||
In your addon uninstall function, add:
|
||||
|
||||
Addon::unregisterHook('template_vars', 'addon/<addon_name>/<addon_name>.php', '<addon_name>_template_vars');
|
||||
```php
|
||||
Addon::unregisterHook('template_vars', __FILE__, '<addon_name>_template_vars');
|
||||
```
|
||||
|
||||
Then, add your addon name to the *addon_hooks* template variable array:
|
||||
|
||||
function <addon_name>_template_vars($a, &$arr)
|
||||
{
|
||||
if (!array_key_exists('addon_hooks',$arr['vars']))
|
||||
{
|
||||
$arr['vars']['addon_hooks'] = array();
|
||||
}
|
||||
$arr['vars']['addon_hooks'][] = "<addon_name>";
|
||||
}
|
||||
```php
|
||||
function <addon_name>_template_vars($a, &$arr)
|
||||
{
|
||||
if (!array_key_exists('addon_hooks', $arr['vars']))
|
||||
{
|
||||
$arr['vars']['addon_hooks'] = array();
|
||||
}
|
||||
$arr['vars']['addon_hooks'][] = "<addon_name>";
|
||||
}
|
||||
```
|
||||
|
||||
#### JavaScript part
|
||||
Register your addon hooks in file 'addon/*addon_name*/*addon_name*.js'.
|
||||
### JavaScript part
|
||||
|
||||
Addon_registerHook(type,hookfnstr);
|
||||
Register your addon hooks in file `addon/*addon_name*/*addon_name*.js`.
|
||||
|
||||
```js
|
||||
Addon_registerHook(type, hookfnstr);
|
||||
```
|
||||
|
||||
*type* is the name of the hook and corresponds to a known Friendica JavaScript hook.
|
||||
*hookfnstr* is the name of your JavaScript function to execute.
|
||||
|
||||
No arguments are provided to your JavaScript callback function. Example:
|
||||
|
||||
function myhook_function() {
|
||||
```javascript
|
||||
function myhook_function() {
|
||||
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Modules
|
||||
---
|
||||
## Modules
|
||||
|
||||
Addons may also act as "modules" and intercept all page requests for a given URL path.
|
||||
In order for a addon to act as a module it needs to define a function "addon_name_module()" which takes no arguments and needs not do anything.
|
||||
|
|
@ -118,15 +127,16 @@ These are parsed into an array $a->argv, with a corresponding $a->argc indicatin
|
|||
So http://my.web.site/addon/arg1/arg2 would look for a module named "addon" 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 => 'addon', 1 => 'arg1', 2 => 'arg2');
|
||||
```php
|
||||
$a->argc = 3
|
||||
$a->argv = array(0 => 'addon', 1 => 'arg1', 2 => 'arg2');
|
||||
```
|
||||
|
||||
Your module functions will often contain the function addon_name_content(App $a), which defines and returns the page body content.
|
||||
They may also contain addon_name_post(App $a) which is called before the _content function and typically handles the results of POST forms.
|
||||
You may also have addon_name_init(App $a) which is called very early on and often does module initialisation.
|
||||
|
||||
Templates
|
||||
---
|
||||
## Templates
|
||||
|
||||
If your addon needs some template, you can use the Friendica template system.
|
||||
Friendica uses [smarty3](http://www.smarty.net/) as a template engine.
|
||||
|
|
@ -135,249 +145,253 @@ Put your tpl files in the *templates/* subfolder of your addon.
|
|||
|
||||
In your code, like in the function addon_name_content(), load the template file and execute it passing needed values:
|
||||
|
||||
# load template file. first argument is the template name,
|
||||
# second is the addon path relative to friendica top folder
|
||||
$tpl = get_markup_template('mytemplate.tpl', 'addon/addon_name/');
|
||||
```php
|
||||
# load template file. first argument is the template name,
|
||||
# second is the addon path relative to friendica top folder
|
||||
$tpl = get_markup_template('mytemplate.tpl', 'addon/addon_name/');
|
||||
|
||||
# apply template. first argument is the loaded template,
|
||||
# second an array of 'name'=>'values' to pass to template
|
||||
$output = replace_macros($tpl,array(
|
||||
'title' => 'My beautiful addon',
|
||||
));
|
||||
# apply template. first argument is the loaded template,
|
||||
# second an array of 'name' => 'values' to pass to template
|
||||
$output = replace_macros($tpl, array(
|
||||
'title' => 'My beautiful addon',
|
||||
));
|
||||
```
|
||||
|
||||
See also the wiki page [Quick Template Guide](https://github.com/friendica/friendica/wiki/Quick-Template-Guide).
|
||||
|
||||
Current PHP hooks
|
||||
-------------
|
||||
## Current PHP hooks
|
||||
|
||||
### 'authenticate'
|
||||
'authenticate' is called when a user attempts to login.
|
||||
$b is an array containing:
|
||||
### authenticate
|
||||
Called when a user attempts to login.
|
||||
`$b` is an array containing:
|
||||
|
||||
'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
|
||||
- **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' is called after a user has successfully logged in.
|
||||
$b contains the $a->user array.
|
||||
### logged_in
|
||||
Called after a user has successfully logged in.
|
||||
`$b` contains the `$a->user` array.
|
||||
|
||||
### 'display_item'
|
||||
'display_item' is called when formatting a post for display.
|
||||
### display_item
|
||||
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
|
||||
- **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'
|
||||
* 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
|
||||
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'
|
||||
* 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_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'
|
||||
* 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.
|
||||
### 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'
|
||||
* 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_form
|
||||
Called when generating the HTML for the user Settings page.
|
||||
`$b` is the HTML string of the settings page before the final `</form>` tag.
|
||||
|
||||
### 'settings_post'
|
||||
* called when the Settings pages are submitted
|
||||
* $b is the $_POST array
|
||||
### settings_post
|
||||
Called when the Settings pages are submitted.
|
||||
`$b` is the $_POST array.
|
||||
|
||||
### 'addon_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.
|
||||
### addon_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.
|
||||
|
||||
### 'addon_settings_post'
|
||||
* called when the Addon Settings pages are submitted
|
||||
* $b is the $_POST array
|
||||
### addon_settings_post
|
||||
Called when the Addon Settings pages are submitted.
|
||||
`$b` is the $_POST array.
|
||||
|
||||
### 'profile_post'
|
||||
* called when posting a profile page
|
||||
* $b is the $_POST array
|
||||
### profile_post
|
||||
Called when posting a profile page.
|
||||
`$b` is the $_POST array.
|
||||
|
||||
### 'profile_edit'
|
||||
'profile_edit' is called prior to output of profile edit page.
|
||||
$b is an array containing:
|
||||
### profile_edit
|
||||
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**: profile (array) record from the database
|
||||
- **entry**: the (string) HTML of the generated entry
|
||||
|
||||
### '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.
|
||||
### 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 HTML string representation of the generated profile.
|
||||
The profile array details are in `$a->profile`.
|
||||
|
||||
### 'directory_item'
|
||||
'directory_item' is called from the Directory page when formatting an item for display.
|
||||
### directory_item
|
||||
Called from the Directory page when formatting an item for display.
|
||||
`$b` is an array:
|
||||
|
||||
- **contact**: contact record array for the person from the database
|
||||
- **entry**: the HTML string of the generated entry
|
||||
|
||||
### profile_sidebar_enter
|
||||
Called prior to generating the sidebar "short" profile for a page.
|
||||
`$b` is the person's profile array
|
||||
|
||||
### profile_sidebar
|
||||
Called when generating the sidebar "short" profile for a page.
|
||||
`$b` is an array:
|
||||
|
||||
- **profile**: profile record array for the person from the database
|
||||
- **entry**: the HTML string of the generated entry
|
||||
|
||||
### contact_block_end
|
||||
Called when formatting the block of contacts/friends on a profile sidebar has completed.
|
||||
`$b` is an array:
|
||||
|
||||
- **contacts**: array of contacts
|
||||
- **output**: the generated HTML string of the contact block
|
||||
|
||||
### bbcode
|
||||
Called after conversion of bbcode to HTML.
|
||||
`$b` is an HTML string converted text.
|
||||
|
||||
### html2bbcode
|
||||
Called after tag conversion of HTML to bbcode (e.g. remote message posting)
|
||||
`$b` is a string converted text
|
||||
|
||||
### page_header
|
||||
Called after building the page navigation section.
|
||||
`$b` is a string HTML of nav region.
|
||||
|
||||
### personal_xrd
|
||||
Called prior to output of personal XRD file.
|
||||
`$b` is an array:
|
||||
|
||||
- **user**: the user record array for the person
|
||||
- **xml**: the complete XML string to be output
|
||||
|
||||
### home_content
|
||||
Called prior to output home page content, shown to unlogged users.
|
||||
`$b` is the HTML sring of section region.
|
||||
|
||||
### contact_edit
|
||||
Called when editing contact details on an individual from the Contacts page.
|
||||
$b is an array:
|
||||
|
||||
'contact' => contact (array) record for the person from the database
|
||||
'entry' => the (string) HTML of the generated entry
|
||||
- **contact**: contact record (array) of target contact
|
||||
- **output**: the (string) generated HTML of the contact edit page
|
||||
|
||||
### 'profile_sidebar_enter'
|
||||
* called prior to generating the sidebar "short" profile for a page
|
||||
* $b is the person's profile array
|
||||
### contact_edit_post
|
||||
Called when posting the contact edit page.
|
||||
`$b` is the `$_POST` array
|
||||
|
||||
### 'profile_sidebar'
|
||||
'profile_sidebar is called when generating the sidebar "short" profile for a page.
|
||||
$b is an array:
|
||||
### init_1
|
||||
Called just after DB has been opened and before session start.
|
||||
No hook data.
|
||||
|
||||
'profile' => profile (array) record for the person from the database
|
||||
'entry' => the (string) HTML of the generated entry
|
||||
### page_end
|
||||
Called after HTML content functions have completed.
|
||||
`$b` is (string) HTML of content div.
|
||||
|
||||
### 'contact_block_end'
|
||||
is called when formatting the block of contacts/friends on a profile sidebar has completed.
|
||||
$b is an array:
|
||||
### avatar_lookup
|
||||
Called when looking up the avatar. `$b` is an array:
|
||||
|
||||
'contacts' => array of contacts
|
||||
'output' => the (string) generated HTML of the contact block
|
||||
- **size**: the size of the avatar that will be looked up
|
||||
- **email**: email to look up the avatar for
|
||||
- **url**: the (string) generated URL of the avatar
|
||||
|
||||
### 'bbcode'
|
||||
* called during conversion of bbcode to html
|
||||
* $b is a string converted text
|
||||
### emailer_send_prepare
|
||||
Called from `Emailer::send()` before building the mime message.
|
||||
`$b` is an array of params to `Emailer::send()`.
|
||||
|
||||
### 'html2bbcode'
|
||||
* called during conversion of html to bbcode (e.g. remote message posting)
|
||||
* $b is a string converted text
|
||||
- **fromName**: name of the sender
|
||||
- **fromEmail**: email fo the sender
|
||||
- **replyTo**: replyTo address to direct responses
|
||||
- **toEmail**: destination email address
|
||||
- **messageSubject**: subject of the message
|
||||
- **htmlVersion**: html version of the message
|
||||
- **textVersion**: text only version of the message
|
||||
- **additionalMailHeader**: additions to the smtp mail header
|
||||
|
||||
### 'page_header'
|
||||
* called after building the page navigation section
|
||||
* $b is a string HTML of nav region
|
||||
### emailer_send
|
||||
Called before calling PHP's `mail()`.
|
||||
`$b` is an array of params to `mail()`.
|
||||
|
||||
### 'personal_xrd'
|
||||
'personal_xrd' is called prior to output of personal XRD file.
|
||||
$b is an array:
|
||||
- **to**
|
||||
- **subject**
|
||||
- **body**
|
||||
- **headers**
|
||||
|
||||
'user' => the user record for the person
|
||||
'xml' => the complete XML to be output
|
||||
### nav_info
|
||||
Called after the navigational menu is build in `include/nav.php`.
|
||||
`$b` is an array containing `$nav` from `include/nav.php`.
|
||||
|
||||
### 'home_content'
|
||||
* called prior to output home page content, shown to unlogged users
|
||||
* $b is (string) HTML of section region
|
||||
|
||||
### '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'
|
||||
* called when posting the contact edit page.
|
||||
* $b is the $_POST array
|
||||
|
||||
### 'init_1'
|
||||
* called just after DB has been opened and before session start
|
||||
* $b is not used or passed
|
||||
|
||||
### 'page_end'
|
||||
* called after HTML content functions have completed
|
||||
* $b is (string) HTML of content div
|
||||
|
||||
### 'avatar_lookup'
|
||||
'avatar_lookup' is called when looking up the avatar.
|
||||
$b is an array:
|
||||
|
||||
'size' => the size of the avatar that will be looked up
|
||||
'email' => email to look up the avatar for
|
||||
'url' => the (string) generated URL of the avatar
|
||||
|
||||
### '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
|
||||
'fromEmail' => email fo the sender
|
||||
'replyTo' => replyTo address to direct responses
|
||||
'toEmail' => destination email address
|
||||
'messageSubject' => subject of the message
|
||||
'htmlVersion' => html version of the message
|
||||
'textVersion' => text only version of the message
|
||||
'additionalMailHeader' => additions to the smtp mail header
|
||||
|
||||
### 'emailer_send'
|
||||
is called before calling PHP's mail().
|
||||
$b is an array, params to mail()
|
||||
|
||||
'to'
|
||||
'subject'
|
||||
'body'
|
||||
'headers'
|
||||
|
||||
### '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'
|
||||
is called before vars are passed to the template engine to render the page.
|
||||
### template_vars
|
||||
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:
|
||||
`$b` is an array with:
|
||||
|
||||
'template' => filename of template
|
||||
'vars' => array of vars passed to template
|
||||
- **template**: filename of template
|
||||
- **vars**: array of vars passed to the template
|
||||
|
||||
### 'acl_lookup_end'
|
||||
is called after the other queries have passed.
|
||||
The registered function can add, change or remove the acl_lookup() variables.
|
||||
### acl_lookup_end
|
||||
Called after the other queries have passed.
|
||||
The registered function can add, change or remove the `acl_lookup()` variables.
|
||||
|
||||
'results' => array of the acl_lookup() vars
|
||||
- **results**: array of the acl_lookup() vars
|
||||
|
||||
### 'prepare_body_init'
|
||||
### prepare_body_init
|
||||
Called at the start of prepare_body
|
||||
Hook data:
|
||||
'item' => item array (input/output)
|
||||
|
||||
### 'prepare_body_content_filter'
|
||||
- **item** (input/output): item array
|
||||
|
||||
### prepare_body_content_filter
|
||||
Called before the HTML conversion in prepare_body. If the item matches a content filter rule set by an addon, it should
|
||||
just add the reason to the filter_reasons element of the hook data.
|
||||
Hook data:
|
||||
'item' => item array (input)
|
||||
'filter_reasons' => reasons array (input/output)
|
||||
|
||||
### 'prepare_body'
|
||||
Called after the HTML conversion in prepare_body.
|
||||
- **item**: item array (input)
|
||||
- **filter_reasons** (input/output): reasons array
|
||||
|
||||
### prepare_body
|
||||
Called after the HTML conversion in `prepare_body()`.
|
||||
Hook data:
|
||||
'item' => item array (input)
|
||||
'html' => converted item body (input/output)
|
||||
'is_preview' => post preview flag (input)
|
||||
'filter_reasons' => reasons array (input)
|
||||
|
||||
### 'prepare_body_final'
|
||||
Called at the end of prepare_body.
|
||||
- **item** (input): item array
|
||||
- **html** (input/output): converted item body
|
||||
- **is_preview** (input): post preview flag
|
||||
- **filter_reasons** (input): reasons array
|
||||
|
||||
### prepare_body_final
|
||||
Called at the end of `prepare_body()`.
|
||||
Hook data:
|
||||
'item' => item array (input)
|
||||
'html' => converted item body (input/output)
|
||||
|
||||
### 'put_item_in_cache'
|
||||
Called after prepare_text in put_item_in_cache().
|
||||
- **item**: item array (input)
|
||||
- **html**: converted item body (input/output)
|
||||
|
||||
### put_item_in_cache
|
||||
Called after `prepare_text()` in `put_item_in_cache()`.
|
||||
Hook data:
|
||||
'item' => item array (input)
|
||||
'rendered-html' => final item body HTML (input/output)
|
||||
'rendered-hash' => original item body hash (input/output)
|
||||
|
||||
### 'magic_auth_success'
|
||||
- **item** (input): item array
|
||||
- **rendered-html** (input/output): final item body HTML
|
||||
- **rendered-hash** (input/output): original item body hash
|
||||
|
||||
### magic_auth_success
|
||||
Called when a magic-auth was successful.
|
||||
Hook data:
|
||||
'visitor' => array with the contact record of the visitor
|
||||
'url' => the query string
|
||||
|
||||
Current JavaScript hooks
|
||||
-------------
|
||||
visitor => array with the contact record of the visitor
|
||||
url => the query string
|
||||
|
||||
### 'postprocess_liveupdate'
|
||||
## Current JavaScript hooks
|
||||
|
||||
### postprocess_liveupdate
|
||||
Called at the end of the live update process (XmlHttpRequest)
|
||||
|
||||
Complete list of hook callbacks
|
||||
---
|
||||
## Complete list of hook callbacks
|
||||
|
||||
Here is a complete list of all hook callbacks with file locations (as of 01-Apr-2018). Please see the source for details of any hooks not documented above.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue