Widgets can basically be thought of as easily customizable blocks.  The main difference between standard blocks and widgets is that widgets can be added to CMS pages through the WYSIWYG editor and they can easily accept parameters, also defined through the WYSIWYG.  Thus a non-programmer can add quasi-dynamic content to their CMS pages, hurrah!

You should reference previous articles if you want more details about creating custom Modules and Blocks.

As an example I’m going to build a super simple slideshow widget called “Glider”.  It’s going to be a widget that takes four static block_id(s) as parameters and then displays each static block, in succession, as a slideshow.  If you let your imagination work a little you should be able to see some cool possibilities for such a thing, given that you extend it a little.

I’m using static blocks as the source material for each slide because this would allow a content manager to change out the content of a slide by either editing the static block that contains the content or by editing the block id being passed to the widget.  Either way it’s manageable through the interface.

Also note that the template (presentation layer) is going to be statically defined in this example, but you could easily make that a parameter and create multiple templates for the content manager to choose from!

Finally, I’ve used jQuery to build the actual slideshow.  I’m not going to go into very much detail about the presentation of the slideshow as that’s not really the focus of this article.  Feel free to write in if you want to see the details on how to implement jQuery (or any other script).

First let’s setup the Module:

/app/etc/modules/Spinonesolutions_WidgetGlider.xml

<?xml version="1.0"?>
 <config>
 <modules>
 <Spinonesolutions_WidgetGlider>
   <active>true</active>
   <codePool>local</codePool>
   <depends>
     <Mage_Cms />
   </depends>
 </Spinonesolutions_WidgetGlider>
 </modules>
 </config>

/app/code/local/Spinonesolutions/WidgetGlider/etc/config.xml

<?xml version="1.0"?>
 <config>
 <modules>
 <Spinonesolutions_WidgetGlider>
   <version>1.0.0</version>
 </Spinonesolutions_WidgetGlider>
 </modules>
 <global>
 <blocks>
   <spinonesolutions_widgetglider>
     <class>Spinonesolutions_WidgetGlider_Block</class>
   </spinonesolutions_widgetglider>
 </blocks>
 </global>
 </config>

OK!  The next thing we need to do is define our widget’s interface.  To do that we create a widget.xml file inside our module’s “etc” folder.

/app/code/local/Spinonesolutions/WidgetGlider/etc/widget.xml

<?xml version="1.0"?>
<widgets>
<glider type="spinonesolutions_widgetglider/glider">
   <name>SpinoneSolutions: Glider</name>
   <description>Displays the given HTML Sections in a Glider Slideshow</description>
   <parameters>
     <section1>
       <required>0</required>
       <visible>1</visible>
       <label>Section1</label>
       <type>text</type>
     </section1>
     <section2>
       <required>0</required>
       <visible>1</visible>
       <label>Section2</label>
       <type>text</type>
     </section2>
     <section3>
       <required>0</required>
       <visible>1</visible>
       <label>Section3</label>
       <type>text</type>
     </section3>
     <section4>
       <required>0</required>
       <visible>1</visible>
       <label>Section4</label>
       <type>text</type>
     </section4>
     <template>
       <visible>0</visible>
       <value>widgetglider/banner.phtml</value>
     </template>
   </parameters>
</glider>
</widgets>

You can define any number of widgets in here.  We’re only creating one so I’ve only got a single entry, glider.

The type attribute tells Magento what class to use when instantiating objects.  I’ve set it as spinonesolutions_widgetglider/glider.  If you go back and inspect the config.xml and remember your Magento naming conventions you can surmise that this is going to cause Magento to try and instantiate an object of type Spinonesolutions_WidgetGlider_Block_Glider.  That class doesn’t exist yet so we should create it.

/app/code/local/Spinonesolutions/WidgetGlider/Block/Glider.php

<?php
class Spinonesolutions_WidgetGlider_Block_Glider extends Mage_Core_Block_Template
implements Mage_Widget_Block_Interface {
  const MAXSECTIONS = 4;
  public $sectionArr = array();

  protected function _construct() {
    parent::_construct();
  }

  protected function _toHtml() {
    for ($i=1;$i <= self::MAXSECTIONS;$i++) {
      if ($this->getData("section$i")) {
        $blockHTML = $this->getLayout()->createBlock('cms/block')->setBlockId($this->getData("section$i"))->toHtml();
        $this->sectionArr[$i] = $blockHTML;
      }
    }
    return parent::_toHtml();
  }
}

Let’s inspect the class from top to bottom.  The first thing to notice is that in the declaration it implements Mage_Widget_Block_Interface.  This is a requirement for Widgets.

Notice my constant MAXSECTIONS is set to 4, the same number of section parameters that I defined in widget.xml.  There’s probably some room for improvement here: one could probably figure out the number of parameters dynamically and then remove the constant.  That would make the widget more flexible for future uses.

I call the _construct function so that everything gets setup the way it’s supposed to.

Finally the real work gets done in _toHtml.  This function will be called automagically by Magento when it goes to render this object to the screen.

