Anatomy of a Widget

Widgets

To make the development of the interface and its modularity easier, all the pages inside Movim are made of modules called "Widgets". They make use of all the features of the heart of Movim.

Execution environment

All the widgets are stored in the app/widgets/ directory. They are loaded in the views through the widget() method. Here is an example of a view.

<nav>
    <?php $this->widget('Navigation');?>
    <?php $this->widget('Presence');?>
</nav>

<main>
    <?php $this->widget('Header'); ?>
    <section>
        <div>
            <?php $this->widget('Chats');?>
            <?php $this->widget('Rooms');?>
        </div>
        <?php $this->widget('Upload');?>
        <?php $this->widget('Chat');?>
    </section>
</main>

As you can see, the widgets have to be declared where they will have to appear. If they are declared outside of the "main" block, they will be seen as floating and won't be properly positioned in the page.

You can find these views in the app/views/ directory.

Declaration

You will find a directory for each widget. The name of the directory is the name of the widget. The complete structure of the widget is defined in a PHP file which will be explained further in the next parts.

class Explore extends \Movim\Widget\Base 
{
    function load()
    {
        $this->addcss('explore.css');
        $this->addjs('explore.js');
    }

    function display()
    {
        $this->view->assign('contacts', $this->prepareContacts());
        $this->view->assign('servers', $this->prepareServers());

        $jid = $this->user->getLogin();
        $server = explode('@', $jid);
        
        $this->view->assign('myserver', $this->route('server', $server[1]));
    }

    function ajaxSearchContacts($form) 
    {
        $html = $this->prepareContacts($form);

        $this->rpc('MovimTpl.fill', '#contactsresult', $html);
    }

    …
}

Each widget inherits from the Widget\Base class. Widget\Base contains all the methods to declare and integrate the module in Movim in terms of interface, event management or additional files loading

load

This method is mandatory. It is called when the widget is loaded in order to specify details about the execution of the module in its environment.

addcss('file.css')

This method lets you give a specific CSS file for the module to load with the widget. The file will have to be in the directory of the module.

addjs('file.js')

Same as for addcss but for Javascript files.

registerEvent('event_key', 'method')

This method lets you subscribe the widget to the events launched by Moxl when it receives a packet. The second parameter indicates which method is called in reaction to the registered event.

During the development and optimize performances, registered events are only considered after the user reconnects.

display

This method lets you declare elements to be added in the view when the widget is loaded. It's not mandatory to declare it.

Model-View-Controller

Each Movim widget behaves like a sub MVC application.

Models

Models data are loaded from the Models you declared in Movim (see the Modl page).

The PHP file of the Widget can be seen as the Controller which will be the link between data and the view.

View

In order to declare the interface in our widget we will have to create a template file with the name of the widget (lowercase) followed by the .tpl extension. With the Explore widget as an example, we would have to create a template file called explore.tpl.

The view will be used in the controller via the view attribute. Therefore you will be able to add your values in it with a call to the assign('key', $value) method.

Movim uses the RainTPL library as a link between the view and the controller. To know more about this library, you can read its documentation.

Here is an example of a view following that system.

<div id="server_result">
    <a class="button color purple oppose icon search" href="{$myserver}">
       {$c->__('Discover my server')}
    </a>
    <h2>{$c->__('Discussion Servers')}</h2>
    {$servers}
</div>

<div>
    <h2>{$c->__('Last registered')}</h2>

    <div id="contacts_result">
        {$contacts}
    </div>
</div>

Movim also adds three features to make the view coding easier.

• The $c->__('locale.key') method lets you add a string which will be translated by the internationalization system
• The $c->route('page', $parameters) method lets you generate a link to another page. It can take a simple string or an array of strings as a parameter
• The $c attribute lets you call a method of the controller

Controller

The $c->route() method of the view can also be called in the controller by using $this->route().

Call to the Controller from the View

You can execute a method of the controller from the view by using $this->call('ajaxMethod', $params). The first parameter is the name of the method to call, the others are the parameters of the method to call.

All the methods of the controller which can be called from the view have to have ajax at the beginning of their name.

Call to the View from the Controller

RPC, for Remote-Process-Call, lets you directly call Javascript methods loaded in the browser from the server. Movim will automagically generate the calls and pass on parameters.

This call is done by using $this->rpc('javascript_function', $param1, $param2 …).