Preparing for the Smarty library upgrade

Sugar utilizes a PHP library called Smarty for rendering PDFs in PDF Manager and also for rendering HTML pages used by Backwards Compatibility (BWC) modules. In Sugar 11.2 (Q4 2021), we will be upgrading that library from v2.6.11 to the latest version v3.1.35. There have been significant changes from Smarty 2.x to 3.x and because it is a major version upgrade there are some potential for breaking changes. 

Who is affected by this change?

For most customers, we expect this change to be seamless and without a noticeable impact. However, if you have instances with BWC customizations that include custom Smarty templates or if you've created PDF templates that make use of Smarty functions or modifiers then you will be affected by the Smarty library upgrade. SugarCloud customers will be impacted first with the 11.2 upgrade. On-premise customers should expect the upgrade in Sugar 12.0 based on Sugar's typical release cadence.

What will happen during upgrade?

The Sugar upgrader will be examining Smarty templates that exist on filesystem (BWC related files with TPL file extension) and stored in the database (PDF templates). The upgrader will identify known incompatibilities with Smarty 3.x and make automated updates to fix the templates.

The upgrader will generate warnings whenever it has migrated a custom Smarty template. For example, it will let you know which custom PDFs it has migrated. It will also generate warnings if it encounters anything unusual. For example, if a TPL file does not appear to be a valid Smarty template.

What action do I need to take?

At the very least, you should plan to test that your custom PDF templates and any BWC customizations that exist in your Sugar instance still works as expected after upgrade.

If you've built an app or integration for Sugar that uses a Module Loadable Package (MLP) that includes custom Smarty templates then you will need to update those templates manually to use Smarty 3.x syntax. You will also need to update your module manifest to indicate compatibility with Sugar 11.2 and greater.

If you have access to Sugar Release Previews, we encourage you to participate in the upcoming previews for Sugar 11.2 (SugarCloud release) or Sugar 12.0 (on premise release) to proactively identify and resolve Smarty issues prior to GA. If you are not a member of Sugar Release Preview program and would like to be added, please contact developers@sugarcrm.com. The Sugar 11.2 preview is planned for August 2021.

Most of the changes cannot be made until you are running Smarty 3.x. But depending on your particular customizations, you may find some things that you can fix right now. Like, maybe you see that you did not use quotes around string parameters. Smarty 2.x was fine with that. Smarty 3.x is not. So, right now you could go into your TPL files and ensure that you have quotes around all text parameters. That's just one example. Continue reading below to see if you think you can get a head start on any of the changes we are highlighting.

Significant breaking changes between Smarty 2.x and 3.x

We are listing some of the biggest potential problems here so you can proactively identify these issues in your BWC customizations and custom PDF templates that utilizes Smarty capabilities. An overview of Smarty 3.x can be found on the Smarty website along with some additional documentation on known incompatibilities. The Sugar upgrade scripts may not catch all problems and these issues will need to be addressed manually within MLPs.

$this in {php}

$this in TPL files will no longer be supported
Please replace all occurrences of $this with $_smarty_tpl (which points to instance of Smarty_Internal_Template)

{php}
$this->_tpl_vars['index'] = "some value";
{/php}

{php}
$_smarty_tpl->assign('index', "some value");
{/php}

Unknown tag 'literalclose' error

It is sometimes desirable - or even necessary - to have Smarty ignore sections it would otherwise parse. A classic example is embedding Javascript or CSS code in a template. The problem arises as those languages use the { and } characters which are also the default delimiters for Smarty. In new Smarty templates, the { and } braces will be ignored so long as they are surrounded by white space.

function(){literal}{{/literal}
    alert(1);
{literal}}{/literal}

function() {
    alert(1);
}

Unknown tag 'phpclose'

Similar to "unknown tag 'literalclose'", replace examples of {{/php} with { {/php}

{assign} with multiple variables

{assign var='groupTabId' value=$tabGroupName$underscore}

{php}
    $_smarty_tpl->assign('groupTabId', $_smarty_tpl->getTemplateVars('tabGroupName') . $_smarty_tpl->getTemplateVars('underscore'));
{/php}

or assign groupTabId in the controller or add quotes around the variable value (see clarification in the next paragraph):

{assign var='groupTabId' value="$tabGroupName$underscore"}

Unquoted Strings

Smarty 2 was a bit more forgiving (and ambiguous) when it comes to unquoted strings in parameters. Smarty 3 is more restrictive. You can still pass strings without quotes so long as they contain no special characters. (anything outside of A-Za-z0-9_)

{html_options name=foo[] options=$myOptions selected=$mySelect multiple="multiple"}

{html_options name='foo[]' options=$myOptions selected=$mySelect multiple="multiple"}

Backticks in attributes

Please use single or double quotes for passing parameters. Do not use backticks.

{assign var='name' value=`Bob`}"

{assign var="name" value="Bob"}
{assign "name" "Bob"}