updated help/plugins to reflect some of the new interfaces and procedures

1 files changed, 34 insertions, 18 deletions

diff --git a/doc/plugins.bb b/doc/plugins.bb
index f74276038..9bcefdd3b 100644
--- a/doc/plugins.bb
+++ b/doc/plugins.bb
@@ -45,16 +45,16 @@ In our case, we'll call them randplace_load() and randplace_unload(), as that is
  pluginname_uninstall()

 [/code]

 

-Next we'll talk about **hooks**. Hooks are places in the $Projectname code where we allow plugins to do stuff. There are a [lot of these](help/Hooks), and they each have a name. What we normally do is use the pluginname_load() function to register a "handler function" for any hooks you are interested in. Then when any of these hooks are triggered, your code will be called.

+Next we'll talk about [b]hooks[/b]. Hooks are places in the $Projectname code where we allow plugins to do stuff. There are a [url=[baseurl]/help/hooklist]lot of these[/url], and they each have a name. What we normally do is use the pluginname_load() function to register a "handler function" for any hooks you are interested in. Then when any of these hooks are triggered, your code will be called.

 

-We register hook handlers with the 'register_hook()' function. It takes 3 arguments. The first is the hook we wish to catch, the second is the filename of the file to find our handler function (relative to the base of your $Projectname installation), and the third is the function name of your handler function. So let's create our randplace_load() function right now. 

+We register hook handlers with the 'Zotlabs\Extend\Hook::register()' function. It typically takes 3 arguments. The first is the hook we wish to catch, the second is the filename of the file to find our handler function (relative to the base of your $Projectname installation), and the third is the function name of your handler function. So let's create our randplace_load() function right now. 

 

 [code]

 	function randplace_load() {

-	    register_hook('post_local', 'addon/randplace/randplace.php', 'randplace_post_hook');

+	    Zotlabs\Extend\Hook::register('post_local', 'addon/randplace/randplace.php', 'randplace_post_hook');

 

-    	register_hook('feature_settings', 'addon/randplace/randplace.php', 'randplace_settings');

-    	register_hook('feature_settings_post', 'addon/randplace/randplace.php', 'randplace_settings_post');

+        Zotlabs\Extend\Hook::register('feature_settings', 'addon/randplace/randplace.php', 'randplace_settings');

+	    Zotlabs\Extend\Hook::register('feature_settings_post', 'addon/randplace/randplace.php', 'randplace_settings_post');

 

 	}

 [/code]

@@ -64,21 +64,18 @@ So we're going to catch three events, 'post_local' which is triggered when a pos
 Next we'll create an unload function. This is easy, as it just unregisters our hooks. It takes exactly the same arguments. 

 [code]

 	function randplace_unload() {

-	    unregister_hook('post_local', 'addon/randplace/randplace.php', 'randplace_post_hook');

-

-    	unregister_hook('feature_settings', 'addon/randplace/randplace.php', 'randplace_settings');

-    	unregister_hook('feature_settings_post', 'addon/randplace/randplace.php', 'randplace_settings_post');

+	    Zotlabs\Extend\Hook::unregister('post_local', 'addon/randplace/randplace.php', 'randplace_post_hook');

 

+        Zotlabs\Extend\Hook::unregister('feature_settings', 'addon/randplace/randplace.php', 'randplace_settings');

+	    Zotlabs\Extend\Hook::unregister('feature_settings_post', 'addon/randplace/randplace.php', 'randplace_settings_post');

 	}

 [/code]

 

-Hooks are called with two arguments. The first is always $a, which is our global App structure and contains a huge amount of information about the state of the web request we are processing; as well as who the viewer is, and what our login state is, and the current contents of the web page we're probably constructing.

-

-The second argument is specific to the hook you're calling. It contains information relevant to that particular place in the program, and often allows you to look at, and even change it. In order to change it, you need to add '&' to the variable name so it is passed to your function by reference. Otherwise it will create a copy and any changes you make will be lost when the hook process returns. Usually (but not always) the second argument is a named array of data structures. Please see the "hook reference" (not yet written as of this date) for details on any specific hook. Occasionally you may need to view the program source to see precisely how a given hook is called and how the results are processed. 

+Hooks are always called with one argument which is specific to the hook you're calling. It contains information relevant to that particular place in the program, and often allows you to look at, and even change it. In order to change it, you need to add '&' to the variable name so it is passed to your function by reference. Otherwise it will create a copy and any changes you make will be lost when the hook process returns. Usually (but not always) the second argument is a named array of data structures. Please see the "hook reference" (not yet written as of this date) for details on any specific hook. Occasionally you may need to view the program source to see precisely how a given hook is called and how the results are processed. 

 

 Let's go ahead and add some code to implement our post_local hook handler. 

 [code]

-	function randplace_post_hook($a, &$item) {

+	function randplace_post_hook(&$item) {

 

 	    /**

     	 *

@@ -145,7 +142,7 @@ Now let's add our functions to create and store preference settings.
 	 *

 	 */

 

-	function randplace_settings_post($a,$post) {

+	function randplace_settings_post($post) {

 	    if(! local_channel())

 	        return;

 	    if($_POST['randplace-submit'])

@@ -171,7 +168,7 @@ Now let's add our functions to create and store preference settings.
 

 

 

-	function randplace_settings(&$a,&$s) {

+	function randplace_settings(&$s) {

 

 	    if(! local_channel())

 	        return;

@@ -205,10 +202,30 @@ Now let's add our functions to create and store preference settings.
    

 

 

-***Advanced Plugins***

+[h2]Advanced Plugins[/h2]

 

 Sometimes your plugins want to provide a range of new functionality which isn't provided at all or is clumsy to provide using hooks. In this case your plugin can also act as a 'module'. A module in our case refers to a structured webpage handler which responds to a given URL. Then anything which accesses that URL will be handled completely by your plugin.

 

+There are two ways to accomplish this. To create a module object use the following model:

+[code]

+

+	// Your module will consist of the name of your addon with an uppercase first character, within the Zotlabs\Module namespace

+

+	class Zotlabs\Module\Randplace extends Zotlabs\Web\Controller {

+		function init() { 

+			// init method is always called first if it exists 

+		}

+		function post() { 

+			// the post method is only called if there are $_POST variables present (e.g. the page request method is "post")

+		}

+		function get() {

+			// The get method is used to display normal content on the page

+			// whatever this function returns will be displayed in the page body

+		}

+	}

+[/code]

+

+The other option is to use a procedural interface. The $a argument to these function is obsolete, but must be present. 

 The key to this is to create a simple function named pluginname_module() which does nothing. 

 [code]

 	function randplace_module() { return; }

@@ -217,7 +234,6 @@ Once this function exists, the URL #^[url=https://yoursite/randplace]https://you
 [code]

 	modulename_init($a)    // (e.g. randplace_init($a);) called first - if you wish to emit json or xml, 

 	                       // you should do it here, followed by killme() which will avoid the default action of building a webpage

-	modulename_aside($a)   // Often used to create sidebar content

 	modulename_post($a)    // Called whenever the page is accessed via the "post" method

 	modulename_content($a) // called to generate the central page content. This function should return a string 

 	                       // consisting of the central page content.

@@ -228,7 +244,7 @@ Your module functions have access to the URL path as if they were standalone pro
 [/code]

 we will create an argc/argv list for use by your module functions

 [code]

-	$x = argc(); $x will be 4, the number of path arguments after the sitename

+	$x = argc(); // $x will be 4, the number of path arguments after the sitename

 

 	for($x = 0; $x < argc(); $x ++)

 		echo $x . ' ' . argv($x);