What I do is load up each block that gets passed into the widget and I stuff it’s HTML into an array element.  This way the widget can render any block, independently, by referencing a key in the array.

It’s not the classes job to do the rendering, that’s left to the presentation layer.  This class is just gathering everything that the presentation layer needs.

To move on with the tutorial we need to look back at our widget declaration in widget.xml.  I’m sure you noticed the last parameter template that I haven’t discussed yet.  Notice that the attribute visible is set to false.  What this parameter does is define the template that our widget is going to use for presentation.  My value is widgetglider/banner.phtml this template doesn’t exist by default so let’s create it.

/app/design/frontend/default/spinonesolutions/template/widgetglider/banner.phtml

<style>
.slideshow {
  position:relative;
}

.slideshow .items div {
  float:left;
  opacity:0.0;
  position:absolute;
  z-index:8;
}

.slideshow .items div.active {
  opacity:1.0;
  z-index:10;
}
</style>

<script>
function slideSwitch() {
  var active = jQuery('.slideshow .items .active');
  // use this to pull the images in the order they appear in the markup
  var next =  jQuery(active).next().length ? jQuery(active).next() : jQuery('.slideshow .items div:first');
  jQuery(next).css({opacity: 0.0})
  .addClass('active')
  .animate({opacity: 1.0}, 1000, function() {
    jQuery(active).removeClass('active');
  });

  jQuery(active).animate({opacity:0.0}, 1000, function(){
  });
}

// execute your scripts when the DOM is ready. this is mostly a good habit
jQuery('document').ready(function() {
  var active = jQuery('.slideshow .items .active');
  if ( active.length == 0 ) {
    active = jQuery('.slideshow .items div:first');
    active.addClass('active').animate({opacity: 1.0}, 1000);
  }

  jQuery(function() {
    setInterval( "slideSwitch()", 5000 );
  });
});
</script>
<div class="slideshow">
  <div class="items">
    <?php foreach($this->sectionArr as $key => $section) { ?>
    <div class="">
      <?php echo $section; ?>
    </div>
    <?php } ?>
  </div>
</div>

The first part of that path is determined by the theme that you’ve set in Configuration.

Inspecting this file the real takeaway is simply the foreach loop.  All it does it loop over the array that was defined in the Business Layer and output the HTML stored in each element.  The template file does all the presentation.

The reason for doing things this way is that one can easily envision some department manager coming to you and asking for another, different, presentation of the same data for some other location of your website.  Since you’ve done a good job of separating your layers all you have to do is make a new .phtml file, and then change the template parameter of your widget.xml file and viola, you’ve got a new presentation of your data.

That does it for the code, all we need to do now is build a little demo using the interface.

Load up the admin and navigate to CMS -> Static Blocks.  Create four static blocks and put an image file into each one.  If you hover your mouse over the row you’ll see the block_id.  Make note of these as you’ll need them for when you create the widget.  Mine are: 6,8,9,10.

Go to CMS -> Pages and create a new CMS page to hold the widget.  Alternatively you could add the widget to a preexisting page.  Switch to the Content Tab.  Click the add Widget icon to add your widget.

Choose your new widget from the dropdown menu.

Fill in the block_id(s) of your static blocks.

Hit Insert.

As a learning exercise click the “Show/HideEditor” button.

Notice what was generated!  It should be pretty similar to what’s in your widget.xml file.  As the smart and curious type the you are also realize that you can change these parameters right here.  Thus the widget.xml file serves a template for your widget, which can be customized later to suit your specific needs.

Ok, save your CMS page.  That’s it!

You can see my demo here.

As always, questions and comments welcomed!

Greetings!  This is installment number one of the the exiting Magento Custom Module series.  There’s basically two paths to the end of the fairytale:

Path 1: You follow this series and get down and dirty with Magento, learning a lot along the way.

