preliminary plugin hook documentation

addon/README

@@ -0,0 +1,125 @@
+Friendika Addon/Plugin development
+
+This is an early specification and hook details may be subject to change.
+
+Please see the sample addon 'randplace' for a working example of using these features.
+
+
+You must register plugins with the system in the .htconfig.php file.
+
+$a->config['system']['addon'] = 'plugin1name, plugin2name, another_name';
+
+Plugin names cannot contain spaces and are used as filenames.
+
+
+Register your plugin hooks during installation. 
+
+	register_hook($hookname, $file, $function);
+
+	$hookname is a string and corresponds to a known Friendika hook
+	$file is a pathname relative to the top-level Friendika directory.
+		This *should* be 'addon/plugin_name/plugin_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.
+
+
+Your hook functions will be called with at least one and possibly two arguments
+
+	function myhook_function(&$a, &$b) {
+
+
+	}
+
+If you wish to make changes to the calling data, you must declare them as 
+reference variables (with '&') during function declaration. 
+
+$a is the Friendika 'App' class - which contains a wealth of information
+about the current state of Friendika, such as which module has been called,
+configuration info, 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.
+
+$b can be called anything you like. This is information which is 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.
+
+
+Current hooks:
+
+'authenticate' - called when a user attempts to login. 
+	$b is an array
+		'username' => the supplied username
+		'password' => the supplied password
+		'authenticated' => set this to non-zero to authenticate the user.
+
+'logged_in' - called after a user has successfully logged in.
+	$b contains the $a->user array
+
+
+'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  
+
+'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_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.
+
+'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.
+
+'settings_post' - called when the Settings and Addon Settings pages are submitted.
+	$b is the $_POST array
+
+'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
+
+'directory_item' - 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' - called when generating the sidebar "short" profile for a page
+	$b is the (string) generated HTML of the entry
+		(The profile array details are in $a->profile)
+
+'contact_block_end' - called when displaying the block of contacts/friends on a 
+	profile sidebar
+***	$b is the (string) generated HTML of the contact block
+
+
+*** = subject to change
+
+
+
+
+
+Not yet documented:
+
+'atom_feed'
+
+'atom_feed_end'
+
+'parse_atom'
+
+'atom_author'
+
+'atom_entry'
+
+'parse_link'
+
+
+
+
+