Enable Colorbox For Non-Gallery Pages

Update: since changing the site over to gpEasy 2.x I've minimized the number of layouts I have. This tutorial no longer has Colorbox enabled on this page. While the information is still valid, gpEasy 2.x allows you to add a gallery into any page via a new section. By using the new gallery section Colorbox is automatically enabled on the page. Therefore, what I've actually done on this page now is to insert a new gallery section after the main content and delete all images so it doesn't show up. This automatically enables Colorbox on this page without all the hassles discussed in this tutorial.

Nonetheless, the original tutorial is left in tact.

The Happy Buddha gpEasy CMS uses the Colorbox plugin to display images in galleries. Colorbox is a very flexible plugin and you can learn a lot about it at the Colorbox main site however, for this tutorial I'm going to show you how to enable it for non-gallery pages just like this one. Click on the Happy Buddha at the right to see.

By default Colorbox is only enabled on gallery pages yet many users want to show off images on other pages as well--File Inclusion can be used to embed a gallery within another page without using the following method to enable Colorbox.

This tutorial requires that you add a line of code to your theme's template.php file. Don't worry, it's not that hard or scary.


Colorbox Tutorial For gpEasy CMS

Step 1
Go to the "themes" folder inside your gpEasy installation and open the folder of the theme you want Colorbox enabled on. Then open the template.php file inside of that theme's folder with your text editor.

You Will see a line of code near the top that looks like: <?php gpOutput::GetHead(); ?>
That's the "GetHead" output function and it's very very important. It calls all of the head data gpEasy needs to make a web page. Every theme requires this line of code! Now we want to add a line of code just before that "GetHead" output function. The code is,

<?php common::AddColorBox(); ?>

Copy the above code and paste it into your text editor just before the GetHead output function then save the template.php file and close your text editor.

By adding the above code you have enabled Colorbox for that entire theme therefore, any page that uses that theme will have Colorbox enabled.

That wasn't so hard, was it?

Step 2
Now we need to tell gpEasy what image to open in Colorbox. It doesn't just open every image. . . that would cause a lot of problems. There are two attributes we can add to the anchor element that will tell gpEasy how to handle images with Colorbox.

This is the first attribute. by adding name="gallery" in the anchor we tell gpEasy to open that link in Colorbox.

<a href="/data/_uploaded/image/gpeasy/admin_pages/image.png" name="gallery"><img alt="" src="/data/_uploaded/image/gpeasy/admin_pages/image.png" style="width: 100px; height: 100px; " /></a>

The above will cause the image linked to be opened in full size in Colorbox; however, Colorbox does adjust the size of the image depending on the viewers screen size. Nonetheless, the image in the page is 100x100 and the full sized image will be opened by Colorbox. The image is 100x100 because I set those parameters when I insert the image via CKEditor. This is exactly what I did with the Happy Buddha image at the top of this page although, I did add a caption and mouse-over title that I'll cover shortly.

The second attribute is the rel attribute. By adding rel=""gallery_gallery" to the anchor we tell gpEasy that that particular image/link is to be included as a "gallery" image with any other images on that particular page with that same attribute, rel="gallery_gallery"

<a href="/data/_uploaded/image/gpeasy/admin_pages/image.png" name="gallery" rel="gallery_gallery"><img alt="" src="/data/_uploaded/image/gpeasy/admin_pages/image.png" style="width: 100px; height: 100px; " /></a>

Notice that this link has both the "name" and "rel" attributes. That's because the "name" attribute MUST be in the anchor to tell gpEasy to open that link in Colorbox while the "rel" attribute is optional. Furthermore, the above link tells gpEasy to lump the image in with any other links on the page with the rel="gallery_gallery" attribute so they can be scrolled through in Colorbox. If the "rel" attribute is left out then you can only open one image at a time. When it is added you can scroll through the images just like in a gallery regardless of where they are placed on the page. They will scroll in consecutive order based on their appearance within the page from top to bottom. You can see this effect in any gallery page. I did not apply it here because it's very common so see in action, thus the Happy Buddha image does not have the rel attribute applied to it.

