1# components
2A DokuWiki helper plugin for easily implementing new actions and new ajax functions in plugins
3
4## AJAX calls
5To add a new AJAX call handler for a plugin, (for example, an AJAX function call some_plugin.some_call), one needs to put a script some_call.php in the ajax directory under the some_plugin file structure. In this PHP script you need to declare a class that extends the Doku_AJAX class (see its definition in lib/ajax.php, and an example in ajax/example.php).
6
7### AJAX methods
8The class must implement 3 methods:
9
101. `public function name() { return 'some_call'; };`
11  * it returns the name of the AJAX call (here, 'some_call'). Note that the actual call is some_plugin.some_call;
12
132. `protected function auth($params) { return ...; }`
14  * here $params is the params that got passed from the client, and it returns TRUE if the user is authorized to call this function, and FALSE otherwise;
15
163. `protected function call($params) { return ...; }`
17  * here $params is the same as above, and the return value is the response to be sent to the client. The return value could be an int, a float, a bool, a strng, or an array.
18
19### The constructor
20This class must also define a constructor
21```
22public function __construct() {
23    parent::__construct(
24        // the required parameters to the AJAX call
25        array(
26            'param_1' => 'type 1',
27            'param_2' => 'type 2' // etc .
28        ),
29        // some optional parameters
30        array(
31            'optional1' => 'type_3' // etc
32        )
33    );
34}
35```
36
37### The client side
38For the AJAX call, you should use
39```
40jQuery.ajax(DOKU_BASE.concat('lib/exe/ajax.php'), {
41	data: {
42		call: 'some_plugin.some_call',
43		sectok: sectok,
44		param1: some_value1,
45		param2: some_value2
46		// optionally, include
47		// optional1: some_value3
48		// note that javascript arrays must use the form
49		// some_array: JSON.stringify(some_array)
50	}
51}).done(function(data) {
52	// the data is the returned data from the call function
53});
54```
55
56### An Example
57
58Try put `<slice from="1" to="10"/>` in your wiki page. This example is included here in
59- syntax/slice.php
60- script.js
61- ajax/example.php
62
63## Action handlers and renderers
64See lib/action.php for the definitions of the action handlers, renderers. These handlers must
65be put under the commands folder of a plugin, with the script filename the same as
66the command name. For example, commands/example.php is the randler for the command
67`pluginname.example`. These files can be put in subdirectories of arbitrary depth to
68avoid colliding in file names. You can only define at most a single action handler and at most a single renderer.
69
70### Extending a previously defined action
71If you extend a hander/renderer, then the subclass replaces
72the parent class as the handler/renderer.
73
74The key methods:
75- `public function action() { return ...; }`
76  - This defines the action name that these handlers respond to. Note the full action name is pluginname.actionname
77- `public function permission_required() { return ...; }`
78  - This returns the minimum required permission for the user to perform this action.
79- `public function handle() { ... }
80  - This is the logic that handles the action. If you want to chain performing another action, return the name of that action. For example, you may want to show the page after handling is done, then return 'show'. The handler is called after all preprocessors and before all postprocessors.
81- `public function xhtml() { ... }`
82  - This is the renderer logic for the action. The randerer is called after all post processors
83
84### Example:
85See the `commands/example.php` file for an example. You can put
86```
87[[?do=components.example&tag=pre]]
88[[?do=components.example&tag=div]]
89```
90in your wiki text to play with this action.
91