movim/app/assets/documents/movim.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@documentencoding UTF-8
@setfilename movim-reference.info
@settitle movim-reference
@setchapternewpage on
@c %**end of header

@set VERSION 0.2
@set UPDATED 28 May 2011

@copying
This manual documents Movim (version @value{VERSION}, @value{UPDATED}).

Copyright @copyright{} 2009-2011 MOVIM project.
@sp 1
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
Texts.  A copy of the license is included in the section entitled ``GNU
Free Documentation License''.
@end quotation
@end copying

@titlepage
@title MOVIM Reference Manual
@subtitle version @value{VERSION}, @value{UPDATED}
@vskip 4cm
@center{@image{movim, 15cm}}
@author Guillaume Pasquet, Timothée Jaussoin
@c Copyright page
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage


@contents

@ifnottex
@node Top
@top MOVIM

This is Movim @value{VERSION}'s manual.
@end ifnottex

@menu
* foreword:: What this document is all about
* introduction:: What is Movim and how to use this document
* structure:: A description of Movim's internals
* Widgets API:: Documentation of the widget's API
* MovimRPC:: The specification of Movim's remote procedure call
@end menu

@node foreword
@chapter Foreword
Movim is an XMPP-based communication platform. It uses a widget-based UI
system. A widget is a combination of server-side and client-side scripts that
interact though a custom xmlrpc protocol.

This document describes the principles on which Movim is built, and the API to
build new widgets.

@node introduction
@chapter Introduction
Movim's core is designed to ease the implementation of XMPP web-based clients,
using massively asynchronous javascript and abstracting XMPP calls into an
events-based API.

The widgets API doesn't only provide the necessary abstraction and framework to
communicate through XMPP, it also features a javascript abstration system that
lets you write as little javascript as possible. Moreover, widgets can embed
their own resources --- pictures, css, javascript.

@section Requirements
Movim runs on any web server with PHP and Curl. The detailed requirements are:

