Developing Modules for Vivvo

With version 4.0 and later, the functionality of Vivvo can be extended through a modular interface. This allows for many different extensions to the software to be developed and made available to users, and without bloating the code base. This will also attract more developers to the project given that module development is a relatively small, yet effective, undertaking.

This document is targeted for developers and attempts to explain how to develop a module by walking through a simple example.  

Vivvo modules interact between VTE and Vivvo Objects. For general information on Vivvo modules, please refer to Vivvo Modules guide section.

Modules in Vivvo are simple PHP classes used to pull needed data from database, or other resources into template. Retrieved data is then properly formatted using VTE code.

Todo…

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.

The purpose of this primer is to make XML to template pipe module using simplexml (PHP5).

 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 communicate 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.

generate_output() receives $params array with almost anything VTE can gather from template.

$this→set_template($params); - sets 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 with this in your module.

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

Please refer to Registering Modules document on how to register a Vivvo module.

For this example we will use the data from Audioscrobbler - http://ws.audioscrobbler.com/1.0/artist/Metallica/toptracks.xml

Putting it to some use:

<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>

developing_modules_primers.zip