Screenshot from 2015-01-21 15:36:57

Bootstrap Carousel Tutorial: getting started, then customizing — example code & bugs

Reading Time: 4 minutes

Recently I had “great fun” modifying bootstrap v3’s image gallery slideshow thingy, Carousel (click here to see an interactive example).

It has some nice features built-in, like indicators for what slide you are on, auto-scaling so it works on any browser window size, and an easy way to select options like cycling the carousel continuously, changing the interval between auto-slides, or reacting to keyboard events.

I made some modifications to get it to look and behave the way I wanted. Namely, I wanted readable captions underneath the images. Bootstrap has the captions overlaid on the image by default, and white-on-white doesn’t work so well.

I mostly succeeded… here’s a screenshot:

Screenshot from 2015-01-21 15:36:57
Live at doc.arvados.org someday soon…

…although I still dislike how verbose the Carousel code is. Oh well, our docs site was already using Bootstrap.

The how-to on bootstrap’s page is pretty terse and kind of confusing for me, so I’m writing up a more detailed explanation here.

stuff needed

From http://getbootstrap.com/getting-started/, download the zip file. You’ll need

1. css/bootstrap.css (you can use the .min version if you’d like, which is just compressed into non-human-readable form)

2. js/bootstrap.js (you can also get away with just carousel.js).

You’ll also need jquery.js from http://jquery.com/download/, try the link “Download the compressed, production jQuery 1.11.2”.

Note: We’ll include the javascript files at the end of HTML so most of the page loads quicker.

how to

Alright, now how do you include all these files? (see this gist for the full HTML file, or download a self-contained zip file of all the files: bootstrap-carousel-example).

Put the CSS at the top, either by linking to a .css file or including the CSS directly:

Inside the body section, put your Carousel HTML.  It’s kind of long so just check out the gist. Put the javascript at the bottom, either by linking to a .js file or else including it directly

step 3: profit?

If you load the html file in your browser, magic should now happen.

For reference, you can download this zip file where everything is set-up already: bootstrap-carousel-example

step 4: customize

What if we want the images to cycle faster, or the images to not cycle at all?

Okay, I’ve already shown how you can select some of the built-in bootstrap options using javascript:

You can select individual carousels on a page by naming the carousel

and then using a more specific jquery call

Alternatively, if you want some option to apply to all carousels on a page / site, you can pull this code out into a separate file

and include it in each HTML file

A third way to change an the options on a carousel is to include it in the HTML, like so:

step 5: sweeter customizations!

Now, to make more custom modifications, I had to fiddle with the CSS. A few hours later, I made the modifications you can see at this gist. Alternatively, download the zip file and uncomment the line

trouble-shooting tips (bugs!)

First, cool tools:

1) Use firefox or chrome’s powerful built-in developer tools. The default shortcut to bring them up is ctrl-shift-c (you actually can’t get rid of our change this shortcut easily, which is annoying).

You can delete things, edit things without refreshing the page or modifying files, and other wonderful tools.

Screenshot from 2015-01-21 16:44:34
Screenshot of Firefox’s “Inspector” tool in use.

2) Use a Javascript hint tool, such as http://jshint.com/.

If you just use the Console tool in Firefox Inspector to see the javascript error messages, it is fairly cryptic.

Tools like JSHint can provide some more helpful feedback about what went wrong.

bugs

these things tripped me up:

1) the Bootstrap website makes ( and { look very similar on my computer, so I skipped the curly brackets and used

instead of the correct

UPDATE 03 April 2015

I filed a bug on github: https://github.com/twbs/bootstrap/issues/16225, or as follows:

Font in code blocks on http://getbootstrap.com/ does not distinguish { and ( clearly, can cause anguish for newcomers to javascript. Please remove the Courier New font fallback option. Just monospace works well.

In Detail

I was following the the example at http://getbootstrap.com/javascript/#carousel, and my brain removed the “extra parenthesis” I think, similar to how you don’t notice I doubled “the” in this sentence unless I point it out.

This is a screenshot of the bootstrap website “code” block font currently on my computer:
js-bootstrap-font

Please remove the courier new font fallback option. Just monospace works well.

Results in the much-better

js-bootstrap-font-better

(Most open-source projects in have nice websites but no issue tracker nor contact info for their own website or their documentation, only for their github repo around the actual code, and it’s not always clear where to file a bug…)

END UPDATE

2) I didn’t realize I needed to include the jquery file first, so I got cryptic messages like “$ is undefined”.

3) I spent a while debugging a weird gap that left the rightmost controls in midair. It occurred when the browser window was too big. Turns out I needed to hardcode a max-width, which I just hardcoded to be slightly smaller than the smallest image width I had.

appendix

Here are the files used in this tutorial again:

Gist

bootstrap-carousel-example.zip

social medialulz

facebooktwittergoogle_plusredditpinterestmail

Leave a Reply

Your email address will not be published. Required fields are marked *