Updating a Theme to 2.x
Though early versions of 2.x supported older theme functions, the move to v2.2.0 and later requires using the v2.x expTheme functions, however optional Old Theme Compatibility exists, but must be first activated. Additionally all the 'old school' modules have been upgraded to the 2.0 'controller' format (though they are called 'modules'. Here are some specific things to look for and update.
Activating Old Theme Compatibility
Compatibily with the older 0.9x theme methods was dropped around v2.2.0. However this enhanced compatibilty can be actived by adding a line to your custom theme's config.php file (which is a new file you'll need to create within the custom theme). This compatibility was automatically included in early iterations such as v2.2.0patch5 or V2.2.1, and displays warning messages with details of how to correct the obsolete/deprecated calls with error reporting turned on and logged in as an admin user. To activate old theme compatibility use the custom theme's config.php file to insert this content:
<?php
define('OLD_THEME_COMPATIBLE', 1);
?>
Obsolete CSS References
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. 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
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 calls used simple (sequential) parameters.
Please keep in mind that the default 'action' for a module is ALWAYS 'showall' if none is passed and the default 'view' for a module is ALWAYS the name of the action if none is passed.
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("module"=>"navigation","action"=>"showall","view"=>"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)
- flowplayerController or flowplayer => media (this is a 2.0 controller which has been deprecated)
- youtubeController or youtube => media (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("module"=>"container","action"=>"showall","view"=>"showall","source"=>"@left"));
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.