You already know that the Zen Grid Framework allows for basic css and javascript to be added in the template administration. But what if we want to add functionality for something like FancyBox? This is a little beyond the scope of the basic include functionality, so let's look at a good, efficient way to do this.

Here's how you can:

Time Required: 20 minutes
Skills: Intermediate
Tools: FTP client
Joomla Version: Joomla 1.5
Overview: We'll use the Zen Grid Frameworks templateVariables file to add some custom scripts and stylesheets.

Note: This tutorial explains how to add FancyBox to a ZGF template, but the same steps apply to many other situations, and you can easily adapt these steps to add a wide range of scripts and features.

1. Let's start by downloading the latest copy of FancyBox at fancybox.net. Click the download FancyBox button and unzip it on your computer. When you open the folder you will find the files that we need to upload in the "fancybox" folder.
2. Login to your site through an FTP client and navigate to the folder of the template you are using. Since I am using the Meridian template, I am going to /templates/jbmeridian/. What we'll do is upload the "fancybox" folder right to our template folder. Make sure you transfer the "fancybox" folder and not the enclosing "jquery.fancybox-1.3" folder.

Note: We could split the files into the css, images, and js folder, but that would create a lot of extra work with updating file paths. Keeping everything grouped is easier both now and for future maintenance.

1. Now that we have the fancybox script and stylesheet uploaded to the server, we need to add the script into the template. We will do this using the Joomla addStyleSheet and addScript tags. Before we add the scripts, we need a place to add them to. Luckily, the framework offers a solution to this. Open the file named templateVariables.php located in the ../jbmeridian/includes/ folder.

__

The templateVariables file allows us to add custom PHP to ZGF templates. So, the combination of the Joomla addStyleSheet, addScript, and ZGF templateVariables will easily allow us to add the references to the files for FancyBox. Any code added to this file gets inserted into the template .

1. Let's start by adding a link to the FancyBox stylesheet. To do this we will use the addStylesheet code:

   {codecitation}$doc->addStyleSheet( 'templates/jbmeridian/fancybox/jquery.fancybox-1.3.4.css' ); {/codecitation} If you aren't using the Meridian template make sure you change jbmeridian to match your template name.

Note: See the conclusion for a comparison between addStyleSheet and addCustomTag.

1. Now that the stylesheet is in place, we need to link to the FancyBox script itself. To add a script link, we have another line to add to the templateVariables file after the addStyleSheet:

   {codecitation}$doc->addScript( 'templates/jbmeridian/fancybox/jquery.fancybox-1.3.4.pack.js' ); {/codecitation} Note: In the folder that we uploaded, there are 2 different FancyBox files: "jquery.fancybox-1.3.4.js" and "jquery.fancybox-1.3.4.pack.js". The packed file is the same code as the first one, except compressed for a faster load time. The unpacked version 29kB while the packed version is 16kB. We are using the packed version.

Save the file. Our final templateVariables file now ends like this:

Note: We don't need to include a link to jQuery because that is taken care of by the JB Library plugin.

1. All the required styles and scripts for FancyBox are in place now. However, we aren't using it just yet. One of the several uses for FancyBox includes displaying images. On my site, I have a module that I want to include a FancyBox link in. You can, of course, create links to FancyBox in content items as well. I am going to add a text link to a popup image. This takes 2 steps:

2. In the module where I want my new FancyBox link I add the following:

   {codecitation}Click me! {/codecitation} This is a link to an image with an ID of "bottom3_image". Without FancyBox, when click the link will just open the image.

3. In the Meridian template preferences under Extras > Extra Scripts I add:

This code creates a script that, when the page is ready, tells jQuery to look for an element with the ID "#bottom3_image" and apply the FancyBox effect. To add more than one FancyBox link, just duplicate the following line and change the id selector.

{codecitation} jQuery("#bottom3_image").fancybox(); {/codecitation}

1. So, when I view my site and go to the bottom3 module I see the link:

   
   And when I click the link, the FancyBox powered popup appears. Perfect!

   

Conclusion

An alternative to this whole process would be to use one of many Joomla lightbox plugins. However, I personally like to be able to tinker directly in the code instead of using a third party plugin. Additionally, using this method, means that I can keep the code contained in the template folder and we don't have to worry about another plugin.

This implementation of FancyBox is bare-bones, but this tutorial is more to show how to add stylesheets and scripts to a ZGF template. If you want to customize FancyBox, including custom animation and styling, check out the FancyBox website.

On addStyleSheet/addScript and addCustomTag

addStyleSheet and addScript are simple tags for adding links to external files. addCustomTag is a more powerful and versatile command that can do everything that addStyleSheet and addScript do. However, addCustomTag allows for functionality like inline code, as well as comments and conditional comments. For example we can easily target IE8 with the following:

{codecitation}$doc->addCustomTag(" "); {/codecitation} In the case of FancyBox, we could have use one addCustomTag instead of both addStyleSheet and addScript, however there are a few drawbacks to the combined method:

1. Quotation marks need to be escaped. This add a bit more bloat to your code.
2. The files aren't loaded optimally. The tutorial method of using addStyleSheet ensures that the CSS file gets loaded with the other CSS before the scripts. This allows for optimal load speed and page rendering. When addCustomScript is used, the CSS file gets loaded after a block of other JS files. In this particular circumstance the difference isn't an issue.

For those who are wondering, here is the way to use addCustomTag:

{codecitation}$doc->addCustomTag(" <link href="\"$this-" rel="\"stylesheet\""> baseurl/templates/jbmeridian/fancybox/jquery.fancybox-1.3.4.css\" type=\"text/css\" /> "); {/codecitation} As is often the case, there is more than one way to get the job done, and in this particular case, both methods are effective. Happy coding!

blog comments powered by Disqus