@itemize @bullet
@item
PHP5.3 or greater with the Curl, JSON, SimpleXML and SQLite3 extensions.
@item
A web server: apache, lighttpd (Note that other web servers should work, with
the possible exception of IIS, which hasn't been tested.)
@end itemize

An XMPP web server with Bosh is also necessary, but you don't need to install
one, you can use and existing server. We provide such a server at
@url{movim.eu}.

@section Getting Movim
Movim may be downloaded from @url{http://www.movim.eu}.

You can also get the latest development version on our git branch at
@url{http://gitorious.org/movim}. Be advised that this version is not stable and
in fact it isn't even guaranteed to work.

@section Installing Movim
After downloading the Movim archive, simply extract it somewhere in your
web server's root directory. You will need to give read/write rights to the
webserver on the folder where Movim is installed.

You should see the installer when you visit your Movim folder from your web
browser. Follow the steps.

Then you should be able to log in on the website's interface with your XMPP
credentials.

Please note that not every XMPP server will work with Movim. Your server needs
to have Bosh enabled for this. You can register an account on the server we
provide @url{movim.eu} to try out Movim.

@section Helping out
Movim is Free software under the AGPL license. You can check out the latest
code at @url{http://gitorious.org/movim}. Feel free to send in merge requests if
you want to lend a hand.

All bug reports and feedback are welcome at
@url{http://codingteam.net/project/movim}. You can  also help us translating
Movim so more people may benefit from our Free social network (on the same
website).

@node structure
@chapter Internal structure
Understanding Movim's internals isn't necessary to use it. However, it may
help finding out problems and developing more efficiently.

Movim is consists of a widgets system and an XMPP abstration that
communicate together through an asynchronous event handler. This is all
triggered by a controller, which is loaded depending on the page you visit.

@section XMPP connection
The XMPP connection is managed by the JAXL library. It abstracts the raw sending
and receiving of XML messages. Each message is handled and pops up as an
event.

@section Widgets
Widgets are small pieces of software that plug into Movim to provide extra
ability to the system. These are mostly graphical, and generate ajax code
automatically.

Movim comes with several widgets. These sit in the @file{lib/widgets}
directory. User-defined widgets should be in the @file{widgets} directory. Note
that user-defined widgets always shadow the system widgets.

Widgets can declare ajax functions and XMPP event handlers in order to interact
with their GUI part and the XMPP subsystem. @xref{Widget API} for more
information.

Note that almost everything in Movim is a widget. Even things like the menu and
the configuration panel. One notable exception is the login page, which is
mostly static.

@section Events manager
The XMPP connection is not aware of the widgets, nor is it able to access
them. However, the event manager knows what widgets are loaded on the client's
interface at any time. When the XMPP connection triggers an event in the event
manager, it loops through all the loaded widgets and executes all handlers that
are attached to this event.


@node Widget API
@chapter Widget API
Widgets inherit from the @emph{WidgetBase} base class. The base class automagically
generates ajax calls and javascript functions for you.

The basic template of a Movim widget is as follows:

@cartouche
@verbatim
class MyWidget extends WidgetBase
{
    function load()
    {
        $this->registerEvent('incomemessage', 'onIncomingMessage');
    }

    function onIncomingMessage($data)
    {
        RPC::call('movim_prepend',
                       'chatMessages',
                       RPC::cdata($data['message']));
    }

    function build()
    {
        ?>
        <div id="chatMessages">
        </div>
        <?
    }
}
@end verbatim
@end cartouche

Note that the constructor must not be shadowed. Instead the parent class
provides a @code{load()} function that is called right at the end of the
parent constructor.

Event handlers must be defined into @code{load()}.

The @code{build()} function is called when the widget is being written onto the
interface. That's typically where you should put your HTML code.


@section Events
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.

@subsection Handling events
An event handler is a public method that only takes one parameter:
@code{$data}, which usually is an array that contains the data returned by the
XMPP server.

Your handlers must be registered in @code{load()} using the method:

@cartouche
@verbatim
WidgetBase::registerEvent($eventType, $handler)
@end verbatim
@end cartouche

@code{$handler} is a the name of the method as a string, and @code{$eventType}
is the name of the event as a string.

@subsection Event types
The XMPP subsystem currently raises the following events:

@table @code
@item postdisconnected
      Event that is triggered immediately after the account has been
      disconnected on the user's request.
@item incomingemptybody
      A message that comes in without body. This is typically a presence ping.
@item myvcardreceived
      Your vcard was received.
@item vcardreceived
      The user's vcard was received. @code{$data} contains the vcard as a base64
      encoded string.
@item rosterreceived
      The roster's list was received. @code{$data} is an array of groups and
      users.
@item incomeactive
      The contact is currently looking at his message list.
@item incomecomposing
      The contact is writing a message.
@item incomemessage
      A new message was received (contained in @code{$data}).
@item incomeoffline
      A contact as gone offline.
@item incomeaway
      A contact is now marked as away.
@item incomednd
      A contact is now marked as @emph{do not disturb}.
@item incomeonline
      A contact is now online.
@item serverdisconnect
      The server has gone offline.
@end table

One additional event type is availble: @code{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.

@node MovimRPC
@section MovimRPC
Movim's javascript and PHP parts communicate through a custom xmlrpc
protocol. It is implemented in the class @code{MovimRPC} on the PHP side.

MovimRPC exposes two static functions to the widget:

@table @code
@item RPC::call(funcname, ...)
      Calls the javascript function @emph{funcname} with the rest of arguments.
@item RPC::cdata(text)
      Packs text into a cdata container. This is useful when passing through
      strings containing messy characters (like HTML).
@end table

You can define your own javascript functions on a per-widget basis, or use one
of the standard functions (@xref{Standard javascript callbacks}).

@node Standard javascript callbacks
@subsection Standard javascript callbacks
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).

@table @code
@item movim_append(target, string)
      Appends @code{string} to the html element with ID @code{target}.
@item movim_prepend(target, string)
      Prepends @code{string} to the html element with ID @code{target}.
@item movim_fill(target, string)
      Fills @code{string} to the html element with ID @code{target}.
@item movim_drop()
      Doesn't do anything.
@end table

@node ajaxcalls
@section Ajax calls
Any method defined in your widget that starts with @code{ajax} will have a
javascript ajax call automatically generated.

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

@cartouche
@verbatim
WidgetBase::callAjax($funcname, ...)
@end verbatim
@end cartouche

@code{$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

@code{ajaxMyfunction($param)}

you can call it with

@code{$this->callAjax('ajaxMyfunction', "'myparam'")}.

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

@cartouche
@verbatim
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');?>"/>
       <?
    }
}
@end verbatim
@end cartouche

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 @code{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:

@cartouche
@verbatim
WidgetBase::call($funcname, $callback, $target, ...)
@end verbatim
@end cartouche

@node widget-resource
@section Widget resource
Widgets can come along with their own resources, in particular their CSS and
javascript.

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

@cartouche
@verbatim
WidgetBase::addjs($jsfile)
WidgetBase::addcss($cssfile)
@end verbatim
@end cartouche

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

For resources, you can use the function:

@cartouche
@verbatim
WidgetBase::respath($file, $fspath = false)
@end verbatim
@end cartouche

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

@node IWC
@section Inter-Widget Communication
Widgets can communicate at two different levels. They can communicate through
the server using MovimRPC, but this is an awkward route for messages need to get
down to the server, then up to the other widget. Another manner is to use the
IWC.

The IWC is basically a javascript-level event manager. In order to use it, your
widget can either add event handlers so that others can communicate with it, or
it can send events to other widgets.

This means that you will not be able to use IWC from PHP. You'll need to add a
javascript resource file along with your widget and define the handlers in it.

Handlers are defined with the function @code{movim_add_event_handler(event_type,
func)}. An example of it could be:

@cartouche
@verbatim
function bar() {
  // Do things
}
// Adding handler
movim_add_event_handler('foo', bar);
@end verbatim
@end cartouche

You may however trigger events from anywhere, including the widget's body with
the function @code{movim_events_emit(event_type)}.

@cartouche
@verbatim
<input type="button" onclick="movim_events_emit('foo')" />
@end verbatim
@end cartouche

@node session
@section Session
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.

@table @code
@item static Session::start($name)
      Starts a session container named $name. Returns the session handle.
@item Session::get($varname)
      Retrieves the value of $varname.
@item Session::set($varname, $value)
      Sets the value of $varname to $value.
@item Session::remove($varname)
      Deletes $varname from the session.
@item Session::delete_container()
      Deletes the physical storage of the container.
@item static Session::dispose($name)
      Deletes the container $name along with its physical storage.
@end table

@node cache
@section Cache
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:

@table @code
@item static Cache::create()
      Gets a cache handle.
@item Cache::handle($key, ...)
      Retrieves or stores one or more objects depending on the way it's
      called. If only $key is provided, handle() will return the corresponding
      cached object. If one or more extra objects are provided, they are cached
      under $key.
@item static Cache::c($key, ...)
      Shorthand for the two previous functions.
@end table

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

@cartouche
@verbatim
$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);
}
@end verbatim
@end cartouche

      
@node MovimRPC spec
@chapter MovimRPC specification
Movim's interface is highly dynamic and composed of two parts, the server-side
written in PHP that provides the XMPP connection and the Javascript-side that
provides the GUI.

Both systems communicate through Ajax. The javascript interface keeps polling
the server for new calls on the url:

@url{http://mymovim.tld/jajax.php?do=poll}

Whenever an event occurs, a MovimRPC call is sent though this interface. The GUI
also communicates directly with the server through the same protocol.

@section Function calls
MovimRPC consists in sending XML-formatted strings that describe a function
call. Both communicating systems need to be aware of each other's functions set
as no return is available on a function call.

Instead of returning data after a function call, the called system triggers a
movimRPC call to the calling system, feeding it the appropriate data as
paramaters.

Messy strings parameters (e.g. those containing HTML code) need to be enclosed
in CDATA markups.

One MovimRPC document can contain more than one function call. All function
calls need to be enclosed in @code{<movimcontainer>} tags. Function calls are
defined with the @code{<funcall>}. Each function parameter is enclosed in
@code{<param>} tags.

Function calls must have a @code{NAME} parameter, and accept a @code{WIDGET}
parameter.

Here is an example of a call to the function @code{myfunc} of the widget
@code{MyWidget} with the relevant parameters.

@cartouche
@verbatim
<?xml version="1.0" encoding="UTF-8" ?>
<movimcontainer>
  <funcall name="myfunc" widget="MyWidget">
    <param>foo</param>
    <param>bar</param>
  </funcall>
</movimcontainer>
@end verbatim
@end cartouche

@section Parameters
The parameters passed to a function aren't typed. The required type needs to be
known by the caller.

Arrays can be passed within parameters. Arrays may be associative or mixed or
not. They are declared within @code{<array>} tags. Each element in the array is
enclosed by @code{<arrayelt>} tags. Elements can be associated to a key with the
@code{NAME} parameter.

An example of two function calls with an associative array.

@cartouche
@verbatim
<?xml version="1.0" encoding="UTF-8" ?>
<movimcontainer>
  <funcall name="myfunc" widget="MyWidget">
    <param>foo</param>
    <param>bar</param>
  </funcall>
  <funcall name="toto">
    <param>foo</param>
    <param>
      <array>
        <arrayelt name="elt1">1</arrayelt>
        <arrayelt name="2">associative</arrayelt>
        <arrayelt>sequential</arrayelt>
      </array>
    </param>
  </funcall>
</movimcontainer>
@end verbatim
@end cartouche

@node license
@comment  node-name,  next,  previous,  up
@chapter GNU Free Documentation License
@include fdl.texi

@bye