Upgrading Templates from Smarty v2 to v3

When Exponent v2.0.2 was released at the end of October 2011 it incorporated a fairly major change under the hood that could 'break' some custom themes or mods.  The template engine (what is used to display everything) was upgraded from Smarty v2.5.x to v3.1.x.  This was a major upgrade, but the syntax basically remained the same...the issue is that 'bad' template code which worked under previous versions will likely break with this version.  However, Smarty v3 adds many enhancements including the ability to use inline computations/math.  Details on how to identify problems and fixes is at the end of this post.

The Smarty v3 template engine adds a parser/lexer feature to better handle inline code (javascript and php) and also better parses commands such as handling inline math, etc...  However, because the parsing has changed slightly, it tends to choke when running across 'bad syntax' conditions that used to work (slipped by) in earlier versions.  So, if you have any custom templates you are using, you may have to update/edit them to work. 

  • We'd recommend you first install v2.0.2 as a test installation on a server with php debug extensions loaded, and have DEVELOPMENT (Error Reporting) turned on (1).  This will point out which file and line number is causing any problems.
    • In most cases the error message will be somewhat descriptive of what needs changing e.g.,
      • Fatal error: Uncaught exception 'SmartyCompilerException' with message 'Syntax Error in template "C:xampphtdocsexp2frameworkmodulestextviewstextshowall.tpl" on line 49 "<a href="{link action=delete id=$text->id enabled=0}">{img src=`$smarty.const.ICON_RELATIVE`toggle_on.gif}</a>" - Unexpected "`"' in C:xampphtdocsexp2externalSmarty-3libssyspluginssmarty_internal_templatecompilerbase.php on line 617
      • This error tells you that the file '/framework/modules/text/view/text/showall.tpl' has a problem on line 49 which is an unexpected backtick
  • When updating/changing Smarty versions or plugins, you MUST ALWAYS clear the smarty cache
  • $smarty->_tpl_vars was deprecated without notice, so we MUST now use the getTemplateVars() method instead
  • Smarty v2 automatically disabled error reporting in templates, not so under v3 therefore there are TONS of warnings (missing indexes, etc...) with our plugins and templates.
    • A partial interim solution is that we've turned off error reporting after creating the Smarty object
    • In future versions we may turn error reporting back on to ensure we have clean plugin code which will expose a lot of warnings.
  • Smarty v3 allows expressions or variable references almost anywhere, and (apparently) isn't very tolerant of the backticks required to perform this in v2 (though this shouldn't be the case according to the documentation)...we use a lot of backticks for variables inside of plugin calls in templates.
    • In most cases you can simply remove the backticks in the 'offending' statement.
    • Look for any math statements in backticks such as rank=`$text->rank+1
      • Should be rank=$text->rank+1
    • This will NOT work in pre-2.0.2 since it handles math pretty poorly
  • Because of the better parsing, some of the formerly unescaped characters in template strings will break. The fix is to escape them by adding a backslash before.
  • You MUST enclose filenames containing symbols such as a period or dash, inside quotes now.
  • Look for any unquoted filenames in the {icon call with the img param
    • Search for '{icon' in the *.tpl files in your theme folder
    • {icon img=image.png ...}, should be {icon img='image.png' ...}
    • This will also work well in pre-2.0.2
  •  Concatenation of variables in strings can work by simply placing the text next to the closing brace {$variable}text, but you might best be served by using the 'cat' modifier such as $variable|cat:'text'
    • E.g., search for '{img' in the *.tpl files in your theme folder
    • Typically seen more in filenames such as {img src=`$smarty.const.ICON_RELATIVE`clean.png} or src={$smarty.const.ICON_RELATIVE}clean.png
    • Should be {img src=$smarty.const.ICON_RELATIVE|cat:'clean.png'
    • This will also work well in pre-2.0.2
    • In some server configurations, the $smarty.const.ICON_RELATIVE|cat:'clean.png' resolves literally to .const.ICON_RELATIVE|cat:'clean.png' instead of something like home/path/icons/clean.png.  Therefore it might be best to use the older backtick-delimted variation src='`$smarty.const.ICON_RELATIVE`clean.png'
  • Variables for arrays and objects in Smarty MUST be preceded with the dollar ($) sign. This should be obvious, but even Smarty v3.1.3 still allows basic variables to be referenced without the $.
    • Sometimes shows up as error '...Unexpected "[", expected one of: "}" , " "' in...'
  • And last, but not least...some of these required changes won't work under the older Smarty v2 (Exp v2.0.1 or older) so you'll have to wat least install a test using 2.0.2 to begin any updates.

(This article was originally a news post)

About the author

Dave Leffler
Exponent CMS Developer