Guest Post: Publishing elections results on the cheap

Caitlin Ostroff is the Miami Herald's data reporter and a graduate of the University of Florida. Mike Stucka is the data dork at the Palm Beach Post and is a graduate of Northeastern University, Loyola University Chicago, and a great IRE bootcamp a decade ago. Today, they contribute a guest post to INN Labs about the elections software they built.

Want to get live election results on a shoestring budget? We did. The result is a multi-component package of election reporting tools that ease the way for newsrooms to build their own scrapers, output them in a semi-standardized format and optionally use a frontend for display.

Python code parses through several pipe-delimited text files published by Florida’s Secretary of State to get statewide results, and also scrapes local results for several counties. The key was to adopt pseudo-standards from software created by The New York Times and National Public Radio, who worked together to process election results from The Associated Press.

By building scrapers against the CSV format of the Elex package, it became easy to combine multiple levels of results that could be handled and processed by a single system. You can combine your own scrapers and AP's data — or just your own scrapers, or just AP's data — to get results for your pages. The Miami-Dade County scraper was easily adapted for Kentucky, and Palm Beach County's scraper easily became West Virginia's.

The Palm Beach Post built a front end by baking out the pages using Flask. Three scrapers ran on Election Night and were beaten into more than 500 different widget embeds for 11 newspapers, with each complete scrape-parse-build run taking about 40 seconds total.

The Miami Herald used JavaScript to parse out the results from a JSON file and render them to the Herald’s static media server, using fixed-size iframes of different breakwidths to bring them into its proprietary content management system. The Herald enabled cross-origin sharing, which allowed it to control caching in an .htaccess file.

Part of the Miami Herald's election results page, showing the ballot initiative results for Florida Amendment 13, which would end dog racing.
Part of the Miami Herald's election results page, showing the ballot initiative results for Florida Amendment 13, which would end dog racing.

There's a lot of flexibility: one of us un-called a race from a cell phone while waiting to pick up a kid from school, because the open-sourced publishing tool uses a Google Sheet to allow edits of race names, candidate names, parties, winners and runoffs.

In addition to rendering live election results, this setup also allowed both papers’ newsrooms easy access to data, from the margins between candidates to live vote count changes from newly-tallied votes. The data structures and workflow helped on election night and through a recount process that stretched more than a week. The Miami Herald and The Palm Beach Post used the code to render the current tallies as Florida inched closer to a recount after the election, as well as to drive analysis for reporting.

A screenshot of a line chart, showing that DeSanis, Scott, and Caldwell had high initial leads in the vote count, but their leads declined as more votes came in. Caldwell's lead disappeared entirely, ending up several thousand votes behind the competition.
Chris Persaud and Mike Stucka built a Datawrapper chart of Republican candidates' lead in vote counts, using data from their election handling tool.

Existing widgets ran with stories, and new widgets were fed in near-real-time from the data we'd pulled. The code for whole-election results gave both publications a framework for pulling precinct-level results.

How cheaply done was this? We think we might have gotten about five weeks total to work on this. A much more ambitious project is Politico's open-sourced Civic, on which a development team of five focused for about five weeks each to add improvements. Our effort is far more limited, but likely also a lighter lift to get started with. Weigh your options and see what fits your organization.

Would you like to use our code? The front-end is available now and you can check out the scrapers here and here, and all are released under the MIT License. You can use this code as-is or contribute improvements. We have a sample widget collection here, and implementations at the Herald and the Post. Want to improve the project? We'd welcome that; send a pull request, drop us an email, find us in News Nerdery, call us by phone.

Announcing: Pym.js Embeds version 1.3.2.1

The INN Labs team is issuing a major, Gutenberg-friendly update to the Pym.js Embeds WordPress plugin, formerly known as the Pym Shortcode plugin, which improves presentations of data journalism.

The Pym.js Embeds plugin creates a better experience for the reader with responsive embeds that scale to fit the story, reduces workflows for data journalists, and removes the need for tricky embed workarounds.

