Overview

The Zen Grid framework version 2.4 was released in November 2012. This version represents a number of improvements which mainly effect the templateDetails.xml of previous Zen Grid Framework templates but in some cases layout overrides and other files are also effected. This document is for users who have customised their template and wish to upgrade to the new version without losing their changes.

In most instances depending on the customisation this means simply uoploading specific files but the changes and new additions are noted below for developers who want to dig deeper.

Do you need to upgrade?

Upgrading to v2.4 of the framework is not mandatory and most of the changes are improvements and not bug fixes. You can see a full list of the additions via the framework changelog page.

 

Can I use my pre v2.4 framework template with Zen Grid Framework v2.4?

Unfortunately due to the nature of this release of this version of the framework, your template needs to be made specifically compatible with v2.4 of the framework.

We will update the specific changelog for templates that are made compatible with v2.4 with details regarding the update process.

If you install the 2.4 version of the framework on templates named v2.3 and less then your template will stop working.

If you do install v2.4 of the framework on an incompatible template then don't fear, because you can simply reinstall the previous version of the framework that is compatible with your template and it will reinstate the template.

Will all templates be updated to v2.4?

At this stage all templates except for Shop Ignition will be updated shortly after the release of 2.4. Shop Ignition was built using legacy mode which is now deprecated and will be updated to use the non-legacy layer in the near future.

How do you know if your template is ready for Zen Grid Framework v2.4?

The naming convention we use for our templates uses the following convention:

JB_Template Name_Joomla Version_FrameworkVersion number.Template increment number.

as an example:

JB_Lifestyle_J1.5_J2.5_v2.4.2

Any template with anything less than 2.4.0 in the version number is not compatible with Zen Grid Framework v2.4.

Can you just install the new 2.4 version of your template over the existing template?

It is not possible to use the upgrade method using Joomlabamboo templates because we have disabled this functionality in the template installer. We decided that it's safer for our users if we disable this because installing new template files over old template files will also remove any customisations added to the template.

 

How do you upgrade your template?

1. If you have not made any changes to your template then you can follow the details on the changelog for your specific template.
2. If you have made changes to a few files int he template but none of those affected by the upgrade as details in the changelog then you can follow the changelog instructions as well.
3. If you have made changes to the files affected in the upgrade then you may need to do a file diff on the new and old files to see the differences or add the code as recommended in the template changelogs. In most cases any specific code changes will be highligted in the template's changelog.
4. As of v2.4, templates will now use a patch file for css additions to the template. Please read the information  below regarding the new patch files. 

New patches for css files.

One of the challenges faced with adding new functionality to old template's, centers around how best to add new css to the current core theme.css file. In the past we have been reluctant to make too many changes to the theme.css file as this generally adds unneeded complexity to new and even experienced users.

As of v2.4, all new patches, upgrades and fixes will be added to a css file located in the user folder of the template. All files in this folder are automatically included in the template on load so we will be using the new patch file to load any new css that is required for the template. This patch file will include code additions for new functionality as well as css overrides for bug fixes.

Example

The css files will be named according to the following naming convention:

• - Template-ZGF-version.css

So as an example an update for the Lifestyle template with a new patch file would be found here

• templates/jblifestyle/user/lifestyle-zgf-24.css

A global zen object

As  a part of the code improvements we have removed all references to the tamplet getParameters and moved the template parameters into a global object.

So now rather than retrieving a template parameter like this:

{codecitation}

echo $this->params->get("hilite");

{/codecitation}

or this:

{codecitation}

$hilite =  $this->params->get("hilite");

echo $hilite;

{/codecitation}

it is possible to simply use this:

{codecitation}

echo $zen->hilite;

{/codecitation}

Changing to this convention has improved the framework's performance and reduced the codebase significantly.

New jQuery and javascript functions

The bulk of the framework jQuery effects and fucntionality is now included in the media/zengridframework/js/zen.min.js file. There is an uncompressed version of this fiel also available in the same folder.

A number of javascript features that were using across templates - such as the select navigation for small devices - have now been transformed into jQuery functions that can be used in the templates and in particular the js/template.js file.

The new jQuery functions include:

zentabs();

Function that drives the inbuilt tabbed layouts.

Example

{codecitation} jQuery("#right-tabs li").zentabs(); {/codecitation}

