Overview

Introduction to Uranium

Uranium offers web page authors the ability to add several convenient JavaScript interactions to the HTML elements on their pages, without writing a single line of JavaScript.

For example, you might have a page with a set of sub-sections that each have headers followed by related content, one right after the other. With the Uranium toggler interaction, you could transform that into an accordion just by adding a few data attributes to the existing HTML elements.

Uranium interactions are not opinionated about styling and layout. You should be able to add the Uranium script and a few data attributes to practically any working web page that uses jQuery (as far back as version 1.3), and take advantage of these useful interactions right where you need them most.

Basic Requirements

Since Uranium builds on jQuery, the minimum you need to do to get Uranium working on your page is to include the latest jQuery script followed by the Uranium script. A good place to do this is right before the closing tag for the body element on your HTML document.

      <html>
      <head>
        <title>Uranium Sample Page</title>
        <style>
          ...
        </style>
      </head>
      <body>
        <div data-ur-set="toggler">
          <h1 data-ur-toggler-component="button">This is your page</h1>
          <p data-ur-toggler-component="content">And this is the content of your page</p>
        </div>
        <script src="scripts/jquery-1.9.1.min.js"></script>
        <script src="scripts/jquery.uranium.js"></script>
      </body>
      </html>

Just download the latest minified version of jQuery, and the Uranium script, and save them in your scripts directory. Then reference them in your HTML document, and you should be good to go.

If there's a conflict with another jQuery version, you can either remove one of them or separate one from the global namespace:

      <script src="scripts/jquery.uranium.js"></script>
      <script>Uranium.$ = $.noConflict(true);</script>

Data Attributes

Data attributes can be added to any HTML element. We use data attributes instead of modifying the id or class attributes of HTML elements so that Uranium can be injected into existing pages as easily as it can be added to new pages, without affecting existing styles and JavaScript.

The syntax is simple. Just add the data attributes the same way you would add any other attributes to an HTML element. For example, to tell Uranium that a specific <h2> element should be used as a toggle button to show and hide the following paragraph, you might start with something like this:

      <div>
        <h2>Information</h2>
        <p>This is content we want to hide and show</p>
      </div>

… and end up with something like this.

      <div data-ur-set="toggler">
        <h2 data-ur-toggler-component="button">Information</h2>
        <p data-ur-toggler-component="content">This is content we want to hide and show</h2>
      </div>

Just adding those data attributes to a page that has jQuery and the Uranium script loaded would enable the desired interaction.

Interaction Sets and Components

Every interaction has at its core a set and a series of components. The set is unique for every interaction: data-ur-set="toggler" for the toggler interaction, etc. The set attribute should be used to wrap the whole interaction.

There are usually a few components per interaction. Some may be required to get the interaction to work, but most are usually optional. For example, a toggler has a button and content, and at least one of each is required if you want the interaction to work. Components are designated in the following way: they'll have data-ur-{interaction}-component="thing".

Most of the interactions also have some extra options. For example, carousel has an optional data-ur-carousel-component="count", which is used to display the count of the currently selected item in a carousel.

Recommended Styles

Uranium tries to be as unopinionated as possible when it comes to styling. Uraniun interactions typically perform their magic by adding, removing, or changing the values associated with data attributes on HTML elements. How you choose to style these different states is entirely up to you.

That said, there are some basic types of styles that will be needed to see how the Uranium interactions behave. Generally, you are going to want the toggler interaction to toggle whether or not that toggler's content can be seen. One way to do that — although by no means the only way — is to have the CSS apply a rule of display: block to toggler content when it is supposed to be seen, and a rule of display: none when it is not supposed to be seen.

On the pages describing each of the Uranium interactions, you can see some basic recommended styles that will make that interaction's behavior visible. But those are for demonstration purposes only. Uranium can be used with any CSS you can dream up!

Additional Resources

Tutorials

To familiarize yourself with how Uranium can be added to a page, we've written up some tutorials demonstrating how to work through a basic and an advanced Uranium use-case. As you'll see, even the advanced example follows the same basic philosophy, allowing you to integration useful JavaScript interactions just by adding a few declarative elements to your HTML.

Basic Use: Creating a simple toggler
Advanced Use: Building a custom carousel with optional features

Additional Documentation

We've written up some more detailed notes on some of the ways in which Uranium is unique. Uranium is not trying to be all things to all people, but for those who need something lightweight, unopinionated, and focused on injecting simple interactions in a declarative manner, Uranium just may be the answer.

Philosophy: The guiding philosophy behind Uranium and the interactions we support
Model: general information about the model on which all the interactions are based
Styling: "lazy" and "explicit" styling of interactions
Grouping: when to use sets and when to use IDs