Creating custom Jamroom Template Functions and Variable Modifiers

If you have worked with Jamroom templates before, then you know how flexible they can be - you can do almost anything you want in a Jamroom Template, and the use of Template Functions and Variable Modifiers adds a lot of power and flexibility.  This guide will not cover the use of Template Functions and Variable Modifiers, as it is assumed you already know how to use them (and their difference) - however, for a brush up on how things work it is highly recommended you check out the "Smarty" manual:

    http://smarty.net/manual/en/

Since Jamroom uses the powerful Smarty Tenmplate engine for it's templates, having a good understanding of the many different things you can do in Smarty is vital to getting the most out of your module and Jamroom.

Custom Template Function

To create a Custom Template function for use in your Jamroom Templates, you will want to locate the plugin file in the following directory:

    modules/Module_Name/smarty

So for our jrYouTube module we are going to create a custom template function that will take a YouTube Video ID and create an embedded YouTube video out of it (this prevents us from having to remember all of the embedded object HTML code).  The naming of the plugin file is important, as that allows Jamroom to determine if the file is a template function OR a modifier.  For a template function, the PHP script MUST be named like so:

    function.function_name.php

So for our custom template function we are going to name it:

    function.jrYouTube_embed.php

This will create a Template function called {jrYouTube_embed} for our use in all Jamroom templates.  Note that you can create as many different custom template functions as you would like - there's no limit.

<?php
/**
 * jrYouTube_embed Template Function
 * @copyright 2009 by Talldude Networks LLC.
 * @author Brian Johnson - bigguy@jamroomnet
 */
function smarty_function_jrYouTube_embed($params,&$smarty)
{
    if (strlen($params['youtube_video_id']) === 0) {
        return('');
    }
    if (!checkType($params['width'],'number_nz')) {
        $params['width'] = 425;
    }
    if (!checkType($params['height'],'number_nz')) {
        $params['height'] = 350;
    }
    $code = '<p><object height="'. $params['height'] .'" width="'. $params['width'] .'">
      <param name="movie" value="http://www.youtube.com/v/'. $params['youtube_video_id'] .'">
      </param>
      <param name="wmode" value="transparent"></param>
      <embed src="http://www.youtube.com/v/'. $params['youtube_video_id'] .'"
       type="application/x-shockwave-flash"
       wmode="transparent"
       height="'. $params['height'] .'"
       width="'. $params['width'] .'">
     </embed></object></p>';
    // Check for assign
    if (isset($params['assign']) && strlen($params['assign']) > 0) {
        $smarty->assign($params['assign'],$code);
    }
    else {
        return($code);
    }
}
?>

This is the contents of the "function.jrYouTube_embed.php" PHP script, and you can see that there is a naming convention we must stick to within the function file as well:

function smarty_function_jrYouTube_embed($params,&$smarty)
{

Note how the function MUST be named:

    smarty_function_FunctionName

and accepts 2 parameters - the $params array (which will contain all of the Template Function parameters in key = value pairs, as well as the global $smarty object.  It is very important that the function be named properly, otherwise Jamroom will not see it and the template function will not work.

So with our template function created, we can now use it in a Jamroom Template.  Since we already created the Ranking System Plugin, we could use it in our "row_template" like so:

{jrYouTube_embed width="400" height="300" youtube_video_id=$YOUTUBE_VIDEO_ID}

and that would create the embedded YouTube video directly in the page.  This is very convenient as now we do not have to remember how the object code is constructed, and in the future if it ever changes, we simply update our Template function and it is fixed everywhere the template function is used.

Custom Template Variable Modifier

The second type of custom template plugin we can create is called a "Variable Modifier" - and like the name implies, its purpose is to modify the contents of a template variables.  For our jrYouTube custom module, we're going to create a Variable Modifier that will "expand" a YouTube video ID into a URL link to the You Tube page for the video.  This way we do not need to enter the full URL details, and instead can simply use the modifier:

<?php
/**
 * jrYouTube_url Template Variable Modifier
 * @copyright 2009 by Talldude Networks LLC.
 * @author Brian Johnson - bigguy@jamroom.net
 */
function smarty_modifier_jrYouTube_url($id,$tg = '_blank')
{
   global $config;
   $out = '<a href="'.$config['jryoutube_base_url'].$id.'" target="'. $tg .'">'. $id .'</a>';
   return($out);
}
?>

As you can see it is a very simple function - it accepts 2 parameters (one for the You Tube video ID, and the other for the "target" for the HTML anchor tag).  This allows us to use it in a Jamroom template like so:

{$YOUTUBE_VIDEO_ID|jrYouTube_url}

or if we want to use a different target for the link:

{$YOUTUBE_VIDEO_ID|jrYouTube_url:"_self"}

Note that the $YOUTUBE_VIDEO_ID value will be passed to the smarty_modifier_jrYouTube_url() function as the first parameter.  Also - just like our Template Function above, the NAMING of the modifier file is important, and would be:

    modules/jrYouTube/smarty/modifier.jrYouTube_url.php

Without your modifier file being named properly, Jamroom will not see it as a modifier plugin.  And just like the template functions, you can create as many different Variable modifiers as you would like.