Blog items tagged with "templates"

Prepping Your Site for v2.2.0 (or how to deal with a major update)

(Update: we HAVE reverted to the name 'container' instead of 'container2' for release candidate1!)  Here are some tips and tutorials to help ensure your site is 'v2.2 ready'!  While there is really no show-stopping change moving from v2.1.1 to v2.2.0, the move to v2.2.0 will reveal any themes or custom views which haven't been updated to 2.0 standards.  In a pragmatic sense, though the upgrade must be run and completed to convert the database for use in v2.2.0, your site would continue to work using one of the shipped or add-on themes which are 2.2 ready.

Since this upgrade only affects a custom theme and/or custom views, that's where we'll need to look:

  • Theme 1.0 compatibility removed
    • This one is the easiest to spot and correct.  It will occur in the main theme template (/themes/mytheme/index.php) and the subthemes (found in the subthemes folder)
    • Calls to the deprecated 1.0 theme subsystem look like 'exponent_theme_method' instead of 'expTheme::method'  And moreso there are only three mandatory calls with a fourth recommended call for hard-coding other modules
      • expTheme::head(...) in the <head>...</head> section, this method is used in place of the deprecated exponent_theme_headerInfo(...) call
      • expTheme::main() in the main content area in the <body>...</body> section, this method is used in place of the deprecated exponent_theme_main() call.
      • expTheme:foot() at the bottom of the <body>...</body> section, this method is used in place of the deprecated exponent_theme_footerInfo() call.
      • expTheme::module(...) within the main content area for hard-coding (embedding) modules, this is THE single multi-purpose method to display a module in place of many deprecated calls: 
        exponent_theme_showSectionalModule(...), 
        expTheme::showSectionalModule(...), 
        exponent_theme_showTopSectionalModule(...), 
        expTheme::showTopSectionalModule(...), 
        exponent_theme_showModule(...),
        expTheme::showModule(...),
        expTheme::showSectionalController(...),
        and expTheme::showController(...)
        • A big difference between the expTheme::module(...) call and the others (except the last two) is that it is called with a single parameter of an associative array of named parameters, whereas the deprecated ones were called with simple (sequential) parameters.
        • Likewise most of these various calls were to either deal with a 1.0 module or 2.0 controller, or to hard-code a module with a specific 'scope' (global, sectional, or top-sectional), which is now simply a 'scope' named parameter with 'global' being the default.  The expTheme::module(...) call is 'smart' in being able to to it all!
        • Deprecated call - expTheme::showModule($module,$view,$title,$source,$pickable,$section,$hide_menu,$params);
        • 2.0 call - expTheme::module(array("controller"=>"navigation","action"=>"showall","view"=>"showall_mega","source"=>"mega","chrome"=>true));
  • Old School (1.0) modules no longer exist
    • Another fairly easy thing to spot and correct are hard-coding an old school module within the main or subtheme template.  In many cases, these old school modules have been disappearing and references to them as hard-coded modules may have already been exposed.  However some were replaced with like named 2.0 modules (controllers)
    • A big difference between the old and 2.0 modules is old school modules only required a 'view' parameter, whereas the 2.0 modules require an 'action' parameter (with the default view implied).  The old school default (view) was 'Default' whereas the 2.0 module default action is 'showall' and the default view is also 'showall'. Therefore to locate old school modules, they were typically called using a 'module' parameter instead of 'controller' (however each are interchangeable).  Specifically, 2.0 modules need to have an action parameter, whereas the old school modules only pass a 'view' parameter (with NO action parameter).  If the old school view was something other than 'Default', please see the next area of discussion.
    • Here's a list of old school modules and their 2.0 counterparts:
      • simplepollmodule or simplepoll => simplePoll
      • navigationmodule or navigation => navigation
      • calendarmodule or calendar => events
      • formmodule or form => forms
      • containermodule or container => container (this has changed to simply 'container' in release candidate 1)
      • headlineController or headline => text (this is a 2.0 controller which has been deprecated)
    • Here's an example of an update required since most themes include a hard-coded container
      • Deprecated call - expTheme::module(array("module"=>"container","view"=>"Default","source"=>"@left"));
      • 2.0 call - expTheme::module(array("controller"=>"container","action"=>"showall","view"=>"showall","source"=>"@left"));
    • ​​If you've kept up to date through v2.1.1, the only NEW upgrade involves the 'container' module.  
    • The deprecated call may continue to work, but is unsupported.  If it fails to work because this is a module name change, your custom themes will not seem to work (will say that containermodule is unavailable) until it is corrected.
  • Old School Module Custom Views must be updated to work with their 2.0 module counterpart
    • The most complex of the changes will likely be required for any old school module custom views.  These would be found in the //themes/mytheme/modules/ folder using any of the above full module named folders.  In many cases, the custom view could be upgraded by a couple of simple renames.
      • Rename the 'module' folder into its 2.0 counterpart...e.g., 'navigationmodule' into 'navigation'
      • Within the newly renamed folder, enter the 'views' folder and create a new folder with the name of the module, such as 'navigation'
      • Move all the other files (.tpl files) within that 'views' folder into that newly created folder
      • Enter the folder with the moved templates, then rename the view template(s) into a 2.0 suitable name which includes the action:
        • 'Default.tpl' would become 'showall.tpl'
        • 'YUI Top Nav.tpl' would become 'showall_YUI Top Nav.tpl'
    • Any configuration or form files (.config or .form) would need more complex editing.
      • .config files are no longer used as these details must now be handled within the controller itself
      • .form files are now templates within the 'configure' subfolder of the views folder.  They are named by the associated view name with a .config suffix.  The files are now formatted just like a view instead of using the shorthand notation to create controls.  You should look at a system module like 'events' or 'blog' to get an idea of how view specific configurations work.
  • (Updated) Some YUI constants and file names/locations have been deprecated
    • Both of these issues tend to be revealed as improper formatting such as misaligned columns or font styles.
    • The 'Reset' stylesheet names have been deprecated for quite some time (apparently) and were finally removed in YUI v3.10.0.  Since many of the older themes use YUI reset(s) instead of the new 'normalize' standard, here's the changes you'll need to look for and make in the expTheme::head() call at the top of your theme templates (and subthemes) (note the additional 'css' at the beginning of the filename!)
      • cssreset/reset-min.css has become cssreset/cssreset-min.css
      • cssreset/fonts-min.css has become cssfonts/cssfonts-min.css
      • cssreset/grids-min.css has become cssgrids/cssgrids-min.css
    • We have finally removed the deprecated YUI path constants for consistency with other path constants.  These were typically used to load scripts or stylesheets in the theme templates (also subthemes) and custom views)
      • JS_FULL is now JS_URL
      • JS_PATH is now JS_RELATIVE
      • YUI3_PATH is now YUI3_RELATIVE
      • YUI2_PATH is now YUI2_RELATIVE

Other articles of interest:

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)