The Render Function
Description
The render function (from Gadget and View) takes data that has been formatted and placed into protected and private members of the gadget and presents a representation of the data in a format that matches the format requested (usually HTML).
Output
The representation is usually output to the output buffer via calls to print, echo, and PHP escaping (<?…?>). However, there are more than a couple cases where render is expected to return a value that matches a value that can be read by the layout of the format that it is requested in. For example, RSS implementations require that a specific RSS-like hash be passed back to the layout. In order to know how to return data it is helpful to look at gadgets that are implemented in a way that specific to the format that you're intending to render for.
Output Example 1
From RiverGadget.inc implemented in RiverGuideBookGadget. Notice how the book list is gathered in act and iterated through in render(). The separation allows detection and handling of errors and alternate representations.
function render()
{
$c = $this->getPage()->getObjectRef("ConfigInfo");
if(!count($this->books)) return;
?>
<h2>Guidebooks</h2>
<div style='clear:both'>
<?
foreach ($this->books as $row )
{
if ($row['imgurl'])
{
$image = $row['imgurl'];
}
else
{
$image = $c->imgRoot . "/bookthumb.gif";
}
?>
<div style='float:left;width:200px'>
<a href="<?=$row['url']?>">
<img src="<?=$image?>">
<br>
<br>
<?=$row['title']?>
</a>
<br>
<?=$row['price']?>
</div>
<?
}
?></div><?
}
Output Example 2
Taken from RiverListView.inc in /formats/mapxml/views/. The view layout expects an array of JSON encoded objects with a member named 'geoMarker' with the prpopriatary (to the layout) object of CMapMarker. CMapMarker is defined in the root page for the format. RiverListView from other formats produce RSS or JSON-encoded data similiarly with the same river list.
<code>
function renderView()
{
$rivarr = array ();
foreach ($this->model->rivers as $river)
{
$rivername = $river['river'];
$lat = isset ($river['plat']) ? $river['plat'] : '0';
$lon = isset ($river['plon']) ? $river['plon'] : '0';
$marker = new CMapMarker();
$marker->lat = $lat;
$marker->lon = $lon;
$rurl = $this->getPage()->gadStatURL("RiverGadget", "detail", 'html',array (
"id"=>$river['id']
));
$gurl = $this->getPage()->gadStatURL("GaugeGadget", "view", 'html',array (
"id"=>$river['gaugeid']
));
$marker->comment = "<a href='$rurl'>$rivername</a><br/><a href='$gurl'>$river[level] $river[levadd] $river[units]</a><br/>Updated $river[updated]<br>";
$marker->description = "$rivername";
$marker->icon = $river['cond'];
$marker->type = 'riverlevel';
$river['geoMarker'] = $marker;
$rivarr[] = $river;
}
//$json =
// convert a complexe value to JSON notation, and send it to the browser
//$output = json_encode($rivarr);
return($rivarr);
}
<code>
Order of Execution
The render() function is called after the act() function on a gadget. All gadgets have run through the act function by the time the first render function is called. Act() has to return the value of array(GDA_DISPLAY) in order for the render function to be called. However, for legacy reasons effect does not return a value or returns an invalid value render() is generally called.