For more details, see our latest announcement. You can also learn more about the latest release on GitHub and download the plugin from WordPress.org.

Some New Tools for News Orgs from NICAR 2018

Chicago skyline from Lincoln Park

The INN Labs team spent a few days in Chicago for the NICAR conference earlier this month. We came back with plenty of inspiration and a long list of tools for journalism on the web. (Many more links can be found in Chrys Wu's annual NICAR roundup.)

Colors

  • Coolors: a fun generator to help build color schemes
  • ColorBrewer: find accessible color schemes for maps and other data visualizations.
  • Colorsafe: another color and accessibility tool, this time focused on proper contrast.

 

Interactives

 

Transcription

  • Otter.ai: notes for voice conversations.
  • Temi: fast speech to text transcription.
  • Cassette: more transcription and search.

 

Music

  • Amper: an AI composer for soundtrack music.
  • Take: an iOS app for recording and collaborating on musical ideas.
  • Figure: make beats and music on iOS.

 

Social Video and Images

  • This by Tinrocket: annotate images for social media use.
  • Legend: create text-based animations on iOS.
  • Spark Post: fast graphics for social media from Adobe.
  • Quik: create quick and simple videos on mobile devices.

 

Collaboration

  • Styleguides.io: publicly available style guides for code, design and content with plenty of ideas to crib from.
  • Dropmark: visual organization for links and files, like Pinterest meets Google Drive meets Delicious.
  • Mural: digital, virtual whiteboarding tool.

How We Made a Shared Inventory for Public Broadcast Stations

We recently had an organization come to us with a unique challenge: a group of public broadcast stations needed a way to see what other stations were working on. They wanted an easy way to spark collaboration, avoid any programming duplication, and see opportunities for cross-promotion.

We had to figure out the best way to go about creating a private, easily-accessible, and friction-less shared inventory (what we were also calling a pipeline) of programs for TV and radio stations scattered across the state.

Here’s how we did it:

First, we started by identifying the basic needs of the programmers and those who would be maintaining the inventory/pipeline. Remember, we wanted to keep it as friction-less as easy to use as possible! Then, we focused on finding existing tools which would offer the necessary features for the workflow while being easy to adopt and use. Below you’ll find an overview of the workflow we built. We hope that sharing this with you will spark ideas for ways to improve your own workflows - whether it be a shared pipeline or another use case.

As always, feel free to reach out to us if you have a unique challenge that we can help you solve!

Our workflow uses a private (password protected) page in WordPress, Google Forms, Google Sheets, a script for said spreadsheet, and Google Drive. Here’s how it all comes together:

Step 1: Limit access to the shared inventory/pipeline

A WordPress page became the hub for the private access to all the shared information. We created a password-protected page which has direct access to the form (more below), as well as a direct link to the spreadsheet (again, more below) which contains all the shared information.

Here’s how to create a password protected page in WordPress and how it looked to users:

The workflow we created relies heavily on Google tools, so a Google login for each contributor to the inventory/pipeline is necessary.

For example, the Google Form that's embedded in the private page requires you to log in to submit your responses. A login is also required to access the spreadsheet. This allows for another layer of restricting access and creates a history of track changes for each user.

Next, you’ll see how we created the form.

Step 2: Build a form to collect information for the shared inventory

We built our form using Google Forms. They’re easy to create, allow for collaborators, and seamlessly connect with other Google Tools, which in our case are Google Sheets, Google Drive and of course, the Google login for restricting access.

The fields we decided to use are the following:

Step 3: Funnel the form submissions to a spreadsheet

Once responses to the form are submitted, the user has an option to edit their submission or submit an additional form response. The submissions are automatically sent to a connected Google Sheet. Each form question has its own column in the Google Sheet and the responses are added as cells under each column. This is the case for all columns except two. The exceptions:

Program Upload

If a program is uploaded as a .pdf file, for example, then the file is saved in a Google Drive folder and a link to the file is automatically added to the spreadsheet.

Link to Edit the Form Submission

Since every form submission has a unique URL, we needed to find a way had to populate the special link to edit the submission alongside its corresponding set of responses. We were able to do that by using Google Apps Script.

Check out next week's blog post ("Fun with Google Apps Script!") for more information on how we did this.

Want to know more about how we did this? Get in touch!

How to use News Match Donation Shortcode

As part of INN's support for the 2017 News Match campaign, we've released two WordPress plugins to help sites convert readers. News Match Donation Shortcode provides a donation form for your site to ease donations through the News Revenue Hub as part of the News Match campaign.

Prefer a video walkthrough? Watch this tutorial on youtube.

Installing the plugin

On your WordPress site, click on "Plugins" in the Dashboard menu. If you see an "Add New" button at the top of the page, click that.

If you don't see the "Add New" button or the "Plugins" menu, your user might not have permission to manage plugins on the site; you should contact your technical support and ask them to install News Match Donation Shortcode for you. Your site might require downloading the plugin ZIPs and uploading them via FTP instead of using WordPress' built-in plugin installation tools.

Configuring the plugin

A screenshot of the plugin's locaiton in the wordpress settings menuThe plugin's settings are at Settings > News Match Shortcode in the WordPress admin.

When you first enable the plugin, you'll want to configure it with your organization's name, your News Revenue Hub ID, the default donation amount, and the live and staging URLs of your News Revenue Hub form.

The settings is where you configure the donation levels to match your organization's membership levels. While the plugin comes with 4 default donation levels, you can easily define your own labels and donation levels. The defaults are: $0-$5 Friend, $5-$50 Ally, $50-$500 Champion, and $500+ Ambassador. If you want fewer donation levels, set the third level's upper donation amount to a very high amount, such as your org's dream budget, and make sure that the fourth level is more than that.

A screenshot of the level 1 donation level settings.
Here's an example of non-default configuration of the first donation level out of four.

If you use Salesforce to track campaigns, you can set a default Salesforce campaign ID for the plugin in the plugin's settings. This can be overridden on a per-form basis by setting the sf_campaign_id attribute of the shortcode, like so: [newsmatch_donation_form sf_campaign_id="foo" amount="25"]

A screenshot of the WordPress admin dashboard shows the setting for the Salesforce Campaign ID
This is the Salesforce campaign ID setting in the plugin admin.

The shortcode in use

The default form of the shortcode uses buttons to select the donation level:

a screenshot of the donation form
[newsmatch_donation_form]
By adding type="select" to the shortcode, it appears like this:

a screenshot of the dropdown donation form
[newsmatch_donation_form type="select"]
A full list of shortcode arguments and examples can be found in the plugin's WordPress.org entry, but they're basically one-off overrides for your Salesforce campaign ID, your default donation amount, and the type of form.

The above screenshots use the plugin's default styles with non-default configuration. You can style the donation form using your site's theme's CSS, Jetpack’s Custom CSS Editor, or any other tool that allows you to define custom styles on your site. Guidance for these custom styles can be found in the FAQ section of the plugin's WordPress.org entry.

Need support?

If you have questions about this plugin and integrating it with your WordPress site, contact support@inn.org.

If you have questions about the News Revenue Hub, visit their contact page.

If you have questions about the News Match program, visit their website for donornonprofit and funding partner information.

Pym Shortcode plugin update: version 1.3.1

Last week, NPR released Pym.js version 1.3.0, and earlier this week released 1.3.1. These feature releases introduced optional scroll tracking, allowing the child iframe to know where the browser is on the parent page. You can read more about how that's implemented, and how it can be used, on the NPR Visuals Team blog post announcing Pym 1.3.0. Pym.js version 1.3.1 added a function getParentPositionInfo to the Pym child.

Pym Shortcode version 1.3.1 brings you the latest version of Pym.js, as well as the following improvements:

  • Adds an id="" attribute to allow setting of custom IDs on embeds, for Github issue #21. The id="" attribute is useful if you want to load a new embedded page inside the iframe and maintain Pym functionality.
  • Adds a class="" attribute to allow setting custom of classes on embeds, for Github issues #22 and #23. The class="" attribute allows you to, among other things, add layout classes to embeds so they take a different shape on your page.
  • Adds a default class name pym to all embed-containing <div> elements output by this plugin, and a filter pym_shortcode_default_class to allow changing the default class or removing it.

You can download the new version of the Pym Shortcode plugin through your WordPress dashboard, on the WordPress.org plugin repository, or on Github.

If you have feedback on the plugin or would like to contribute to development of the Pym Shortcode plugin, check out our contributor guidelines and join the conversation in the plugin's GitHub issues or in our Slack.

Storytelling Tools Plugin for WordPress

https://wordpress.org/plugins/storytelling-tools/

If you're not familiar with them already, The Knight Lab at Northwestern University has built some great storytelling & visualization tools for journalists, all of which are freely available on their website.

Knight Lab Storytelling Tools

You may have already seen some of these tools in action as a reader and not realized what they were. Their Timeline, StoryMap, Juxtapose, and Soundcite tools have been featured in Time, The Washington Post, ESPN, and ProPublica, to name a few.

Even better, the Knight Lab has taken steps to make it as easy as possible for anyone to build these visualizations and embed them on their site. Each tool has its own page on the Knight Lab site that contains either a wizard to guide you through building the visualization or detailed information and examples on how to do it yourself (in the case of Soundcite).

Why We Built The Plugin

When you use the online wizard to build one of these tools, you'll get a few different options to embed the finished product on your website. If you're publishing on Medium, you'll receive a link you can just paste into your editor. If you're using WordPress or another platform, there's some iframe code you can add to your editor. For Soundcite, there are some rather detailed instructions for WordPress users, because you need to include the Soundcite JavaScript file that builds the players.

For non-technical users, relying on code to embed these tools can be difficult, and even prevent people from using these tools. We saw an opportunity here to add first-party support for these tools in WordPress, allowing for the same automatic embeds as Medium and a shortcode for Soundcite. Now, anyone can begin using these tools in WordPress without any coding skills!

More Info

By this point, you're probably thinking, "WOW, where can I get this plugin to start using it myself?!?"

You're in luck - it is freely available on https://wordpress.org/plugins/storytelling-tools/ or you can install from the comfort of your own website's plugin section. At that link, you'll also find detailed information about each of the tools and how to use them on your site.

If you have any questions or suggestions, you can always contact us via email, open a ticket on Github, or leave a note for us in the WordPress.org forums. We look forward to hearing from you!

Building A WordPress Donation Form Using Gravity Forms, MailChimp and Stripe

Please note: The following article contains outdated information has since been updated. Please use the up-to-date guide here


Here at INN, we've built a lot of donation forms for our members. Over the last year, we've created a standard set of forms and integrations that you may find useful as a starting point for building your own donation forms.

Note that this is a loooooong post and if it seems overwhelming, we'd encourage you to stick with it and experiment with these tools.

If you get stuck or just want to hire us to help, we're also happy to work with you to get you up and running. Now that we've standardized a lot of this work, we're often able to get a site using our Largo WordPress platform up and running with a donation form that looks and works great in just a few hours!

Get in touch if you'd like to discuss that option.

Here we go!

We start with WordPress and Gravity Forms, and add the following plugins:

We typically use Stripe to process payments because the fees are lower and it offers more flexibility, but Gravity Forms has add-ons for PayPal and several other payment gateways if you'd prefer to use one of those.

Stripe charges 2.9% of the transaction total, plus a $0.30 flat fee per transaction (with no monthly or annual fee). We use the subtotal merge tag plugin to create a checkbox that gives users the option of paying the fees so that their entire donation amount goes to the organization they're choosing to support.

In addition to collecting money, donation forms are an excellent place to ask donors if they want to become newsletter subscribers. We add a checkbox to our default donation form and conditional logic and the Gravity Forms MailChimp Add-On to automatically add donors to an organization's mailing list.

Gravity Forms also allows you to automate the sending of receipts and donation acknowledgements and also to send notifications via email or Slack when a new donation is received.

For our sites, we've created some boilerplate code containing default styles and a clean WordPress template for use on these donation pages. We've also included importable form templates, if you'd like to use our form designs.

Does this sound like something you want to use? Read on - the full set of instructions are below.

Installation

First, get the following things:

  • Gravity Forms Developer license in order to download two of the plugins from Gravity Forms. A developer license costs $199/year and will allow you to use the plugin and any add-ons on as many sites as you would like. For INN members, we pay for a developer key for all sites we host. If you want to use our group license, just contact our support team and we'll help you get that set up.
  • Stripe API key for handling purchases. (Stripe charges a transaction fee for most accounts; following this instruction set will help you cover that transaction fee)
  • MailChimp API key for sending a newsletter to your subscribers. (MailChimp's pricing varies based on mail volume)
  • An SSL certificate (if you want to accept payments directly on your site). For sites we host, these are available for free through our hosting company (via Let's Encrypt). If you'd like us to request a certificate on your behalf, just open a support ticket and we can take care of this for you. For sites using other hosting you'll need to check with your hosting provider to see what options are available.
  • (optional) a reCaptcha site key, to help prevent spam submissions

Once you have your credentials in hand, install these plugins:

All of those must be installed manually, because they're not available in the official plugin repository. If you have FTP/SFTP access to your site, you can upload them to the plugins directory of your site using an SFTP client or similar program. WordPress.org has instructions on how to do this.

You can also install them from the WordPress dashboard by going to Plugins > Add New. Click on the Upload Plugin link next to the page title and you can upload the zip file of the plugin you'd like to add.

Once you've installed the plugins, you'll need to also activate them. To do this, go to the Plugins screen and find the newly uploaded plugin in the list. Then, click Activate to activate it.

For sites we host, we have to install and activate the plugins for you. If you'd like these plugins enabled on your site, just contact our support team and we'd be happy to assist.

Configuration

Each add-on has a configuration section in the WordPress dashboard, at Forms > Settings.

Gravity Forms

You'll need to enter your Gravity Forms support license key in the Gravity Forms plugin settings.

Gravity Forms Stripe Add-On

The Stripe add-on has four keys that you'll need to enter:

  • Test Secret Key
  • Test Publishable Key
  • Live Secret Key
  • Live Publishable Key

You can create/access these from the API Keys tab of the Account Settings page in Stripe.

There's also a set of radio buttons for switching your site from using the Test API to the Live API. Note that you'll need to switch this both here on the settings page and in the Stripe dashboard itself. If you're using Stripe for the first time, note that you'll also need to have provided your bank information before Stripe will allow you to switch to Live mode.

Typically, when you're setting up a new form, you'll use the Test API to run some test transactions using their testing credit cards to make sure everything works before switching your form/site to Live mode.

Follow the instructions on the Stripe add-on settings page to add your site's Gravity Forms callback hook to your Stripe account. If you are testing the form on a staging site, note that the callback URL should be your live site or else the callbacks will not work properly (this is something to also double check on your site before making the new form live).

Gravity Forms MailChimp Add-On

If you're going to use your donation form to collect email addresses for your MailChimp newsletter, you need to add your MailChimp API key.

You can get a MailChimp API key by logging in to MailChimp and going to Account > Extras > API Keys. There, click on Create A Key and give it a name (something like "Gravity Forms" should suffice) and then copy the newly created key and add it to the Gravity Forms MailChimp Add-On settings in the field provided.

Create your donation form

We've created a couple of sample forms based on the forms we've developed for a few of our members/clients. We recommend importing one of these forms first so that you can examine how things are put together before attempting to create a form of your own. You might even find that one of the example forms will work well for you with very little modification!

Create form by importing

Gravity Forms allows you to import forms from JSON files, so we've provided two example donation forms that you can download and import to get started.

To import a form, save the importable .json file from either of the above links, then upload it following Gravity Forms' import instructions.

Once you've imported a form, find the form in the list of forms and click "Edit." From here you'll see the various form fields and how they're configured. Note that each of these examples uses conditional logic to show/hide certain form fields depending on the options a donor selects in the form. For more on how conditional logic works in Gravity Forms, see the relevant section of their documentation.

If you like how one of the example forms works, you can move on to setting up notifications, confirmations and the MailChimp and Stripe feeds to ensure they are set up correctly with your site's information.

Refer to the Gravity Forms documentation if you have specific questions.

Create a form from scratch

After you've imported one of the forms above and examined it to see how it's put together, you may want to try your hand at creating a form that's more tailored to the individual needs of your site.

A few general best practices for donation forms:

  • Include a default donation amount (we find that $20 is a good default for one-time donations and $10 is a better default for recurring donations) but make it easy for people to specific their own amount.
  • Provide the option to make the donation a recurring donation on a monthly or yearly basis. Both Gravity Forms and PayPal have options to set up recurring donations and this is a great way to save yourself a lot of time and effort in trying to get donors to renew their membership in the future.
  • If you're a nonprofit, you'll need a way to send a tax receipt to the donor: email addresses and postal mailing addresses both work. Personalized notes are best, particularly for first-time donors or those who have consistently supported you, but Gravity Forms also allows you to automate the sending of receipts (see the section below on setting up notifications).
  • Request as little information about a donor as possible. You want to make it as easy as possible for people to give you money and asking for too much information or having a very long form will cause many donors to give up and never complete their donation. Make sure you are only collecting information that you actually intend to use, and wherever possible, explain how that information will be used and why you're collecting it.
  • Collect the user's email address for confirmation and thank-you emails related to this transaction, but do not add them to your mailing list without their explicit permission. In most of our forms, we' do this by adding a checkbox (usually checked by default) to opt a donor into receiving further messages from the organization.
  • In general, single page donation forms are best unless the form is very long. With Stripe, you can add the necessary credit card fields at the bottom of the form directly before the submit button. With PayPal, you'll have to send a donor off to PayPal to complete the transaction. This is one of the reasons we prefer Stripe. Note that if you handle the credit card information directly on your site, you will need to have an SSL certificate that is configured correctly to serve your donation page over https.
Set up notifications

You'll probably want to receive notifications from your website when someone submits a response to the form. To do this, find your form in the list of forms, hover over it, and then click "Settings" when that text appears.

Under the "Settings" tab are at least three tabs: "Form Settings," "Confirmations," and "Notifications" are the default ones.

Under Confirmations you can set what happens when a donor submits the donation form. Gravity Forms gives you a couple options here but we typically prefer sending people to a thank you page after the form is successfully submitted. If you don't want to create a thank you page, you can also just choose to display some confirmation text.

If you want to send users to a thank you page, first you need to first create a WordPress page to send them to. Here's an example on INN's website. Once the page is created, go back to the settings for the form you're working on and click on "confirmations". Now, select the "Page" option, choose your page from the drop-down list of pages, and save the confirmation:

A screenshot of the Gravity Forms Confirmation settings, showing the choice of a "Page" confirmation with the "Thank you!" page chosen.

Under the Notifications tab, you can set which email notifications are sent when a form is submitted. Typically, you'll want to send an email to one or more members of your staff to let you know a new donation has been received and also send an email to the donor with the details of their donation.

In the INN example form, two notification emails are sent on submission:

The first one is sent to the site administrator, with a subject of {form_title} and message body of {all_fields}. These form fields surrounded by curly brackets are Gravity Forms' merge tags, and allow you to put information from the form into the email. Note that you can send notifications to multiple email addresses by adding each address separated by commas in the "send to email" field.

The second confirmation is sent to the email address provided by the donor in the form, thanking them for their donation and again using the {all_fields} merge tag so that the donor has a receipt for their donation. Note that you can use conditional logic here if you'd like to send different confirmation messages to different segments of donors based on the information they submitted. So, for example, you could send a different confirmation to one-time vs. recurring donors, or an automated response to low-dollar donors but send yourself a notification for large-dollar donors so you can send them a personalized note.

Set up the link to Stripe

The Stripe connection for each form is configured in the form's settings area, in a "Stripe" tab that appears underneath the "Notifications" tab. The Stripe settings area allows you to create different "Feeds" for this form.

A "Feed" is a type of transaction and a single form can have multiple types of transactions. In the INN example, there are three feeds: a monthly recurring donation, a yearly recurring donation, and a one-time transaction. These donation types are respectively categorized by Stripe as "subscription," "subscription," and "products and services."

You don't have to have multiple feeds. Sometimes all you want to do is create a one-time donation form. If that's the case, you can skip ahead to the "One Time Donation" example below, and ignore the "Conditional Logic" box.

When creating a donation form with multiple donation types, add a "Radio Buttons" element to let the donor choose between "Per Month," "Per Year," and "One Time".

A screenshot of a selection box for choosing between "Per Month", "Per Year", and "One Time"
An example form element with radio buttons.

Then, in the Settings area for this form, create three Stripe feeds, matching the donation types.

A screenshot of the settings page for a Monthly Recurring Stripe feed, showing the options as they are set when the INN form is imported.
A screenshot of the settings page for a Monthly Recurring Stripe feed, showing the options as they are set when the INN form is imported.
A screenshot of the settings page for a One Time Donation Stripe feed, showing the options as they are set when the INN form is imported.
A screenshot of the settings page for a One Time Donation Stripe feed, showing the options as they are set when the INN form is imported.

If you have multiple feeds set up (because you have multiple types of donation) make sure to check the "Conditional Logic" box and set it to only process that feed if the value of the "Donation Type" form element you chose is set to the radio button label that corresponds with this donation feed.

The payment amount should be "Form Total" so that you capture the processing fee, if that option is enabled.

You may also want to send over other information to Stripe so that you have other metadata associated with the "customer" record that will be created when a payment is processed. The "metadata" section here allows you to provide the name(s) of the fields as you want them to appear in Stripe and then map those to the form fields submitted on your site.

Once you have this set up, run some test transactions. Make sure that the Gravity Forms Stripe Add-On is in "Test" mode by going to Forms > Settings > Stripe and checking the "Test" option for the API. Make sure your API keys are entered. Press the "Update Settings" button to make sure. Then grab some testing credit card numbers from the Stripe website and test every option on the form, confirming with in the Stripe dashboard that the test transactions completed successfully.

Set up the link to MailChimp

Most of the sites we work with want to also give new donors the opportunity to sign up for one or more mailing lists. We use the Gravity Forms MailChimp add-on to enable this option.

Before you set up a MailChimp feed in Gravity Forms, you'll need to have already created the mailing list you want to add people to and also make sure the fields you want to send over are configured correctly in MailChimp.

Once you have the Gravity Forms MailChimp Add-On installed and enabled, a MailChimp tab will appear in the form's settings section. Here, you can configure which of the submitted form fields match up to MailChimp's fields in its database for subscribers.

There is a checkbox to enable double opt-in, so that the donor receives an email to confirm that they would like to sign up to receive your newsletter, but it's commonly assumed that by checking the "Sign me up" checkbox, your donor has consented to receiving your newsletter.

At the very bottom of the MailChimp settings tab for the form is a checkbox labeled "Conditional Logic." Check this box to show the conditional configuration options. We're going to change the conditions so that the MailChimp integration only sends the email address to MailChimp when a box is checked.

a gif showing how to change the conditional logic works
Choose the field name from the left box, the "is" equivalency option from the middle box, and the text of the checkbox from the right box.

Setting up styles for forms

The forms that you've set up above will work as-is, but they're not particularly pretty. Gravity Forms' form HTML is complex and contains some weird opinions. The stylesheets that Gravity Forms includes are similar: weirdly scoped, curiously specific, and often a bit perplexing.

There are several ways to dequeue Gravity Forms' default styles; Zack Katz has an excellent blog post detailing the ways to dequeue them.

However, because Gravity Forms' styles are at least partially useful, we keep them enqueued and modify them. Here's the modifications we make:

These example styles are scoped to the form IDs and they also depend on a wrapper class that can be added to your form settings but they may not be immediately applicable to your form if the form ID or CSS class is different. We hope that these are at least useful as a starting point.

Good luck!

We hope this was a helpful introduction on how to setup donation forms using WordPress, Gravity Forms, MailChimp and Stripe.

Again, if you found all of that overwhelming and would like to hire us to help, just reach out and we'd be happy to help get you up and running!

 

News Quiz Shortcode Plugin Now Available On WordPress.org

A little while ago, our apprentice, Will Haynes, released the initial version of what we're now calling the News Quiz Shortcode. We're happy to announce that the plugin is now listed in the WordPress plugin directory.

Built on top of Mother Jones’ NewsQuiz.js library, this WordPress plugin allows you to build a quiz in Google Drive and embed it with a shortcode into a WordPress post.

Screen Shot 2016-06-17 at 1.46.01 PM

This could be used to test readers’ understanding of material, or just to expose them to the questions in an interactive way.

Grading of questions happens inline, at the bottom of the widget. Settings exist to control both the size and flow of the plugin, as documented in the project readme.

Try out the example quiz embedded in this post, or check out how INN member Youth Today is using it to support a piece exploring how the income gap affects scoring on college entrance exams.

To see how to build a quiz of your own using this plugin, how to format your Google spreadsheet, etc. please see Mother Jones’ documentation for the original quiz library.

Here's the sample quiz from the example:

Introducing the Super Cool Ad Inserter Plugin For WordPress

After several months of development, we're pleased to announce the initial release of a plugin that will help publishers automatically insert widgets in the middle of posts: the Super Cool Ad Inserter Plugin (SCAIP, for short).

SCAIP creates widget areas that are inserted programmatically into every post after every Nth paragraph.

A screenshot of the configuration page of the Super Cool Ad Inserter Plugin
Here's the main SCAIP settings page. Read more about these settings in the plugin's documentation.

You can then fill the widget areas that SCAIP creates with ads, newsletter signup forms, donation messages, other calls to action, related posts widgets, or really anything else that fits in a WordPress widget (including the default text/html widget).

To see the plugin in use, check out Religion News Service, which uses another one of our plugins, DoubleClick for WordPress, to insert ads within posts after every few paragraphs. The Cornell Daily Sun uses WordPress text widgets to display ads within posts using another ad network.

Another example is this screenshot, which shows the plugin in use in the WordPress.org Twenty Thirteen theme, inserting image widgets. Anything contained in a WordPress widget can easily be inserted by SCAIP.

Ads are normally inserted automatically, but the plugin also supports shortcodes to allow manual placement of the widget areas within posts, and per-post overrides to disable automatic ad placement.

To learn more about what the plugin is capable of, check out the docs or download the plugin and try it out! We're eager for your suggestions, bug reports and pull requests on GitHub or in the open tech channel on the INN Slack.

Developers will be happy to learn that the plugin is easy to integrate with themes. Our Largo WordPress theme required no changes to support SCAIP, and we believe that is the case with other themes.