XMPP triggers many different kinds of events that are run against all the loaded widgets. In order to process an event, you may register one or more handlers in your widget.

An event handler is a public method that only takes one the paramter $data, which usually is an array that contains the data returned by the XMPP server.

Your handlers must be registered in WidgetLoad() with the method:

WidgetBase::registerEvent($eventType, $handler)

$handler is the name of the method as a string, and $eventType is the name of the event as a string.

The XMPP subsystem currently raises the following events:

One additional event type is availble: allEvents. This type of event is a catchall that is always executed before the other event handlers in the widget.

The event handling process cannot be interrupted. All loaded widgets will be requested to run their eventhandlers, unless of course a fatal error occurs.

Movim's javascript and PHP parts communicate through a custom xmlrpc protocol. It is implemented in the class RPC on the PHP side.

RPC exposes two static functions to the widget:

You can define your own javascript functions on a per-widget basis, or use one of the standard functions.

You may define your own javascript callback functions and use them as appropriate. Alternatively, Movim comes with a standard set of javascript callbacks that allow simple operations on HTML elements (picked up by ID).

Any method defined in your widget that starts with ajax will have a javascript ajax call automatically generated.

This ajax call can be explicitely called upon with the method:

WidgetBase::callAjax($funcname, ...)

$funcname is the name of the ajax function. The rest of paramters are passed to the ajax-called PHP function.

It is important to understand how the ajax calls work in Movim. Movim uses a custom-designed xmlrpc protocol to callback PHP functions directly. Therefore, making an ajax call is very similar to making a straight callback in PHP.

So for example if you have defined an ajax function

ajaxMyfunction($param)

you can call it with

$this->callAjax('ajaxMyfunction', "'myparam'")

Here is a complete example of a widget that implements an ajax call:

class MyWidget extends WidgetBase
{
    function ajaxTest($param1, $param2)
    {
       RPC::call('movim_append', 'test',
                      RPC::cdata('<p>Test</p>'));
    }

    function build()
    {
       ?>
       <div id="test"></div>
       <input type="button"
              onclick="<? $this->callAjax(
                           'ajaxTest',
                           '"param1"',
                           '2');?>"/>
       <?
    }
}

Note that string parameters passed to the ajax method must be double-quoted. The reason for this is that javascript will remove the first set of quotes. Thus single-quoted parameters will be javascript objects.

The drawback of WidgetBase::callAjax() is that it prints the ajax call straight away. It is sometimes desirable to have it return the generated call. Another variant of the function exists that does this:

WidgetBase::genCallAjax($funcname, $callback, $target, ...)

Widgets can come along with their own resources, in particular their CSS and javascript.

The Widget base class includes two methods to ease the integration of custom javascript and css:

WidgetBase::addjs($jsfile)
WidgetBase::addcss($cssfile)

The file paths given to these functions are relative to the widget's directory.

For resources, you can use the function:

WidgetBase::respath($file, $fspath = false)

This returns the URL to the specified file. The optional parameter $fspath will make the function return the file-system path rather than the URL to the file.

Movim has moved away from using PHP’s sessions, which couldn’t provide an efficient locking and handling of Movim’s multi-threaded behaviour.

If you need to store data in session, use Movim’s Session class rather than PHP’s session. The class provides you the following methods.

Movim uses caching heavily in order to minimise load-time. Depending on how your widget works, it might be convenient for you to cache parts of it, or even the whole of its html output, rather than regenerate it every time.

Movim’s cache is user-specific. So you don’t have to worry about your cached data being accessible to others.

Movim’s Cache provides the following methods:

Here is an example of how to use Cache in its two different forms:

$cache = Cache::create();

// Storing some object.
$cache->handle('foo', 'bar', 'baz');

// Retrieving data
list($bar, $baz) = $cache->handle('foo');

// Using the shorthand
Cache::c('foo', $bar);

// Usual cache routine
if(!$bar = Cache::c('foo')) {
    Cache::c('foo', $bar);
}