Overview
Jamroom has the ability to use Template Pre-processors for all templates found in your active skin directory. Template pre-processors are basically PHP files that are called (or processed) by Jamroom to perform an action before a particular template is called.
Step 1 - Create your Template Pre-Processor
The first step for utilizing template pre-processors is to create a new file with the naming schema template.tpl.php, where template.tpl is the template name that the pre-processor should be used for, in the same skin directory as that template. For example, if you wanted to have a template pre-processor for your browse_artists.tpl file, you would create a file in the same directory as the browse_artists.tpl file with the name browse_artists.tpl.php.
Step 2 - Add your PHP Code to the Template Pre-Processor
The next step in creating your template pre-processor is to add your PHP code to it. Template pre-processors are .php files, and, therefore, must have valid PHP code. One of the most common uses for a template pre-processor is to send a different "header" to the accessing entity. For example, the following template pre-processor would display the accompanying template (rss_event.tpl) as an XML file:
rss_event.tpl.php:
<?php
// These header calls will output an XML header
header('Expires: '. gmdate('D, d M Y H:i:s', time()) .' GMT');
header('Last-Modified: '. gmdate('D, d M Y H:i:s') .' GMT');
header('Content-Type: application/xml; charset=utf-8');
?>
|
Once you have saved this file, each time the accompanying template is called, i.e. http://www.yoursite.com/index.php?t=rss_event, this file will be processed before the template, and output the template with an XML header.
Example - Create a Custom RSS Feed with Streaming Music
This tutorial can also be found on the Jamroom Support Forums. The goal of this example is to create an RSS feed for a Jamroom Radio Station with the capability to stream songs from the radio station. The first step to do this is to create a file that we will call podcast.tpl with the following code inside:
podcast.tpl:
| {jr_playlist id=$id|default:"1" limit=$limit|default:"40" template=$template|default:"podcast_xml.tpl"} |
The above code will use a {jr_playlist} function to create a playlist of all songs for a given radio station.
Next, we need to create our template pre-processor that will output an XML header to the accessing entity, ensuring it is seen as an RSS file. We can use the same code in the template pre-processor example above in our podcast.tpl.php file:
podcast.tpl.php:
<?php
// These header calls will output an XML header
header('Expires: '. gmdate('D, d M Y H:i:s', time()) .' GMT');
header('Last-Modified: '. gmdate('D, d M Y H:i:s') .' GMT');
header('Content-Type: application/xml; charset=utf-8');
?> |
Next, we need to create the template that will be used to process each of the items in our radio station playlist. We will need to create a file called podcast_xml.tpl.
podcast_xml.tpl:
<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0">
<channel>
<title>{$RADIO_NAME} - Top 40 Feed</title>
<description>{$RADIO_DESCRIPTION}</description>
<language>en-us</language>
<webMaster>{$return_email}</webMaster>
<link>{$JAMROOM_URL}</link>
<copyright>{$smarty.now|jr_date_format:"%Y"} {$system_name|escape:"quotes"} All rights reserved.</copyright>
<lastBuildDate>{$smarty.now|jr_date_format:"%a, %d %b %Y %T"} -0500</lastBuildDate>
<ttl>60</ttl>
{foreach from=$RADIO_SONGS key=key item=songs name=song_val}
<item>
<title>{$songs.SONG_NAME|replace:"&":"&"}</title>
<description><![CDATA[<a href="{$songs.SONG_PLAY_URL}">Click To Listen!</a> {$songs.SONG_NAME|replace:"&":"&"} - By: {$songs.BAND_NAME|replace:"&":"&"}<br>
]]></description>
<pubDate>{$songs.SONG_TIME|date_format:"%a, %d %b %Y %T"} -0500</pubDate>
<guid isPermaLink="false">{$songs.SONG_NAME|replace:"&":"&"}</guid>
</item>
{/foreach}
</channel>
</rss> |
Now all we need to do is to view and test our RSS feed! We can use the following URL to access our feed:
http://yoursite.com/index.php?t=podcast
By default, the feed we created will be for radio station radio_id "1," and will limit the feed to 40 songs and use the podcast_xml.tpl file to process the songs. However, due to the fact that our feed is going through the index.php file, we can also pass URL query string parameters to our feed URL and use them in our {jr_playlist} function that we created in our podcast.tpl file (as they are above). For example, this URL:
http://yoursite.com/index.php?t=podcast&id=2&limit=50&template=podcast_custom_xml.tpl
Would create an RSS feed for radio station radio_id 2, display 50 songs, and process the feed with the template called podcast_custom_xml.tpl (which would need to be created).
Congratulations! That's it - using the outline above, you can now use template pre-processors for any template in your skin directory called through the index.php file!
Additional Resources
If you have any questions on this guide, or would like add comments or suggestions, please join us in the Jamroom User Support forums. Thanks!
|