The example above shows the jQuery used to fire the tabs in the sidebar of the template. The object of the function is the list element that will be used to trigger the tabs.

The html required for this is included below:

{codecitation} {/codecitation}

zentoggle(); 

Used to toggle elements on the page.

{codecitation} jQuery("#mytrigger").zentoggle({activeclass: 'active',display: true}); {/codecitation}

Functions:

activeclass: the class applied to the trigger when the item is open.

display: false by default but when set to true the content is displayed on page load.

Implementation:

When the code block above is added to the template.js file the following markup becomes a show / hide toggle.

{codecitation}

<div id="mytrigger">Toggle</div>

<div id= "mycontent">Content here in the next div.</div>

{/codecitation}

The selector nominated in the function above eg #togglemenutrigger when clicked toggles the display of the following div.

zencookietoggle();

This is similar to zentoggle except that the toggle state is saved to a cookie and recalled on page load.

eg 

{codecitation}

jQuery('.moduletable-slide .moduleTitle>h3').zencookietoggle();

{/codecitation}

zenwidthcheck();

This snippet can be used to add a class to a specified div when it gets to a certain size. This is useful for conditions when you want to display a condensed format for a specific div that reduces in size that may or may not be affected by the window size.

{codecitation}

jQuery('#rightCol,#leftCol,#jbtabbedArea').zenwidthcheck({width: "300",targetclass: "narrow"});

{/codecitation}

Functions

After adding the selector you want to target in the code block above you can then specify:

width: Determines the width the element needs to be in order to toggle the class.

Class: The class that you want to add to the element when the width is reached.

zenselect();

{codecitation} {/codecitation} {codecitation} {/codecitation} {divider}{/divider}

zenpanel();

Can be used to create a new panel instance on the page.

eg

{codecitation}

jQuery('#mypanel').zenpanel({

     trigger: '#mypanelopen,#mypanelclose,#myoverlay',

     overlay: '#myoverlay',

     type: 'opacity'

});

{/codecitation}

The Object

The object of this function is the panel element itself eg The content you want to show when the panel is created.

Functions:

• trigger: The element used to trigger the panel. Can be multiple elements.
• overlay: The name of the div that behaves as the overlay.
• type: opacity, height or width.

zenaccordion();

The zenaccordion(); function refers to the old panelmenu functionality and has not been made a global object yet.

3rd Party scripts

We have also included some other 3rd party scripts taht are used extensively throughout our templates.

ImagesLoaded plugin: Created by Dave Desandro

We use this to trigger javascript once images have loaded. eg for masonry and equal heights layouts

Breakpoint.js: created by XOXCO

We use this to run javascript and control some layout elements when the user moves through various screen breakpoints.

jQuery Cookie: Created by carhartl

Used to recall states of toggles and menus based on user interaction

Other feature additions

Version 2.4 of the framework also adds the following new features to version 2 compatible templates.

 

Sidebar tabs

You can now add tabbed layouts above the left and right columns by publishing modules to left-a, left-b, left-c,left-d for the left column and right-a, right-b, right-c and right-d for the right column.

Cookie script

Users who run websites in the EU can now simply enable the cookie accept functionality from their template backend.

We used the cookiecuttr script for this funtionality.

Virtuemart Reset

The framework now includes a reset css file for the Virtuemart templat which can be toggled on or off from the template admin. This css file is designed to reset some of the core display characteristics of Virtuemart to make the default Virtuemart template more integrated into our templates.

This file can be overidden by simply loading a file named virtuemart.css into the css folder of your template.

Other under the hood improvements

The core functions/vars.php file is now half it's previous size.

In addition to this much of the logic in that file has been simplified and optimised.

Removed legacy mode: This only applies to the Shop Ignition template which at this stage will not be made compatible with 2.4 of the framework.

Removed debug mode: This was a smart idea but just added to code size in a lot of respects. We will revisit this in future updates to see how it can be re-implemented with a lighter footprint.

Removed unneed jLibrary imports.

Added League Gothic as a stand alone webfont. Not sure why it was removed from google fonts but we like this font alot.

Reorganised framework admin files.

Removed all legacy files

Updated layout/assets files

Added noscript message for users running their browser without javascript enabled. This is a configurable message.