Blog items tagged with "smarty"

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)

The introduction of YUI 2in3

YUI 3.2 and earlier had no browser based detection loading, and worked well with YUI PHP Loader, allowing for Exponent to load YUI dependencies on the server side. Since the introduction of YUI 3.3.0, which loads (and skips loading) JavaScript based on your browser, it's now only YUI 2.x that can take advantage of server-side dependency calculation and loading, since PHP has no sure-fire way to detect the user's browser. The result: Exponent YUI 2 loading up on the server, and YUI 3 loading via YUI3's built-in Loader.

It's always been the goal to migrate fully to YUI 3 once certain aspects of the library offer comparable widgets to YUI 2. Until we can fully drop YUI 2 from the system, we can at least streamline the YUI loading mechanisms by making use of the YUI 2in3 library. YUI 2in3 is written by the YUI team as a compatibility layer that allows the loading and usage of the YUI 2 library within the YUI 3 ecosystem.

Integrating YUI 2in3 offered many advantages compared to sticking with YUI PHP loader. For one, it streamlines using the YUI environment, setting up a general usage pattern for using both versions of YUI. It also drops 2 external library dependencies: YUI PHP Loader, and Lissa (ties YUI PHP Loader together with minify).

With these changes, however, you stand a good chance of breaking existing views making use of YUI 2 code. We've corrected the themes shipping with Exponent that previously made use of this, like cool waters override for YUI Top Nav.

To help alleviate some migration pains, we've added some helper mechanisms to the {script} plugin, looking for the yui2mods or yuimodules parameter, parsing out whichever modules were passed, and plugging them in to yui3 wrapper code for you. This helps keep 90% of code from breaking, but isn't bullet-proof. Any custom views should definitely be adjusted.

Here's a gist of the old vs new pattern:

A good read that helped me integrate YUI2in3: