Support Center

Creating a Simple Widget

Last Updated: Nov 13, 2014 12:16PM PST
In this tutorial, we will be creating a basic module named, 'Fruit', which will display a list of fruit and their colors. It will have an optional argument (color), which will return only fruit having that color.

Let's begin:

Step 1. Create a folder in /livewhale/client/modules with the name of your new module. Since our example module is "Fruit", we will name the directory /fruit 

Step 2. We will add a widget file to the newly created directory. The filename must match the appropriate naming conventions. In this case, our module, Fruit, will have this filename: public.widget.fruit.php

We will go through the structure of the public.widget.fruit.php file below:

First, we must register our widget in the CMS.

The first code block below will register our widget module. Again, it's important to stay consistent and follow the naming conventions. Where you see the word "fruit", is where you should match your module name

       'title'=>'Fruit',    //the widget's name
       'widget'=>array(   //configure the widget attributes
            'item_url'=>'/fruit_details.php',   // this is the url to the fruit details template page for demo purposes but typically set in /livewhale/client/public.config.php
            'format'=>'<span class="lw_fruit_name">{name}</span> (<span class="lw_fruit_color">{color}</span>) ',   //the format of each fruit result 
      'handlers'=>array('onLoad', 'onDisplay', 'onDetails')   // add the widget function handlers
Next, we need to define our widget class and write our function handlers that we defined in our registration above (onLoad(), onDisplay(), onDetails()).
class LiveWhaleWidgetFruit { // the fruit widget class

   /* The following (optional) handler runs once when the widget type is first initialized. It would connect to a data source, or initialize anything needed by any number of fruit widgets occurring on this page. Example: Let's create a fake data source as a global array. */
      public function onLoad() { // initializes the widget
          $this->fruit=array( // create an array of fruit to use as a data source
             1=>array( 'title'=>'Apple', 'color'=>'red' ),
             2=>array( 'title'=>'Orange', 'color'=>'orange' ),
             3=>array( 'title'=>'Kiwi', 'color'=>'green' ),
             4=>array( 'title'=>'Banana', 'color'=>'yellow' ),
             5=>array( 'title'=>'Strawberry', 'color'=>'red' ),
             6=>array( 'title'=>'Lemon', 'color'=>'yellow' ),
             7=>array( 'title'=>'Pear', 'color'=>'green' ),
             8=>array( 'title'=>'Cherry', 'color'=>'red' )
    } //end of onLoad()

   /*  onDisplay() is called for each instance of a fruit widget, it constructs its content, and then returns it to the page in place of the widget syntax. See fruit_widget.php for an example in Step 4.*/

   public function onDisplay(){
          $output='';   // initialize the output

         // check for data source
         if (!empty($this->fruit)) { 
            //loop through results
            foreach($this->fruit as $key=>$val) {
                     // show either all fruit or fruit by color 
                    if (!isset($_LW->widget['args']['color']) || $_LW->widget['args' ]['color']==$val['color']) {

                        // set variables for display (MUST be valid XHTML!)
                               'name'=>'<a href="'.$_LW->REGISTERED_WIDGETS['fruit']['widget']['item_url'].'?id='.(int)$key.'">'.$val['title'].'</a>',

                       // add each result to widget output  
            }; //end foreach

           // add results to the widget
          if (!empty($_LW->widget['results'])) { 

          // get the widget's output
      }; //end if

       // return output in place of widget
       return $output;     } //end of onDisplay()

    /*  onDetails() runs once when the fruit template is accessed. It provides global variables for use in the page template. See fruit_details.php template for an example in Step 3. */

  public function onDetails(){
       global $_LW;
        // if id GET var not passed in, or id is invalid then redirect to another page
       if (!isset($_LW->_GET['id']) || !isset($this->fruit[$_LW->_GET['id']]))          
          // take some alternative action here (for example, a redirect)
           die(header('Location: /some-page.php')); 

      // expose fruit title to template
       // expose fruit color to template‚Äč
  } //end of onDetails()
} // end  widget class


Step 3. Set up your module details template. This file lives within your webroot of your domain ( In this example, when we registered our widget, we defined our item_url as /fruit_details.php. 

Below is an example of our fruit details template, fruit_details.php. If you are familiar with your news.php or events.php details template in LiveWhale, this is the same type of file that triggers the details handler and displays the information. 
<?php require $_SERVER['DOCUMENT_ROOT'].'/livewhale/frontend.php';?>

<!--   This file demonstrates a template for the fruit widget. To trigger the fruit details handler, add the fruit details widget before the html tag, and then use the fruit variables however you like in the template with XPHP variables as done below within the <body> tags.  -->

<widget type="fruit_details" priority="high"/>

           <h3> Fruit Details Template </h3>              

            <p><strong>Title:</strong>  <xphp var="fruit_title"/> </p>
           <p><strong>Color:</strong> <xphp var="fruit_color"/> </p>


Step 4. So far, we have registered a widget, built handlers to gather and setup data, and have a template to display the data details. Now, it's time to call your widget. 

Below the example file, fruit_widget.php, calls our new widget. This file can live anywhere under your webroot and the name of the file is arbitrary, it doesn't have to follow any special naming conventions. This file solely demonstrates how we simply call our new module, fruit.
<?php require $_SERVER['DOCUMENT_ROOT'].'/livewhale/frontend.php';?>

         <p>Test 1: List all the fruit</p>
          <widget type="fruit"/>

          <p>Test 2: List only red fruit</p>
          <widget type="fruit">
              <arg id="color">red</arg>
‚Äč          </widget>
Step 5. Complete the module registration by visiting the login page ( By visiting the login page, LiveWhale will scan for newly added modules and register them. 

Download the complete attached source code below.
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found