Strict Standards: Only variables should be assigned by reference in /home/aotearoa/public_html/ on line 24

Problems with Joomla 2.5 and Twitter Bootstrap Carousel

Yesterday I spent about 3 hours determined to get something to work that just wouldn't. In the end I had to give up. It was taking to much time, my frustration level had maxed out and I had a pile of other things to work on.

Long story short: if you're having problems with a Bootstrap carousel in Joomla 2.5 just go download the DJ-ImageSlider extension and use that. You'll save yourself a tonne of time and pain.

Initially I was disappointed that I hadn't been able to solve the problem, and also annoyed at the time I had wasted. But after reflecting upon in I realised that in a round about way I'd actually learned something. I had learned what hadn't worked. I should probably have learned to call it quits earlier and move on, but as a developer that's an easy lesson to learn yet hard to put into practice.

Anyway, I thought I'd attempt to document what the problem was, how I tried to fix it, and what I ended up doing. This will hopefully help someone else who comes across the same issue - maybe it will at least save them some time.

Twitter Bootstrap

Recently we've been using Twitter Bootstrap more and more as a quick way to start building templates. I won't go into it in much more detail because you obviously know what it is if you're here. If you do need more information you can find out here.

It's no secret that Joomla 3.0 has integrated Twitter Bootstrap into the core, so it's incredibly easy to get started building a Joomla 3.0 template with Bootstrap.

But we're talking about Joomla 2.5 here. Since 3.0 has only just been released and there's no immediate rush for everyone to migrate/upgrade to 3.0 there's still a majority of Joomla sites running 2.5 (or less), so we'll continue building templates for Joomla 2.5 for a while to come.

Incorporating Bootstrap into a template is no big deal, you just link the CSS as per normal, and then you can also include the Bootstrap Javascript file if you want to use the features that require Javascript.

I did want to use one of the features that required Javascript...

The Twitter Bootstrap carousel

It's called a Carousel in Bootstrap. Other sources call it an Image Slider, Image Rotator, Image Cycler, etc. The idea is basically the same though: you have a bunch of images that you want to rotate through.

There's plenty of image slider extensions available for Joomla 2.5 already, but I wanted to use the Bootstrap carousel because:

  1. I've already loaded Bootstrap in the template. No need to load a bunch more CSS and Javascript.
  2. The markup for the Bootstrap carousel is really nice and clean, it's easy enough to write the HTML for the carousel by hand
  3. I actually like the simplicity of the Bootstrap carousel. There's not 100 different config options required. You get a nice clean carousel where each slide can have caption with title & description on it. Nice.

The Problem

I started with a simple 3 slide carousel that I'd statically coded and added to a Custom HTML module.

The carousel rendered fine, image showing properly, previous and next buttons showing. But when the carousel cycled to the next image the carousel slid up as it transitioned to the next image, stayed there for a bit, then slid back down as it transitioned to the next image.

So I would see image 1, the carousel would then slid up and I wouldn't see image 2, then it would slide back down and I'd see image 3.



Is the module rendering causing an issue?

I initially thought it may have something to do with the code in the module, maybe something was getting stripped by the Joomla WYSIWYG editor? So I pasted the carousel code directly into the template index.php file and deleted the module.

Tried it again - the problem still existed.

Is the markup for the carousel?

Maybe there was an issue with the markup for the carousel? I went to the Twitter Bootstrap site, copied the exact example from there, replaced the image references with my own and then saved that directly into the template index.php.

Problem still existed.

Do I have the latest version of Boostrap?

So the actual example code from Bootstrap has the same problem. Maybe I don't have the latest versions of Bootstrap CSS & JS?

Download the latest versions, replace the files I'm using (which were actually the latest anyway) and try again.

Problem still existed.

Google is (usually) your friend 

Very weird. Let's try Google to see if I can find anyone else having the same problem.

I can't remember exactly what I searched for, I recall trying a couple of different terms like:

"twitter bootstrap +carousel +sliding +up"

"twitter boostrap carousel issues"

Couldn't really find anything specific to the issue I was having.

I get frustrated with the results returned from Google, so I go back to trying to figure out the problem for myself.

Does the carousel on the Bootstrap site work in my browser?

