Advanced Implementation of Uranium

Introduction

In the getting started tutorial, we introduced how to implement a basic Uranium interaction: the toggler. We went over the basics — adding attributes to our HTML elements to confer interactivity on them.

The toggler interaction is pretty simple — we only had three elements to add attributes to. The carousel has a few more components, which is why this is a slightly more advanced tutorial. We'll also cover some optional features of carousels, plus introduce the concept of a Uranium ID.

Tutorial: How to Implement a Carousel

We're going to start by making a carousel. Carousels are very prominent in the web today — they allow the user to swipe through a number of images — or use buttons if necessary.

Below is the carousel we are going to implement through this tutorial. Some prominent features are the autoscroll feature that advances images, the "dot" indicators showing the index of the image, and the "Previous" and "Next" buttons for navigating through the images.

You can swipe through the images on any touch device (to test this out on the desktop, it's probably best to enable touch events on Chrome), use the "Prev" and "Next" buttons to navigate through them, or just let them scroll automatically. Let's get started.

First Step: Setting up the Elements

Like other Uranium interactions, when building the carousel we start by creating a wrapping <div> with the carousel set.

    <div data-ur-set="carousel">
    </div>

Once we have that set up, we can add our next container — the scroll container. The scroll container should be nested within the set, and will contain all the images through which you want to scroll.

    <div data-ur-set="carousel">
      <div data-ur-carousel-component="scroll_container">
        <img src="http://placekitten.com/g/100/100" alt="1">
        <img src="http://placekitten.com/g/100/100" alt="2">
        <img src="http://placekitten.com/g/100/100" alt="3">
        <img src="http://placekitten.com/g/100/100" alt="4">
        <img src="http://placekitten.com/g/100/100" alt="5">
      </div>
    </div>

In the example above, we have five images. You'll notice that we're using PlaceKitten for the src attributes — this is so you can easily copy the code in our example. Of course, you can use any image src if you want.

Each image (or other item that is being scrolled) must have a component of "item" associated with it.

    <div data-ur-set="carousel">
      <div data-ur-carousel-component="scroll_container">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="1">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="2">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="3">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="4">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="5">
      </div>
    </div>

All the elements for the most basic carousel are there. However, there's one small bit of CSS we must add in order for the carousel to work. Add the following to your stylesheet.

    [data-ur-set="carousel"] {
      overflow: hidden;
      position: relative;
    }
    [data-ur-carousel-component="item"] {
      float: left;
    }

Second Step: Adding Features

We have a working carousel, but at the moment all that anyone can do is swipe back and forth. This may be great for a simple use case, but let's have a look at some other features we can add to the carousel to make it more interactive. Let's start with the autoscroll, which will automatically move items forward every 5 seconds.

All we need to do is add another attribute to our set: data-ur-autoscroll="enabled".

    <div data-ur-set="carousel" data-ur-autoscroll="enabled">
      <div data-ur-carousel-component="scroll_container">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="1">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="2">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="3">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="4">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="5">
      </div>
    </div>

If you want to customize the autoscroll, you can use the extra attribute data-ur-autoscroll-delay, where the value is in milliseconds. For example, if you wanted the carousel to advanced every 3s, you would use data-ur-autoscroll-delay="3000". We'll keep ours at the default for now.

The next item we will set up is a set of "dot" indicators, showing which item of the carousel we are on. These are incredibly easy to set up in Uranium. All we need to do is use the attribute data-ur-carousel-component="dots".

    <div data-ur-set="carousel" data-ur-autoscroll="enabled">
      <div data-ur-carousel-component="dots"></div>
      <div data-ur-carousel-component="scroll_container">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="1">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="2">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="3">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="4">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="5">
      </div>
    </div>

If you refresh straight away, you'll notice that nothing is obviously there. That's because Uranium allows you to style the dots as you want. Within the "dots" element, Uranium added the following HTML:

    <div data-ur-carousel-component="dots">
      <div data-ur-carousel-component="dot" data-ur-state="inactive"></div>
      <div data-ur-carousel-component="dot" data-ur-state="inactive"></div>
      <div data-ur-carousel-component="dot" data-ur-state="inactive"></div>
      <div data-ur-carousel-component="dot" data-ur-state="active"></div>
      <div data-ur-carousel-component="dot" data-ur-state="inactive"></div>
    </div>

Within the "dots" <div>, we have a number of <div> children with two attributes — one specifying it as a "dot" and one showing the state. The data-ur-state of "active" is applied when the corresponding item is highlighted. So, for the example above, the fourth image will be highlighted. Currently the dots have no style associated with them, so you won't be able to see them. Feel free to style them as you like!

Some sample styles similar to the ones we use in our original example

        [data-ur-carousel-component="dot"] {
          border-radius: 5px;
          background: #bbb;
          display: inline-block;
          margin: 0 5px;
          width: 10px;
          height: 10px;
        }
        [data-ur-carousel-component="dot"][data-ur-state="active"] {
          background: #000;
        }

Now we have our dot indicators and auto-scrolling feature enabled, time to move onto implementing our final carousel feature: the previous and next buttons.

Final Step: Buttons and Items External to Sets

Say we have some buttons that we want to add to our carousel. These buttons would allow people to scroll to the previous and next items in the carousel. That's pretty simple — we can just add some attributes to some divs to create buttons. However, in our case we have some HTML constraints that mean the buttons must be outside of the set. This is where we introduce the concept of an ID in Uranium.

Firstly, let's ignore the IDs and just add our buttons outside of the set. They will be non-functional for now, but if the same code was inside the set, they would work fine (this is how we would normally create buttons for a carousel). Each button needs an attribute of data-ur-carousel-component="button".

As well as the button attribute, they each need an attribute to distinguish the "previous" and "next" buttons. The attribute for this is data-ur-carousel-button-type. Check the button syntax out below.

    <div data-ur-set="carousel" data-ur-autoscroll="enabled">
      <div data-ur-carousel-component="dots"></div>
      <div data-ur-carousel-component="scroll_container">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="1">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="2">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="3">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="4">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="5">
      </div>
    </div>
    <div data-ur-carousel-component="button" data-ur-carousel-button-type="prev">Prev</div>
    <div data-ur-carousel-component="button" data-ur-carousel-button-type="next">Next</div>

As mentioned previously, the buttons will not work at the moment as they are outside the carousel set. However, we can make them work by using a Uranium ID. We give the same ID to the set and both of the buttons. This allows Uranium to match up the buttons with the appropriate carousel. The syntax is data-ur-id="carousel-id".

    <div data-ur-set="carousel" data-ur-autoscroll="enabled" data-ur-id="first-carousel">
      <div data-ur-carousel-component="dots"></div>
      <div data-ur-carousel-component="scroll_container">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="1">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="2">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="3">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="4">
        <img data-ur-carousel-component="item" src="http://placekitten.com/g/100/100" alt="5">
      </div>
    </div>
    <div data-ur-carousel-component="button" data-ur-carousel-button-type="prev" data-ur-id="first-carousel">Prev</div>
    <div data-ur-carousel-component="button" data-ur-carousel-button-type="next" data-ur-id="first-carousel">Next</div>

Uranium IDs can also be used for both tabs and togglers. If the button and the content cannot be placed in the same HTML element set, they can be separated physically and joined via the same Uranium ID. We have a page about grouping Uranium enabled HTML elements that goes into more detail about this, if your're curious.

Now that you have gone through the advanced Uranium tutorial, you should feel confident playing around with all the interactions and using their optional and advanced features. For example, with the carousel you can add a counter as a numerical indicator of the index of the item you are on. These options and more are available on the carousel interaction page.