Path 2: You go out and download the Module Creator (http://www.magentocommerce.com/wiki/custom_module_with_custom_database_table) and head straight to GO!

Your choice!

Note: Magento is an MVC application so I’m going to assume you have a basic understanding of MVC.  Also, Magento is built (I believe) on the Zend framework, so there’s some Zend specific syntax that I’m also not going to dive into.  Huzzzah!

The Problem:

You need to create a custom Module in Magento!  Why…?  Hell, I don’t know; you just do.  That’s enough of that, let’s get down to it.

The Solution:

All of your customizations need to go into the [root]\app\code\local folder.  This is where Magento expects to find them and it’s also a factor in maintaining your upgrade path.  When the next version of Magento is released you’ll be able to backup your “local” folder and blow away everything else.

Before we get too far into this let’s setup our development environment, go to:
Admin -> System -> Cache Management: Cache Control – All Cache = Disable

This will save you many hours of self-torture while you’re developing.

A couple of other developer settings that I’ve found helpful:
Admin -> System -> Configuration -> Developer: Debug – Profiler = yes
Log Settings – Enabled = yes

Now open up [root]\index.php and at the very end you’ll see three lines that are commented out; un-comment them and save.

Finally, turn SEO friendly URLs on:
Admin -> System -> Configuration -> Web: Search Engine Optimization – Use Web Server Rewrites = Yes

All of the URLs that I’ll be presenting as examples below assume that SEO friendly URLs are enabled.

Magento is now correctly configured for development so let’s dive into building a custom module.

Sample file structure:
[root]\app\code\local\{Namespace}\{Modulename}
[root]\app\code\local\{Namespace}\{Modulename}\controllers
[root]\app\code\local\{Namespace}\{Modulename}\etc
[root]\app\code\local\{Namespace}\{Modulename}\etc\config.xml
[root]\app\code\local\{Namespace}\{Modulename}\Helper
[root]\app\code\local\{Namespace}\{Modulename}\Helper\Data.php
[root]\app\code\local\{Namespace}\{Modulename}\Model
[root]\app\code\local\{Namespace}\{Modulename}\{Modulename}.php

{Namespace} is a user defined variable.  Basically it’s just a mechanism that allows the user to create disparate classes that would otherwise have the same names.
{Modulename} this is the name of your module.

For my examples I’m going to use “Spinonesolutions” as my namespace and “Helloworld” as my Module.  I’m not entirely sure if it matters or not, but as a general rule I always capitalize the first letter and leave the rest lower case.  Don’t use underscores in your names either, we’ll see why later.

controllers is where all the controllers go, crazy right?  I’ll get into the controller structure in another part of this series.  For now a sample will suffice.

<?php
//IndexController is the default controller
//EG: http://localhost/spinonesolutions/
//Notice there's no parameters being passed as a parameter (Nothing after trailing "/")
//IndexController will be called since it's the default.
//"spinonesolutions" is the frontname as defined in confg.xml
class Spinonesolutions_Helloworld_IndexController extends Mage_Core_Controller_Front_Action {
  //indexAction is the default Action for any controller
  function indexAction() {
    echo "indexAction";
    $helloworld = Mage::getModel("spinonesolutions_helloworld/helloworld");
    $helloworld->helloworld("helloworld");
  }
}

Data.php is just a helper file for the Magento internals, I’m not exactly sure what it does but it appears to be exactly the same in every module except for its class definition.

<?php
class Spinonesolutions_Helloworld_Helper_Data extends Mage_Core_Helper_Abstract {

}

Model holds all of the models for your module.  It’s customary to name your main model after your {Modulename}.  You’ll most likely have at least one model and if you browse through the Magento core you’ll notice that most modules contain many models.

<?php
class Spinonesolutions_Helloworld_Model_Helloworld extends Varien_Object {
  function __construct() {
    parent::__construct();
  }

  function helloworld($arg) {
    echo "<br>Hello World! My argument is : " . $arg;
  }
}

config.xml is where you connect all your code up to Magento.  There’s a lot of voodoo going on in here and I’m not entirely sure how it all works.  I might even write a full post on the config.xml as a forthcoming part of this series.

<?xml version="1.0" encoding="UTF-8" ?>
<config>
 <modules>
   <Spinonesolutions_Helloworld>
   <version>0.1.0</version>
   </Spinonesolutions_Helloworld>
 </modules>
 <frontend>
   <routers>
     <spinonesolutions>    <!-- I make this match my front name but I'm not sure it matters -->
       <use>standard</use>    <!-- Use standard routing as opposed to admin.  IE: frontend vs admin -->
       <args>
         <module>Spinonesolutions_Helloworld</module>    <!-- The module to search for controllers -->
         <frontName>spinonesolutions</frontName>    <!-- The first descriminator in the path.  "spinonesolutions" in http://localhost/spinonesolutions/ -->
       </args>
     </spinonesolutions>
   </routers>
 </frontend>
 <global>
   <models>
     <spinonesolutions_helloworld>    <!-- This is used when istanting your Model EG: Mage::getModel("spinonesolutions_helloworld/hellworld") -->
       <class>Spinonesolutions_Helloworld_Model</class>    <!-- That class to use when isntanting objects of type above. -->
     </spinonesolutions_helloworld>
   </models>
 </global>
</config>

That takes care of all the code needed in the module directory. There’s one more configuration file we need to create and it’s an exception to the local folder rule:
[root]\app\etc\modules\{Namespace}_{Modulename}.xml

<?xml version="1.0"?>
<config>
 <modules>
   <Spinonesolutions_Helloworld>
     <active>true</active>
     <codePool>local</codePool>
   </Spinonesolutions_Helloworld>
 </modules>
</config>

This file tells Magento that there’s a new module out there that it needs to load.  Alternatively, you can name your file [root]\app\etc\modules\{Namespace}_All.xml to tell Magento to load up all the modules in that namespace.

Once you have this file in place you can navigate to Admin->System -> Configuration -> Advanced and you should see your module enabled here.

You now have a functioning custom module, hurray!

Download the source – Helloworld

1. Part I : Custom Module
2. Part II : Models
3. Part III : Controllers
4. Part IV : Extending Models
5. Part V : Data Layer