Go back to Bootstrap site and check the carousel there - yes it works!

I checked the example code, making sure I have exactly the same code (except the change of images to mine), and also check the Javascript they're using to call the carousel - exactly the same as I'm using.

Didn't I use the carousel on a Joomla 3.0 site?

I suddenly remember that I used the Bootstrap carousel on a Joomla 3.0 site just the other day.

I go have a look at that - yes it works. So I copy the exact code from that, HTML & JS and paste into my Joomla 2.5 template.

It doesn't work!

Use Firebug to see what's going on

I inspect the carousel element on the 2.5 site to see what's going on when the carousel runs.

I notice that there's an extra div tag wrapped around the carousel who's height gets decreased to 0 when the first image transitions to the second and so on.

Is that normal?

I inspect the carousel in the 3.0 site - NO, it's not happening there.

Next I check the module rendering code - maybe that's adding the additional div when it renders the module?

Nope - the module rendering code is clean as a whistle, and if I look at the generated source code in Firefox I can see that there is no extra div wrapped around the carousel div.

So it must be getting added dynamically through Javascript?

Process of elimination

Within my template index.php I start removing Javascripts automatically included by Joomla in the head:

$doc = JFactory::getDocument();


After removing all those MooTools related scripts the carousel suddenly works as normal!

BUT! There is a javascript error being thrown by the 'JCaption' code that tries to attach itself to 'window.addEvent'.

That's not ideal - I can't fix an issue by breaking something else.

Is it MooTools version issue?

I attempt to include the latest version of MooTools from Google code, to see if that'll fix it.

Nope.To be honest I'm not sure if the version of MooTools shipped with Joomla 2.5.7 is a standard version anyway, plus there's the core.js, caption.js and mootools-more.js files that I need to work out how to deal with.

That sounds like a world of pain just to understand the relationship between all those files. Move on.

Can I remove the extra div through Javascript?

What if I could just remove the extra div that is wrapped around the carousel?

I write a quick & dirty script that found the parent div of the carousel, copied the carousel HTML out into another element, then deleted the parent (the one that was having height decreased to 0, etc.)

Something like (Javascript):

var carousel = jQuery('#myCarousel').parent().html();

Something like that (sorry, I no longer have it since I just deleted everything in the end).

Yeah well that didn't work either. I think there's two reasons why:

  • the carousel behaviour was attached to that actual DOM element in the first place.
  • the extra div gets added WHEN the .carousel(); initialisation is called, NOT when the page loads.

Back to Google?

Okay, so I know a bit more about the issue. It seems to be specific to how MooTools is behaving in Joomla 2.5, let's search on that...

"joomla 2.5 twitter boostrap carousel"

This question on Stack Overflow comes up first:

It's exactly the issue I've been having.

I read all the responses and suggestions. One person explains that it is in fact MooTools conflicting with the carousel, but all the suggested fixes involve stripping out MooTools or switching to using only one Javascript framework.

That might be all well & good for a specific site, but I'm trying to make templates that can be used across a multitude of different sites. Sites that I don't know exactly what other extensions are installed on, etc. This means that I can just go stripping out MooTools because chances are someone is already using that for some other function on their site.

Also, MooTools is loaded on the Joomla frontend for any number of reasons. I know it's loaded for frontend editing, but I don't know for what else and I don't have time to audit Joomla trying to work out where else it's required and would cause errors if I just rip it out.

The Solution

After all this stuffing around I decided there's no more time to waste. I'm going to use an alternative to the Bootstrap carousel.

I install DJ-ImageSlider and set that up - No more problems!

Yeah I know you may be thinking "You didn't even solve the problem!".

That may be true - it depends what your definition of the problem was. I wanted a carousel/image slider for Joomla 2.5, which is what I got in the end.

I didn't solve the issue of why the Twitter Bootstrap carousel doesn't play nicely with MooTools in Joomla 2.5 (or should that be, why MooTools doesn't play nice with the carousel?!), which really annoys the developer in me.

But at the end of the day the result I got was:

  • A carousel that works
  • A carousel that looks how I wanted it to on the frontend
  • No javascript errors occurring as a result of ripping out code

I guess that's got to be classed as a small win, besides the time wasted.