]> git.mxchange.org Git - friendica.git/blob - doc/Plugins.md
revup
[friendica.git] / doc / Plugins.md
1 **Friendika Addon/Plugin development**
2
3 This is an early specification and hook details may be subject to change.
4
5 Please see the sample addon 'randplace' for a working example of using some of these features. The facebook addon provides an example of integrating both "addon" and "module" functionality. Addons work by intercepting event hooks - which must be registered. Modules work by intercepting specific page requests (by URL path). 
6
7 You must register all addons/plugins with the system in the .htconfig.php file.
8
9      $a->config['system']['addon'] = 'plugin1name, plugin2name, another_name';
10
11 Plugin names cannot contain spaces and are used as filenames. Each addon must contain both an install and an uninstall function based on the addon/plugin name. For instance "plugin1name_install()". These two functions take no arguments and are usually responsible for registering (and unregistering) event hooks that your plugin will require. The install and uninstall functions will also be called (i.e. re-installed) if the plugin changes after installation - therefore your uninstall should not destroy data and install should consider that data may already exist. Future extensions may provide for "setup" amd "remove". 
12
13
14
15 Register your plugin hooks during installation.
16
17     register_hook($hookname, $file, $function);
18
19 $hookname is a string and corresponds to a known Friendika hook.
20
21 $file is a pathname relative to the top-level Friendika directory. This *should* be 'addon/plugin_name/plugin_name.php' in most cases.
22
23 $function is a string and is the name of the function which will be executed when the hook is called.
24
25
26 Your hook callback functions will be called with at least one and possibly two arguments
27
28
29     function myhook_function(&$a, &$b) {
30
31
32     }
33
34
35 If you wish to make changes to the calling data, you must declare them as
36 reference variables (with '&') during function declaration.
37
38 $a is the Friendika 'App' class - which contains a wealth of information
39 about the current state of Friendika, such as which module has been called,
40 configuration info, the page contents at the point the hook was invoked, profile
41 and user information, etc. It is recommeded you call this '$a' to match its usage
42 elsewhere.
43
44 $b can be called anything you like. This is information which is specific to the hook
45 currently being processed, and generally contains information that is being immediately
46 processed or acted on that you can use, display, or alter. Remember to declare it with
47 '&' if you wish to alter it.
48
49 **Modules**
50
51 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 need not do anything.
52
53 If this function exists, you will now receive all page requests for "http://my.web.site/plugin_name" - with any number of URL components as additional arguments. These are parsed into an array $a->argv, with a corresponding $a->argc indicating the number of URL components. 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:
54      $a->argc = 3
55      $a->argv = array(0 => 'plugin', 1 => 'arg1', 2 => 'arg2');
56
57 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. 
58
59
60
61 **Current hooks:**
62
63 **'authenticate'** - called when a user attempts to login.
64     $b is an array
65         'username' => the supplied username
66         'password' => the supplied password
67         'authenticated' => set this to non-zero to authenticate the user.
68         'user_record' => successful authentication must also return a valid user record from the database
69
70 **'logged_in'** - called after a user has successfully logged in.
71     $b contains the $a->user array
72
73
74 **'display_item'** - called when formatting a post for display.
75     $b is an array
76         'item' => The item (array) details pulled from the database
77         'output' => the (string) HTML representation of this item prior to adding it to the page
78
79 **'post_local'** - called when a status post or comment is entered on the local system
80     $b is the item array of the information to be stored in the database
81         {Please note: body contents are bbcode - not HTML)
82
83 **'post_local_end'** - called when a local status post or comment has been stored on the local system
84     $b is the item array of the information which has just been stored in the database
85         {Please note: body contents are bbcode - not HTML)
86
87 **'post_remote'** - called when receiving a post from another source. This may also be used to post local activity or system generated messages.
88     $b is the item array of information to be stored in the database and the item
89     body is bbcode.
90
91 **'settings_form'** - called when generating the HTML for the user Settings page
92     $b is the (string) HTML of the settings page before the final '</form>' tag.
93
94 **'settings_post'** - called when the Settings pages are submitted.
95     $b is the $_POST array
96
97 **'plugin_settings'** - called when generating the HTML for the addon settings page
98     $b is the (string) HTML of the addon settings page before the final '</form>' tag.
99
100 **'plugin_settings_post'** - called when the Addon Settings pages are submitted.
101     $b is the $_POST array
102
103 **'profile_post'** - called when posting a profile page.
104     $b is the $_POST array
105
106 **'profile_edit'** - called prior to output of profile edit page
107     $b is array
108         'profile' => profile (array) record from the database
109         'entry' => the (string) HTML of the generated entry
110
111
112 **'profile_advanced'** - called when the HTML is generated for the 'Advanced profile', corresponding to the 'Profile' tab within a person's profile page.
113     $b is the (string) HTML representation of the generated profile
114     (The profile array details are in $a->profile)
115
116 **'directory_item'** - called from the Directory page when formatting an item for display
117     $b is an array
118         'contact' => contact (array) record for the person from the database
119         'entry' => the (string) HTML of the generated entry
120
121 **'profile_sidebar_enter'** - called prior to generating the sidebar "short" profile for a page
122     $b is (array) the person's profile array
123
124 **'profile_sidebar'** - called when generating the sidebar "short" profile for a page
125     $b is an array
126         'profile' => profile (array) record for the person from the database
127         'entry' => the (string) HTML of the generated entry
128
129 **'contact_block_end'** - called when formatting the block of contacts/friends on a profile sidebar has completed
130     $b is an array
131           'contacts' => array of contacts
132           'output' => the (string) generated HTML of the contact block
133
134 **'bbcode'** - called during conversion of bbcode to html
135     $b is (string) converted text
136
137 **'html2bbcode'** - called during conversion of html to bbcode (e.g. remote message posting)
138     $b is (string) converted text
139
140 **'page_header'** - called after building the page navigation section
141     $b is (string) HTML of nav region
142
143 **'personal_xrd'** - called prior to output of personal XRD file.
144     $b is an array
145         'user' => the user record for the person
146         'xml' => the complete XML to be output
147
148 **'home_content'** - called prior to output home page content, shown to unlogged users
149     $b is (string) HTML of section region
150
151 **'contact_edit'** - called when editing contact details on an individual from the Contacts page
152     $b is (array)
153         'contact' => contact record (array) of target contact
154         'output' => the (string) generated HTML of the contact edit page
155
156 **'contact_edit_post'** - called when posting the contact edit page
157     $b is the $_POST array
158
159 **'init_1'** - called just after DB has been opened and before session start
160     $b is not used or passed
161
162
163 **'page_end'** - called after HTML content functions have completed
164     $b is (string) HTML of content div
165
166
167 *** = subject to change
168
169 Not yet documented (you may view these within the source code):
170
171 **'atom_feed'** ***
172
173 **'atom_feed_end'** ***
174
175 **'parse_atom'** ***
176
177 **'atom_author'** ***
178
179 **'atom_entry'** ***
180
181 A complete list of all hook callbacks with file locations (generated 22-Feb-2011): Please see the source for details of any hooks not documented above.
182
183 boot.php:       call_hooks('contact_block_end', $arr);
184
185 boot.php:       call_hooks('profile_sidebar_enter', $profile);
186
187 boot.php:       call_hooks('profile_sidebar', $arr);
188
189 boot.php:       call_hooks("proc_run", $args);
190
191 include/nav.php:        call_hooks('page_header', $a->page['nav']);
192
193 include/auth.php:               call_hooks('authenticate', $addon_auth);
194
195 include/auth.php:               call_hooks('logged_in', $a->user);
196
197 include/bbcode.php:     call_hooks('bbcode',$Text);
198
199 include/acl_selectors.php:      call_hooks($a->module . '_pre_' . $selname, $arr);
200
201 include/acl_selectors.php:      call_hooks($a->module . '_post_' . $selname, $o);
202
203 include/acl_selectors.php:      call_hooks($a->module . '_pre_' . $selname, $arr);
204
205 include/acl_selectors.php:      call_hooks($a->module . '_post_' . $selname, $o);
206
207 include/items.php:      call_hooks('atom_feed', $atom);
208
209 include/items.php:              call_hooks('atom_feed_end', $atom);
210
211 include/items.php:      call_hooks('atom_feed_end', $atom);
212
213 include/items.php:      call_hooks('parse_atom', $arr);
214
215 include/items.php:      call_hooks('post_remote',$arr);
216
217 include/items.php:      call_hooks('atom_author', $o);
218
219 include/items.php:      call_hooks('atom_entry', $o);
220
221 include/html2bbcode.php:        call_hooks('html2bbcode', $text);
222
223 index.php:      call_hooks('init_1');
224
225 index.php:call_hooks('app_menu', $arr);
226
227 index.php:call_hooks('page_end', $a->page['content']);
228
229 mod/photos.php: call_hooks('photo_post_init', $_POST);
230
231 mod/photos.php: call_hooks('photo_post_file',$ret);
232
233 mod/photos.php: call_hooks('photo_post_end',intval($item_id));
234
235 mod/photos.php:         call_hooks('photo_upload_form',$ret);
236
237 mod/parse_url.php:      call_hooks('parse_link', $arr);
238
239 mod/home.php:   call_hooks("home_content",$o);
240
241 mod/contacts.php:       call_hooks('contact_edit_post', $_POST);
242
243 mod/contacts.php:               call_hooks('contact_edit', $arr);
244
245 mod/settings.php:               call_hooks('plugin_settings_post', $_POST);
246
247 mod/settings.php:       call_hooks('settings_post', $_POST);
248
249 mod/settings.php:               call_hooks('plugin_settings', $o);
250
251 mod/settings.php:       call_hooks('settings_form',$o);
252
253 mod/network.php:                call_hooks('jot_tool', $jotplugins);
254
255 mod/network.php:                call_hooks('jot_networks', $jotnets);
256
257 mod/network.php:                        call_hooks('display_item', $arr);
258
259 mod/xrd.php:    call_hooks('personal_xrd', $arr);
260
261 mod/item.php:   call_hooks('post_local_start', $_POST);
262
263 mod/item.php:   call_hooks('post_local',$datarray);
264
265 mod/item.php:   call_hooks('post_local_end', $datarray);
266
267 mod/profile.php:                        call_hooks('profile_advanced',$o);
268
269 mod/profile.php:                        call_hooks('jot_tool', $jotplugins); 
270
271 mod/profile.php:                        call_hooks('jot_networks', $jotnets);
272
273 mod/profile.php:                        call_hooks('display_item', $arr);
274
275 mod/display.php:                        call_hooks('display_item', $arr);
276
277 mod/profiles.php:       call_hooks('profile_post', $_POST);
278
279 mod/profiles.php:               call_hooks('profile_edit', $arr);
280
281 mod/cb.php:     call_hooks('cb_init');
282
283 mod/cb.php:     call_hooks('cb_post', $_POST);
284
285 mod/cb.php:     call_hooks('cb_afterpost');
286
287 mod/cb.php:     call_hooks('cb_content', $o);
288
289 mod/directory.php:                      call_hooks('directory_item', $arr);