From TomatoCMS Documentation

Widget is most important part of TomatoCMS. All web pages build by TomatoCMS was composed by widgets. This article describe structure of widget files as well as how to develop a widget from scratch.

The following guide will help you have to build a widget called Feed from utility module. This widget showlatest entries from given RSS channel.

Step 1: Widget folder structure

Each widget have to belong to one module. The widget folder have to be located at the path
Root_TomatoCMS_Directory/app/modules/Name_Of_Module/widgets/Name_Of_Widget.
In this example, the feed widget folder have the path as follow:

Each widget consist of at least 5 files:

- about.xml This file describe about widget

- config.phtml Used to display when user configure widget

- lang.en_US.ini (or something like lang.xx_YY.ini): Language file

- show.phtml Output of widget

- Widget.php The controller of widget

Step 2: Widget files

a) about.xml Widget introduction file:

01	<?xml version="1.0" encoding="UTF-8"?>
02	<!DOCTYPE widget SYSTEM "http://schemas.tomatocms.com/dtd/widget_about.dtd">
03	<widget>
04	  <name>Feed</name>
05	  <title>Feed</title>
06	  <module>utility</module>
07	  <description>Show entries from RSS channel</description>
08	  <thumbnail></thumbnail>
09	  <author>TomatoCMS</author>
10	  <email>dev@tomatocms.com</email>
11	  <version>1.0</version>
12	  <license>free</license>
13	  <params>
14	    <param name="url">
15	      <description>Feed URL</description>
16	    </param>
17	    <param name="title">
18	      <description>Title of feed box. If you want to display the title taken from feed URL,
19	      don't set value for this variable.</description>
20	    </param>
21	    <param name="limit">
22	      <description>Number of entries displayed</description>
23	    </param>
24	  </params>
25	</widget>

- Line 2: DTD format of file

- Line 4: Name of widget. Lower case of this name have to be the same as name of widget folder.

- Line 5: Title of widget. This title will be shown at the head section of widget in Layout Editor.

- Line 6: Name of module which the widget belong to

- Line 7: Description of widget. This will be shown in Layout Editor.

- Line 8: URL of thumbnail that describe widget

- Line 9: Author name

- Line 10: Email address used to contact with author

- Line 12: License information

- Line 13 to 24: Parameters information including name and description of parameters.

b) Widget.php This file work as controller class of a widget.

The class have to extend from Tomato_Core_Widget class and override _prepareShow() method:

01	class Tomato_Modules_Utility_Widgets_Feed_Widget extends Tomato_Core_Widget {
02	  protected function _prepareShow() {
03	    $url = $this->_request->getParam('url');
04	    $entries = Zend_Feed::import($url);
05	     
06	    $limit = $this->_request->getParam('limit', count($entries));
07	    $this->_view->assign('entries', $entries);
08	    $this->_view->assign('limit', $limit);
09	 
10	    $title = $this->_request->getParam('title');
11	    $title = ($title == null || $title == '') ? $entries->title() : $title;
12	    $this->_view->assign('title', $title);
13	  }
14	}

- Line 3, 6, 10: Get the input parameters

- Line 4: Use Zend_Feed to get the latest entries

- Line 7, 8, 12: Assign the variables to view

c) lang.en_US.ini The language file in INI format.

1	[config]
2	config_enter_url = "URL:"
3	config_enter_title = "Title (leave empty if you want to get title from above URL):"
4	config_enter_limit = "Number of entries will be shown:"

The language file usually consist of two sections: config and show. In this case, we have not show section.

The config section is used in configuration mode (config.phtml file) and show section is used in preview mode (show.phtml file).

d) config.phtml Content of this file will be shown when user configure widget in Layout Editor tool.

1	<?= $this->translates['utility_feed']->_('config_enter_url'); ?><br />
2	<input type="text" class="t_widget_input" name="url" style="width: 100%" /><br />
3	<?= $this->translates['utility_feed']->_('config_enter_title'); ?><br />
4	<input type="text" class="t_widget_input" name="title" style="width: 100%" /><br />
5	<?= $this->translates['utility_feed']->_('config_enter_limit'); ?><br />
6	<input type="text" class="t_widget_input" name="limit" style="width: 50px" value="10" />

- Line 1, 3, 5: We can use the data from language file in following format:

1	$this->translates['utility_feed']->_('config_enter_url'); ?>

where:

   * utility_feed is the string created by joining module name with widget name, seperated by _
   * config_enter_url is the key from language file

- Line 2, 4, 6: All input fields that present widget parameters have to be set CSS class t_widget_input.

This is to Layout Editor indicate data from which fields should be stored.

e) show.phtml Output of widget, will be shown at the front end.

01	<div class="t_g_box t_g_bottom">
02	  <h2><?= $this->title; ?></h2>
03	  <?php if (count($this->entries) > 0) : ?>
04	  <ul class="t_utility_feed t_g_top">
05	    <?php foreach ($this->entries as $entry) : ?>
06	    <li class="t_g_bottom">
07	      <b><a href="<?= $entry->link(); ?>"><?= $entry->title(); ?></a></b><br />
08	      <span><?= $entry->pubDate(); ?></span><br />
09	      <?= $entry->description(); ?>
10	    </li>
11	    <?php endforeach; ?>
12	  </ul>
13	  <?php endif; ?>
14	</div>

- Line 2, 3, 5: Get the value of variables which has been assigned values from controller class.

Now, go to the Layout Editor, click on Widget tab, select the utility module from the left side, drag the feed widget from right side and drop it to container, you will see the output rendered from config.phtml file:

Enter http://feeds.feedburner.com/ZendDeveloperZone to URL text box and Zend Developer Zone to Title text box.

Click on the Preview button to see the output rendered from show.phtml file:

Well done!

We have just created feed widget. It is easy to develop and maintain, isn't it?