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"));
- Deprecated call -
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.
- 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.
- (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:
Comments
Leave a comment
Log In to leave a Comment