====== components Plugin ======

---- plugin ----
description: Defines some easy interfaces for AJAX function handlers and action handlers/renderers
author     : jma 
email      : junlingm@gmail.com 
type       : action
lastupdate : 2015-12-21
compatible : 2015-08-10a
depends    : 
conflicts  : 
similar    : 
tags       : action, ajax

downloadurl: https://github.com/roverrobot/components/zipball/master
bugtracker : https://github.com/roverrobot/components/issues
sourcerepo : https://github.com/roverrobot/components
donationurl: 

screenshot_img : 
----

===== Installation =====

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

===== Examples/Usage =====

===== New action handlers/renderers =====

All new action handlers should be put under your plugin's //commands// folder, with a php script name identical to your command name. For example, if you want to implement an example_action action for your plugin named example, you need to put commands/example.php under your plugin folder. This defines an action example.example_action. Your script should as lead extend the Doku_Action class, which defines a handler, and its handle class can return an action name to change the processing to the action that you returned. If you do not change to another action, you must define a renderer for this action by extending the Doku_Action_Renderer class. Its xhtml() function's standard output is the action rendering output.

See the commands/example.php in this source repo. To see this in action, add a link to ''%%?do=components.example&tag=pre%%'' to your page.

===== AJAX function call handler =====

All new AJAX function call should extend the Doku_AJAX class, and be put in your plugin's //ajax// folder, with a name identical to your AJAX function. For example, if you want to implement a function example_call in your plugin named example, you should name the script ajax/example.php. This defines an AJAX function call named example.example_call. The caller should pass in a data object that contains

<code>
{
   call: example.example_call,
   sectok: your_sectok,
   param1: some_value1,
   param2: some_value2 //etc, you can put as many parameters as you need to
}
</code>

Your ajax handler class should implement the call($parmas) function, which returns a PHP array/string/number/bool, this return value is automatically encoded as JSON and sent to the client. The $params argument is an array holding the passed in parameters. To specify the parameters, the constructor should call the parent's constructor with two parameters, the first is an array of required parameters, keys are the parameter names, and values are the parameter types. The second is an optional parameter array in the same format. For example,

<code php>
public function __construct() {
    parent::__construct(
        array('param1' => 'array', 'param2' => 'string')
    );
}
</code>

See the ajax/example.php and script.js for an example. To see the example in action, put ''%%<slice from="1" to="5"/>%%'' in your wiki to see aslice of the first 5 characters in your raw wiki text. 

===== Development =====

The GitHub repo: [[https://github.com/roverrobot/components]]

=== Change Log ===

  * **2015-12-21d**
    * A working initial release.

=== Known Bugs and Issues ===


=== ToDo/Wish List ===


===== FAQ =====


===== Discussion =====