Custom Vivvo modules

A primer and explanation on creating custom Vivvo modules.

Keep your custom modules in your own file(s), not vivvo_box.php, and any changes or custom mods you make to Vivvo will not be affected during upgrades or patches.

Vivvo modules interact between VTE and Vivvo objects. For more information on Vivvo modules in general, please refer to Developer guide section.

In this primer, we shall make our own my_boxes.php file (i.e. inside vivvo root). We will keep our custom modules in this file.

Making module:

For this HOWTO we will make XML to template pipe module using simplexml (PHP5).

PHP Code:

 class box_xml_grabber extends module {
        var $data;
       
        function object2array($object){
            $return = NULL;
            
            if(is_array($object)){
                foreach($object as $key => $value){
                    $key = str_replace('@', '_', $key);
                    $return[$key] = $this->object2array($value);
                }
            }else{
                $var = get_object_vars($object);
                if($var){
                    foreach($var as $key => $value){
                        $key = str_replace('@', '_', $key);
                        $return[$key] = $this->object2array($value);
                    }
                }else{
                    return strval($object); // strval and everything is fine
                }
            }
       
            return $return;
        }
       
        /**
         * Generate box output
         *
         * @param array $params Parameters
         */
        function generate_output($params){
            $this->set_template($params);
            if ($params['url'] != ''){
                $data = @simplexml_load_file($params['url']);
                if ($data){
                    $this->data = $this->object2array($data);
                    $this->_template->assign('xml_data', $this->data);
                }   
            }               
        }
    }

Our new module extends Vivvo module class and inherits all necessary methods and properties from it to comunicate with Vivvo core.

Main method you need to define in your custom module is generate_output. This method will be called when template engine encounters module signature.

Note: Vivvo creates new instance of modules for each module template engine calls for.

generate_output receives $params array with anything VTE can gather form template.

$this->set_template($params); - set local template object whit template string from parent template (vte:box/vte:temlpate instruction) or template load file (vte:load/@template instruction).

$this->_template->assign('xml_data', $this->data); - local template is accessible trough $this->_template variable. In this case it binds parsed XML data to local template {xml_data} tag.

You can do pretty much anything whit in your module (try analyzing your lib/vivvo/box/vivvo_box.php).

Registering module:

Last thing you need to do when making new module is to register it in Vivvo configuration table:

Code:

INSERT INTO `tblConfiguration` ( `id` , `variable_name` , `variable_property` , `variable_value` , `module` , `domain_id` , `reg_exp` )
VALUES (NULL , 'box_xml_grabber', 'class_name', 'box_xml_grabber', 'modules', '1', NULL),
(NULL , 'box_xml_grabber', 'file', 'my_boxes.php', 'modules', '1', NULL);

First SQL insert tells vivvo that module named 'box_xml_grabber' uses box_xml_grabber class and second that that class is located in my_boxes.php (path relative to vivvo root).

This box module can be used generally to fetch xml data. It relies on simplexml extension (PHP 5) and remote fopen being allowed.

Using module:

For my example I will get data from audioscrobbler http://ws.audioscrobbler.com/1.0/art.../toptracks.xml

Putting it to some use:

Code:

<vte:box module="box_xml_grabber">
    <vte:params>
        <vte:param name="url" value="http://ws.audioscrobbler.com/1.0/artist/Metallica/toptracks.xml" />
    </vte:params>
    <vte:template>
        <div class="box">
            <div class="box_title_holder">
                <div class="box_title">
                    <vte:foreach item="attr" from="{xml_data[_attributes]}"><vte:value select="{attr}" /></vte:foreach> @ last.fm
                </div>
            </div>
            <div class="box_body">
                <div class="box_content">
                    <ul>
                        <vte:foreach item="track" from="{xml_data[track]}" loop="10">
                            <li><vte:value select="{track[name]}" /> (<vte:value select="{track[reach]}" />)</li>
                        </vte:foreach>
                    </ul>
                </div>
            </div>
        </div>
    </vte:template>
</vte:box>