Getting Started

Tutorial: How to Implement a Toggler

We're going to start by making a toggler. What's a toggler? Well, it's an interaction that has two components to it: a button and content. When we click on the button, the content should appear. Here is an example of what we're going to build (click on "Clothing"):

We click on the button ("Clothing") and the content (the list of clothes) appears.

First Step: Adding Attributes to the HTML

Let's start with the basic, bare-bones HTML: we have a <div> for "Clothing" and then an unordered list with the items in it.

    <div>Clothing</div>
    <ul>
      <li>Hat</li>
      <li>Socks</li>
      <li>Shoes</li>
      <li>Gloves</li>
      <li>Shirts</li>
    </ul>
    

The first thing we need to do is wrap the whole toggler in a <div> with the data-ur-set attribute set as "toggler". This is basically telling Uranium that the whole thing in the <div> is a toggler.

    <div data-ur-set="toggler">
      <div>Clothing</div>
      <ul>
        <li>Hat</li>
        <li>Socks</li>
        <li>Shoes</li>
        <li>Gloves</li>
        <li>Shirts</li>
      </ul>
    </div>
    

This may have already caused a problem. What if we can't wrap the whole thing in a <div>? Well, there's a trick around that — check out the explanation of IDs here.

Next, we indicate where the button is. In our case, we want the button to be the Clothing <div>. So we give the clothing <div> the attribute data-ur-toggler-component and the value "button". (Want to know why the attributes are named so? Click here.)

    <div data-ur-set="toggler">
      <div data-ur-toggler-component="button">Clothing</div>
      <ul>
        <li>Hat</li>
        <li>Socks</li>
        <li>Shoes</li>
        <li>Gloves</li>
        <li>Shirts</li>
      </ul>
    </div>
    

The final thing we need to do to this HTML is specify the content bit of the toggler. The content in this case is the unordered list that we want to appear when the button is clicked. We give it the attribute data-ur-toggler-component (the same as for the button, if you remember) — but this time we use the value "content".

    <div data-ur-set="toggler">
      <div data-ur-toggler-component="button">Clothing</div>
      <ul data-ur-toggler-component="content">
        <li>Hat</li>
        <li>Socks</li>
        <li>Shoes</li>
        <li>Gloves</li>
        <li>Shirts</li>
      </ul>
    </div>
    

That's all we need to do with regards to HTML.

Second Step: Don't forget the JavaScript

We've added all the necessary attributes to the HTML. The next job is to make sure we have Uranium running in the page.

The Uranium file can be downloaded here.

Include it in your project folder, and add an appropriate reference to it in the head of the HTML.

Third Step: Changing the CSS

Now we've added the Uranium JavaScript to the page, go back and refresh the site. The moment of truth is upon us. Click on the button!

…

Ruh roh. Nothing seems to happen. Why not? Is the JavaScript broken? Let's check.

Right-click on your interaction and "inspect element". You'll see the button and the content <div>s have an extra attribute data-ur-state. This is, by default, set to "disabled".

    <div data-ur-set="toggler" data-ur-id="ur1" data-ur-state="enabled">
      <div data-ur-toggler-component="button" data-ur-state="disabled">Clothing</div>
      <ul data-ur-toggler-component="content" data-ur-state="disabled">...</ul>
    </div>
    

When the button is clicked, it changes to "enabled".

    <div data-ur-set="toggler" data-ur-id="ur1" data-ur-state="enabled">
      <div data-ur-toggler-component="button" data-ur-state="enabled">Clothing</div>
      <ul data-ur-toggler-component="content" data-ur-state="enabled">...</ul>
    </div>
    

The JavaScript is doing its job. The missing piece of the puzzle is the CSS.

What we need to do is change the styling of the page. It needs to be set so that the content does not display when data-ur-state="disabled", but to display when data-ur-state="enabled".

    [data-ur-toggler-component="content"][data-ur-state="disabled"] {
      display: none;
    }
    [data-ur-toggler-component="content"][data-ur-state="enabled"] {
      display: block;
    }
    

(This is actually what we call "explicit" CSS styling. What we're doing is defining what happens when the data-ur-state is "enabled" and what happens when it is "disabled." This is more robust than lazy styling, which only defines the styles that get applied in the "enabled" state. You can learn more about lazy vs explicit styling if you're curious.)

By this point, the interaction should be fully functional. Isn't it neat?

Fourth Step: Apply These Skills

Pretty much all the interactions in Uranium work in a similar way. You add special attributes to the tags in your HTML, import the JavaScript, and maybe do a little CSS re-styling.

Now we've whetted your appetite, you probably want to check out some more interactions. If you want to go through another tutorial, we have an advanced tutorial that covers how to implement a carousel with some custom features, all without writing a single line of JavaScript.