By default FRAPI generates XML and HTML (And other formats) on it's own. However some vendors may require proprietary formats while serving XML.
For that purpose, FRAPI has a templating system and a custom templating system. This document will describe how to implement and use these templates.
FRAPI actions by default will process a template file for xml or html if it exists at the following location:
FRAPI_PATH/src/frapi/custom/Output/[xml or html]/ActionName.[xml or html].tpl.
Now that this file exists FRAPI will automatically start parsing it. You just have to add the code to make it look the way to you want.
A FRAPI template file can contain any html or xml you desire. You can use regular php code and syntax to process the data array you built in your action.
To access the data array you built in the action from the template simply use the $data array.
Let's create an action Sports and have the get for that action return, in xml, the id and name of all the sports in our database.
Start by creating the action from the admin interface. To learn how to create actions, click here.
Start by modifying the executeGet function in the FRAPI_PATH/src/frapi/custom/Action/Sports.php to look like the following:
public function executeGet()
{
$valid = $this->hasRequiredParameters($this->requiredParams);
if ($valid instanceof Frapi_Error) {
return $valid;
}
// Connect to our database
$db = Frapi_Database::getInstance();
$stmt = $db->prepare('
SELECT sport_id, sport_name
FROM sport'
);
$stmt->execute();
$sports_result = $stmt->fetchAll();
// Create an array of data to use in our template file
foreach($sports_result as $sport_data) {
$this->data[] = array('sport' =>
array('id' => $sport_data['sport_id'],
'name' => $sport_data['sport_name']
)
);
}
$db = null;
return $this->toArray();
}
The code above connects to the database, queries the sport table for all sports, and then builds an array with that data. The array might look like:
Array
(
[0] => Array
(
[sport] => Array
(
[id] => 1
[name] => Basketball
)
)
[1] => Array
(
[sport] => Array
(
[id] => 2
[name] => Football
)
)
[2] => Array
(
[sport] => Array
(
[id] => 3
[name] => Hockey
)
)
)
Now that you have your data organized you can manipulate it in your FRAPI_PATH/src/frapi/custom/Output/xml/Sports.xml.tpl file*.
Below is the content of the template file utilizing the $data variable which contains all the data you assigned to $this->data in the executeGet() function. Here you are simply looping through your array and building the xml structure you require.
<sports>
<?php foreach ($data as $key => $value) : ?>
<sport>
<id><?php echo $value['sport']['id']; ?></id>
<name><?php echo $value['sport']['name']; ?></name>
</sport>
<?php endforeach; ?>
</sports>
Given the array you created in the action and the code in the template above the following xml will be created:
<?xml version="1.0" encoding="UTF-8"?>
<sports>
<sport>
<id>1</id>
<name>Basketball</name>
</sport>
<sport>
<id>2</id>
<name>Football</name>
</sport>
<sport>
<id>3</id>
<name>Hockey</name>
</sport>
</sports>
And that's all you need to know to create a custom xml or html template for your frapi action. If you need to represent the data from you action in multiple xml or html formats continue to the Creating Multiple Custom Templates section below.
*You may need to create this file if it does not already exist.
Let's say you want to represent the data created in your action in a slightly different way based on a parameter passed. FRAPI makes this very easy. All you have to do is create a template file in the following location: FRAPI_PATH/src/frapi/custom/Output/[xml or html]/custom/CustomActionName.[xml or html].tpl.
Now all that is left is to specify the custom template you want to load. To do this simply call the setTemplateFileName method of your action object, passing it the name of your custom template. Like so $this->setTemplateFileName('CustomActionName');.