Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
133 lines (97 sloc) 6.17 KB


A "Choose Your Own Adventure" plugin for interactive storytelling, from the apps team at Mother Jones, that uses Google Spreadsheets to drive a simple and fluid story telling experience.


Examples in the wild

Is Your Vote in Danger? Take the Test

Are You a Slut?

What's Mitt Romney's Stance on Immigration?

Interactive Quiz: Should Texas Expand Medicaid?

Want to Ditch Citizen's United? A DIY Guide

Think You Can Beat the Immigration Maze?

How it works

MoJo users: Before you get started, follow these instructions.

What this tool does is allows you to take a simple spreadsheet set up, populate with questions, answers, images and sourcing, and then let readers navigate their way through a story. Here's how you do it:

Set up your Google Spreadsheet

The setup is pretty straightforward. Here's what it will look like:


You can make a copy of this template and move the copy into the relevant beat folder in the Mother Jones Google Drive. Rename the spreadsheet as you see fit. Change the owner of the spreadsheet to MoJo Data in Share > Advanced.

In order for the slider to be able to read your spreadsheet, you'll need to make your new spreadsheet public. Go to File and click on Publish to the web, then click on Start publishing.

A URL will appear. It will look something like this:

Copy that link. This is your spreadsheet ID or url, which you will use to connect your spreadsheet to the slider. The part of that URL you'll really need is between the key= and the &.

Modify your project files

MoJo users: By now you should have a local clone of this project repo on your machine. If you don't, go back and follow these instructions.

In your copy of index.html (required):

You're going to need to drop your key into line 12 of the index.html file (see below the line that starts "var cyoa = ...")

<!DOCTYPE html>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width" />
        <link href="css/style.css" rel="stylesheet" />
        <script src="js/jquery.js"></script>
        <script src="js/tabletop.js"></script>
        <script src="js/script.js"></script>      
        <script type="text/javascript">
            jQuery(document).ready(function() {
                    // this pulls from the spreadsheet that can be found at
                var cyoa = jQuery.Cyoa('0AswaDV9q95oZdHRQUlVQcDBJRU44NFdzc3lIeElkQXc',
                     { separator : ',',
                    control_location: 'bottom'
        <div class="cyoa_wrapper">
        <div style="clear:both" id="cyoa_container"></div>

Alternately, you can use tabletop to connect to google spreadsheet and automatically write the JSON needed to power the CYOA.

<script src="jquery.js"></script>
<script src="dist/cyoa.min.js"></script>
<script src="tabletop.js"></script>
    jQuery(function($) {
            'the key to your published google spreadsheet',
            { separator: '|' }

So long as you've set up

Column headers for your google spreadsheet must be slug, text, connects to, connects text, title, background image, The connects to should be a pipe-separated ( this is the "|" under the delete key) list of slugs which you want the page to connect to. The connects text should also be a pipe-separated separated list of what you want the connectors to read. If you like, you can designate a different character as the separator. Note that the order of the connects to and connects text must match.

Wow. That's a bit to take in, isn't it. Here's our original Google Spreadsheet again so you can remind yourself what we're talking about here.

When you make the function, you can also feed in your options; in addition to how you want to separate your info, you can choose how the controls appear the controls are 'left', 'right', 'centered', and 'split' like so:

    jQuery(function($) {
            'the key to your published google spreadsheet',
            { separator: '|',
              control_position: 'centered'

Hoping to sneak around Google's arbitrary rate limits? CYOA now supports a tabletop_proxy setting, which gets pased on to the Tabletop.init() call.


Because you're using images and not background images, and because they're now responsive, you need to make sure all of them are of a minimum height - the overflow:hidden on the viewport will hide oversized images but if an image is short, it will make the entire container short.


Hit us up by email, or Twitter: @jaeahjlee or @tasneemraja


Copyright (c) 2012 Mother Jones