That's really all there is to enabling Colorbox for non-gallery pages. Test it out and play with how the name & rel attributes function. It's fairly easy.


Unlike gallery pages you don't have a caption field to enter anything in an image. So, is there a way to add a caption? Of course there is. Colorbox uses the "title" attribute of an anchor as the caption. So, let's add a caption to the above image.

<a title="This would be the caption in colorbox" href="/data/_uploaded/image/gpeasy/admin_pages/image.png" name="gallery" rel="gallery_gallery"><img alt="" src="/data/_uploaded/image/gpeasy/admin_pages/image.png" style="width: 100px; height: 100px; " /></a>

Notice the title="This would be the caption in Colorbox"? That's the title attribute for the anchor and it will be displayed as a caption. You can actually format it with HTML if you want. You will notice I do that a lot in the pictorial tutorials. However, the anchor's title attribute will also be displayed on mouse-over and if we use HTML formatting it looks a little ugly and may not be what we want. So, can we have a caption and a clean mouse-over title? Yep!

All we need to do to accomplish that is add a "title" element to the "img" element. The Happy Buddha image has the title attribute added to the anchor & img elements. You can see that it has a different mouse-over title than the caption. You can also look that is page's source code to see exactly how that all looks for my Happy Buddha image.

<a title="This would be that caption in colorbox" href="/data/_uploaded/image/gpeasy/admin_pages/image.png" name="gallery" rel="gallery_gallery"><img alt="" src="/data/_uploaded/image/gpeasy/admin_pages/image.png" style="width: 100px; height: 100px; " title="This would be the mouse-over title" /></a>

Do you see the "title" attribute at the end? The title attribute in the img element takes precedence over the title element in the anchor for display on mouse-over in most modern browsers. Therefore, you can have a different title for the mouse-over than what shows up in the caption in Colorbox. Give it a try. It looks pretty good. So why don't I have that in my gallery pages for my pictorial tutorials? Because gpEasy handles a lot of the code for a gallery page and currently strips the title attribute from the img element so it won't work there.

Drawbacks of enabling Colorbox

There is one major drawback to enabling Colorbox for a theme or entire site. It can slow down the page load time. So, if you enable Colorbox on a theme that's on every page of your entire site then it will be loaded for every page of your site even if you don't have images on a page that you want opened in Colorbox. HOWEVER. . . if you are a smart one. .  you will enable Colorbox on a separate theme and apply that theme to pages you want Colorbox enable for. Does that make sense? If not, just keep on reading. . .

Enable Colorbox per Layout

Can you enable Colorbox for a layout? Not exactly. Because the code to enable Colorbox needs to be inside of a theme's template.php file you can't enable it just for a layout; however, I'm going to show you an easy way to get nearly that.

Make a duplicate copy of the theme you want to enable Colorbox for. Give that theme a different name so you know it's your Colorbox Enabled theme. Then add <?php common::AddColorBox(); ?> to this duplicate theme.

Next, open the duplicate theme's style.css file and delete all it's contents and add an @import pointing to the original style.css file of the original theme.
Example: @import url("/themes/ThemeFolderName/style.css");

Why did we do that? You don't have to but it you make any changes to the original theme's css now you will only have to do it to the one file and the duplicate will import that CSS. It just keeps us using one CSS for a theme.

Now you should have a "duplicate" theme that has Colorbox enabled. Simple enough? Now add to it your layouts and name it so you remember that it's the Colorbox enabled theme. Make sure you edit the layout so it looks correct. Then simply apply it in the File Manager on a per page basis. This way Colorbox will only load when this particular layout loads.

That's a simple trick to enable Colorbox easily without having to enable it for the entire site or your regular theme. Remember you can add a theme to the layouts as many times as you like and customize each addition with a different layout.

That's exactly what I did for this page. It's the same theme I use for my site in general, but duplicated with an @import for the CSS & Colorbox output function added then I just added it to the layouts and edited it to look like my other gpEasy CMS pages. It may sound odd or even difficult but it really is very simple.

OK, that's it for this one. You should be able to play with Colorbox and images on any page at this point. Head back to the gpEasy tutorials page for more.

gpEasy B2sq Theme by CS @True Acupuncture