tech

Friends With Benefits: Adapting MoJo’s Choose Your Own Adventure App


Note: this is cross-posted on the Texas Tribune Nerd Blog. I’ve made a few minor revisions to my sections, but the main thing I’d like to add is that this technology has really interesting possibilities for telling stories about any topic: genderimmigration, voting, you name it. For the tech-curious, it’s a low-effort, high-payoff first project.

By Amanda Krauss and Becca Aaronson

Amanda says:

I think Mother Jones‘s choose-your-own-adventure (CYOA) interactive flowcharts are the perfect  way to make serious issues fun, engaging, and a little less scary for everyday readers. After reading their first CYOA story (the hilarious Slut Quiz) I was excited to see that MoJo’s dev team had released a CYOA plugin for general use, and totally geeked to meet creators Ben Breedlove and Tasneem Raja at this year’s NICAR, where Texas Tribune reporter Becca Aaronson and I were attending a live workshop on how to make a CYOA.

Becca says:

Only a total nerd would get as excited as I did watching Tasneem demonstrate MoJo’s Choose Your Own Adventure (CYOA) app at NICAR last year. What immediately struck me was how easy it would be to adapt the code for our website.

I’m a journalist, not a programmer, but I’ve learned to code because sometimes coding is necessary to create the stories that I want to tell. In addition to working on the NewsApps team, I’m also the Trib’s health care reporter, so there isn’t always time for me to devote to coding. (You may have noticed we’re rolling out this insanely complex federal health care law in a state filled with leaders that oppose it.) That’s why I love when programmers design applications like MoJo’s CYOA that are easy for journalists to adapt and change to fit their storytelling needs. It’s also easy for us to forget that learning how to code can be really intimidating for journalists. CYOA is a great icebreaker to get journalists to realize how easy it can be to create some news apps.

Amanda says:

Becca wanted to make her first CYOA interactive to help people explore Medicaid expansion, and I helped her with the code. After restructuring and styling the CYOA app to be responsive and mobile-friendy for our site, I contributed to the main project repository, meaning that I proposed changes and they were accepted. That was pretty exciting. Recently, Becca decided to make another CYOA to help Texans understand their options under the Affordable Care Act, and that gave us another opportunity to experiment with Tribune-branded styling and better performance.

Becca says:

When we attended the workshop, I was consistently covering Medicaid expansion (or lack thereof) in Texas, and a lightbulb just went off in my head that the application would be perfect for creating an interactive quiz to help people determine where they really stood on the issue. One of the things I noticed in my reporting was that many proponents of Medicaid expansion crossed political party lines, but because Obamacare was so politicized many people outside the health care community didn’t think about the issue enough to really figure out whether they thought Medicaid expansion was a good idea or not. So, Amanda and I adapted the CYOA code to fit our Tribune style and I created a quiz for people to figure out where they really stood on the issue.

So how easy is it to create a CYOA app? Let’s walk you through the process.

First, you need a good idea. The CYOA app is basically a flow chart, so it’s useful for showing many answers to a question. For our most recent CYOA app, the question was basically, what’s my best option for complying with the health insurance mandate in 2014? There are lots of different answers, depending on the person and situation, so the topic lent itself really well to a CYOA app.

To get started, I recruited our intern Edgar Walters to help me research the many answers to that question. We sat down and brainstormed the best way to direct people to the right outcome. Here’s a picture of our first draft:

image

A good start, but we needed to flesh out the details. Here’s the second draft:

image

You’ll notice that it’s really just a flow chart. The next step is to move the flow chart from paper to a spreadsheet. While the spreadsheet may look complicated, it’s really not. The column headers are called from the Javascript, so keeping the column headers consistent is important.

image

slug: The unique ID for a slide.

text: The text that you want to appear on the slide. i.e. “Do you currently have health care coverage?”

connects to: A list of the unique IDs or slugs for the next slides that you want to send the user to. They should be separated by a “|”. Remember, you’ll have to create a new row for each “slug” that you list.

connects text: The text that you want to appear for the person to select that will lead them to the next slide. For example, “Yes” or “No.” These should also be separated by “|” and in the same order of the list of slugs that you want the person to be connected to.

background image: A hyperlink to an image or gif. MoJo has done some really hilarious CYOA apps using this field to add funny gifs in the background. But for something serious like health reform, we chose to keep it simple and left this blank. Works either way!

sourcing: Text to show the source information on the slide. Not necessary, if you want to leave this blank.

source link: A hyperlink to the source information. Also, not always necessary.

So, what’s that look like? Here’s an example from the Medicaid Expansion CYOA spreadsheet:

The CYOA app loads the information directly from Google spreadsheets using Tabletop.js. So when you’re finished inputting your flow chart into the spreadsheet, all you have to do is publish it to the web (Under File>Publish to the web.) Also remember to make sure your share setting is set to public! Once you’ve published, you’ll see that Google has given your spreadsheet a unique “key.” The key for our spreadsheet is highlighted in the picture below. Grab and copy your “key,” because you’ll need that for your code.

Amanda says:

You’ll need to grab the code from the MoJo repo.  You’ll need an index HTML page, and you’ll link the Javascript and CSS files to that. Most of the initial debugging involves making sure all the files are correctly linked – if it’s not working, just look in the console to see what’s up.

The CYOA code is pretty simple. The HTML on the main page looks like this:


<div class="cyoa_wrapper">
<div class="cyoa_container"></div>
</div>

That’s it! The script (usually located at the top of the page) is what does all the work, grabbing the container

div

and using it as a base to build the pages from the spreadsheet data Becca described above:


<script src="//s3.amazonaws.com/cdn.texastribune.org/lib/tt_cyoa/v2/cyoa.js"></script>
<script type="text/javascript" src="//s3.amazonaws.com/cdn.texastribune.org/lib/tt_cyoa/v2/tabletop.js"></script>
<script type="text/javascript" src="//s3.amazonaws.com/static.texastribune.org/media/flatpages/scripts/handlebars.js"></script>
<script type="text/javascript">
jQuery(document).ready(function() {
var cyoa = jQuery.Cyoa('0AgQB1XZuIQjddDh4NGQ1cXl5WnJzdkR5Tl9teHNIUFE', {
separator : '|',
control_location: 'bottom',
tabletop_proxy: '//s3.amazonaws.com/tabletop.texastribune.org'
});
});
</script>

The first script loads the plugin code for future use. The second script allows your spreadsheet to be imported. The third is a templating library that the plugin uses to make the pages. The last script is the one actually calling the plugin function to build the pages, and it needs all the previous files to be loaded to  do its work; you’ll see the key Becca mentioned in it – that’s how it knows where to get the information to build the pages. If all goes well, you’ll see your CYOA in the browser

Once you’ve got it working, there’s always some tweaking and debugging to do; this time we changed the CSS to make it look more like the Tribune branding, and fellow news apps developer Ryan Murphy found that we needed to update Tabletop, as well as pointing out this bug, which can interfere with performance.

In conclusion, building a CYOA is relatively simple, a really fun way to tell a story, and a great way to get on board the code train.

Becca says: