Pym.js Embeds version 1.3.2.3: Now with AMP ⚡️ support!

It's hard to do truly custom interactives work within WordPress. INN Labs' Pym.js Embeds plugin is built to make it easier for your newsroom to embed your latest data project, with help from NPR's Pym.js library.

Other solutions often involve pasting JavaScript into the post editor, disabling or bypassing parts of WordPress' security filters, or using interactive-builder plugins that limit your creative freedom.

All that Pym.js Embeds requires is a place to host your interactive as a standalone HTML page, and that you use NPR's Pym.js library in your interactive to make it resizable. Our plugin provides the seamless WordPress integration. Take the URL of your interactive and embed it in posts using the Block Editor or shortcodes. We handle the rest!

For the first time, thanks to the efforts of Claudiu Lodromanean and Weston Ruter, the Pym.js Embeds plugin supports the official WordPress AMP ⚡️ plugin. With both plugins installed, your Pym.js-based iframes will now be displayed as <amp-iframe> tags when your site is viewed through AMP.

Since amp-iframe now includes Pym.js's messages as a supported protocol, your embedded content is now more likely to work in AMP sites than it was before. As Google drives more content to your AMP pages, your readers will continue to have the same first-class experience they'd have if the reader viewed your full site.

This release also fixes some minor documentation issues, and we've improved this plugin's contribution guidelines on GitHub for external contributors.

Connect with the INN Labs Team

If you're using this plugin, let us know how you're using it! Send us links to cool things you've done with it; we'd love to include them in our weekly newsletter.

If you'd like to learn more about INN Labs' open-source WordPress plugins and tools for publishers or how we can work together on your next project, send us an email or join us at one of our weekly Office Hours.


Announcing Version 1.0 of the Link Roundups Plugin

INN Labs is pleased to announce an important update to the Link Roundups plugin!

If you run a daily or weekly newsletter collecting headlines from around the state, region, or within a particular industry, the Link Roundups plugin will make it easier to build and feed your aggregation posts into MailChimp.

The Link Roundups plugin helps editors aggregate links from around the web and save them in WordPress as “Saved Links”. You can publish these curated links in a Link Roundup (more below), display Saved Links and Link Roundups in widgets and posts in your WordPress site, or push Link Roundups directly to subscribers via MailChimp. It's designed to replace scattered link-gathering workflows that may span email, Slack, Google Docs and spreadsheets and streamlines collaborations between different staffers.

Why might you want to use this plugin? Here are a few reasons:

  • It creates a single destination for collecting links and metadata
  • On sites that publish infrequently, it provides recently published (curated) content for your readers
  • Weekly roundup newsletters or posts are a great way to recap your own site's coverage and build and diversify your audience, which can increase donations

Saved Links

The central function of the Link Roundups plugin is the Saved Link. It's a way of storing links in your WordPress database, alongside metadata such as the link's title, source site, and your description of the link's contents.

A screenshot of the Saved Links interface, showing many saved links and their respective metadata: authors, links, descriptions, and tags.

Save to Site Bookmarklet

When WordPress 4.9 removed the "Press This" functionality, this plugin's bookmarklet broke. This release's updates to the Saved Links functionality include a renewal of the "Save to Site" bookmarklet, based off of the canonical Press This plugin's functions. If your site has the WordPress-maintained Press This plugin active, your site users will be able to generate new bookmarklets. We include instructions on how to use the bookmarklet in the latest release.

A screenshot of the "Save to Site" button and its copy button

Once you've accumulated a few Saved Links, you can display them on your site using the Saved Links Widget or start to create Link Roundups (see next).

Saved Links Widget

Common uses of this widget include "coverage from around the state" or "recommended reads" or "from our partners" links.

It's a good way to point your to expert coverage from newsrooms you partner with. With the ability to sort Saved Links by tag, you can easily filter a widget to only show a selection of all the links saved on your site. Here's how Energy News Network uses the widget:

A screenshot of the widget as it appears at Energy News Network, showing a selection of links from the last day.
A screenshot of the widget as it appears at Energy News Network, showing a selection of links from the last day.

Link Roundups

Link Roundups are one of the best ways to present Saved Links to your readers. Collect links with Saved Links, then create a Link Roundup post with the week's curated links. The person who assembles the Link Roundup doesn't have to deal with messy cut-and-paste formatting or composing blurbs — when your users create Saved Links, they're already adding headlines, blurbs, and sources.

Add some opening and closing text, and you're most of the way to having composed a morning or weekly news roundup.

Link Roundups are a custom post type with all the Classic Editor tools and an easy interface for creating lists of Saved Links. As a separate post type, they can be integrated into your site's standard lists of posts or kept separate in their own taxonomies. You don't have to integrate the roundups with your standard posts flow; it's why we provide a Link Roundups widget to fulfill your widget area needs.

MailChimp Integration

Link Roundups don't have to stay on your site. If you configure your site to connect to the MailChimp API and create a newsletter template with editable content areas, you can send a Link Roundup directly to MailChimp from WordPress.

From the Link Roundup editor, you can choose a mailing list, and create MailChimp campaign drafts, send test emails, and send drafted campaigns directly. If you'd rather open a draft campaign in MailChimp to finalize the copy, there's a handy link to your draft campaign.

A screenshot of a settings metabox: choose a campaign type of regular or text. Choose a list to send to: the Link Roundups Mailchimp Tools Test list, with the group "are they Ben" option chosen: "Ben". The campaign title will be "Test Title Three Title", the test subject will be "Test Title Three Subject", and the template will be "Link Roundups Test 2"
Here's the MailChimp settings for the Link Roundups campaign editor: Many of the controls that you'd want to use to create and send a draft campaign.

More information

For more information about how the plugin works, see the Largo guide for administrators, the plugin's documentation on GitHub, or drop by one of our weekly open office hours sessions with your questions. You can also reach us by email at support@inn.org.

If you already have the Link Roundups plugin installed, keep an eye out for an update notice in your WordPress dashboard. If you'd like to install it, download it from the WordPress.org plugin repository or through your site dashboard's plugin page.

This update was funded in part by Energy News Network and Fresh Energy, with additional funding thanks to the generous support of the Democracy Fund, Ethics and Excellence in Journalism Fund, Open Society Foundation, and the John S. and James L. Knight Foundation.

Link Roundups is one of the many WordPress plugins maintained by INN Labs, the tech and product team at the Institute for Nonprofit News.

Plugin Release: Disclaimers

Let's start with some ancient history. Our flagship WordPress theme, Largo, descends from work that NPR did in the early 2010s under the name The Argo Network. The network's work included best-practices recommendations for working with WordPress in news, published at the Argo Project, and an open-source WordPress theme called Argo, which INN forked in 2012.

Fast-forward a few years. INN was working on a big refresh of WisconsinWatch.org for the Wisconsin Center for Investigative Journalism, and was bringing in new features in Largo to support that refresh. The 0.4 release of Largo included a disclaimer widget that could be used to provide site-wide or per-article disclaimers and disclosures.

Today, we're happy to announce that that functionality is available to all WordPress users, with the launch of the Disclaimers plugin. 🎉

The plugin's site-wide settings page, showing an example setting of "This is an example sitewide disclaimer."
The plugin's site-wide settings page, showing an example setting.

The widget settings page, showing the Disclaimers widget added to the "Article Bottom" widget area. The active theme is Largo.
The widget settings page, showing the Disclaimers widget added to the "Article Bottom" widget area. The active theme is Largo.

The Disclaimers widget, displaying a sitewide disclaimer, set at the bottom of an article.
The Disclaimers widget, displaying a sitewide disclaimer, set at the bottom of an article using the Largo theme.

With the Twenty Seventeen theme active, this site has chosen to put the Disclaimer widget at the top of the sidebar.
With the Twenty Seventeen theme active, this site has chosen to put the Disclaimer widget at the top of the sidebar.

Here's what the per-post settings look like on a site using the Gutenberg editor plugin. The same subset of HTML is supported in this box as your site supports in the post body.
Here's what the per-post settings look like on a site using the Gutenberg editor plugin. The same subset of HTML is supported in this box as your site supports in the post body.

A screenshot of a post in Twenty Seventeen displaying a more-complex disclaimer with HTML bold, strong, emphasized, italic, and link tags in use.
A screenshot of a post in Twenty Seventeen displaying a more-complex disclaimer with HTML bold, strong, emphasized, italic, and link tags in use.

Largo sites running any current version of Largo don't need to install this plugin now, but we will be removing the corresponding disclaimers functionality from Largo in the next release. The migration process will be as painless as we can make it, with all your existing disclaimers carried forward.

Stay tuned for more plugin announcements in the coming months! You can subscribe to our newsletter or follow us on Twitter at @innnerds to receive updates. Or, just watch our blog here. We even have an RSS feed!

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.

How to use News Match Popup Basics

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 Popup Basics provides a little guidance and some useful tools for using popups in your campaigns.

Prefer a video walk through? Watch this tutorial on youtube.

News Match Popup Basics does the following:

  • Creates a new popup with our recommended default settings, using the free Popup Maker plugin
  • Provides a way to disable popups on your donation pages
  • Provides a way to disable popups when readers click a link in your Mailchimp-powered newsletter

Let's walk you through installing the plugin and getting it set up.

Installing the plugin

News Match Popup Basics requires the Popup Maker plugin, so first we need to install that.

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 Popup Basics for you. Your site might require downloading the plugin ZIPs and uploading them via FTP instead of using WordPress' built-in plugin installation tools.

After clicking "Add New" you should be on the "Add Plugins" page. In the "Search plugins..." box, enter "popup maker" — you should see an entry named "Popup Maker™ – Best Rated" appear, by "WP Popup Maker." Click "Install Now" to install the plugin, and then click "Activate". You'll be sent to a page asking you to allow sending certain information to a third party. You can press the "Skip" button without any negative effects. Whether you choose to skip or accept, you'll be taken to the list of Popup Maker popups: none yet exist, and that's okay.

Go back to the "Plugins" page, and inn the "Search plugins..." box, enter "news match popup basics innlabs" and choose the presented popup named "News Match Popup Basics" by "innlabs" — that's our plugin. Install and activate it.

In the Dashboard menu, choose the "Popup Maker" item. This will take you back to the "Popups" page you saw earlier, but there should now be a draft popup named "News Match Default Popup." Click on it.

You'll see an editor page that looks rather like the default WordPress post editor, but with a number of exciting new boxes. You can read more about those boxes at the Popup Maker plugin documentation, which is thorough and well-illustrated.

Our default settings for the popup are these:

  • is not published by default, but requires you to publish it before it becomes active on your site
  • is the size “Large” from Popup Maker’s settings
  • appears at the center of the bottom of the reader’s screen
  • appears by sliding up from the bottom of the screen, over 350 milliseconds
  • has a “Close” button
  • does not prevent readers from interacting with the page by means of an overlay
  • does not have a title
  • automatically opens after 25 seconds on the page, because immediate popup appearances can be jarring
  • once dismissed by a reader, does not appear again for a year or until the reader clears their browser’s cookies, whichever comes first
  • appears on the front page of your site
  • uses Popup Maker’s default theme

You'll need to configure which pages the popup appears on, using the built-in conditionals feature. For disabling the popup on certain pages or in certain cases, read on in this blog post, or check out Popup Maker's paid extensions.

You'll also probably want to review the Popup Maker themes available and modify them to suit your own site's appearances. Once you've modified or created a theme, edit your popup to make it use your theme.

In addition to using Popup Maker themes, you can style popups using your site's WordPress theme's CSS, Jetpack’s Custom CSS Editor, or any other tool that allows you to define custom styles on your site.

What goes in a popup?

We recommend donation forms or newsletter signup forms. For a simple donation form that integrates with the News Match campaign, check out News Match Donation Shortcode.

Finding the News Match Popup Basics settings

From the WordPress Dashboard menu, under Popup Maker, choose "News Match Popup Basics." This is where you configure whether the plugin disables certain popups.

Disabling popups on certain pages

Donation pages should help people give you money, and should have as few obstacles to that goal as possible. Likewise, newsletter signup pages. Strip out ads, remove unnecessary headers, maybe even clean up your footer on these pages. Donation and signup pages should do one thing and do that well.

Popup Maker's free version includes a simple yet powerful Boolean conditionals system that determines on what pages popups appear, but that system only works on a per-popup basis. Preventing popups from appearing on a particular page requires checking every single popup on your site, and modifying their conditions. We've endeavored to make the process simpler.

In the News Match Popup Basics settings, check the box to enable donation page popup prevention, and add some URLs to the box. Each URL must be on its own line. You should remove the protocol from the start of the URL, so that https://example.org/ is entered as example.org/.

A screenshot of the WordPress admin showing the News Match Popup Basics settings page, focused on the URL-based popup suppression feature's settings. The URLS given are example.org/donate/, example.org/newsletter-signup/, and /about/
Example settings for the URL-based popup prevention feature of News Match Popup Basics.

When a visitor goes to a page the URL of which matches one of the entered URLs, News Match Popup Basics will prevent Popup Maker from displaying any popups on that page. You can include URL fragments as well, so if you want to prevent popups on pages that have a common URL name, like every page that has donate in its URL.

Be careful with how general your URL fragments are. By "match" we mean that if the entire text on the line in the box can be found in the URL, it will match:

  • example.org/meow/ will only match example.org/meow/ and example.org/meow/woof/
  • /meow/ will only match example.org/meow/, example.org/meow/woof/ and example.org/2014/03/25/meow/
  • meow will match example.org/meow/, example.org/meow/woof/, example.org/2014/03/25/meow/,
    example.org/2017/10/25/adopt-chairman-meow-adorable/ and
    example.org/category/homeownership/

We named this feature "donation page popup prevention," but in reality it can be used to exclude popups on all sorts of pages.

If you'd like the ability to programmatically exclude popups on arbitrary pages, let us know on this feature proposal on GitHub.

Disabling popups from Mailchimp visitors

In the WordPress Dashboard, under the “Popup Maker” menu item, on the “News Match Popup Basics” page, there is a checkbox that enables MailChimp suppression. There is also a text box to set the utm_source parameter. MailChimp automatically appends this URL parameter to outbound links in your emails if you have click tracking set up.

From one of the emails you have sent, find a link that contains a utm_source= parameter and copy the following argument text, up until any & character, into the text box. For example, a Nerd Alert newsletter sent by INN Labs contained a link that looked like this: https://example.org/?utm_source=Nerd+Alert&utm_campaign=4d4ecd9f68-EMAIL_CAMPAIGN_2017_10_06&utm_medium=email&utm_term=0_1476113985-4d4ecd9f68-421742753. From that URL, you would copy Nerd+Alert into the text box.

A screenshot of the WordPress Admin settings page for News Match Popup Basics, focused on the popup prevention for MailChimp visitors. The setting for utm_source is set to "Nerd+Alert"
An example configuration of the utm_source setting.

Once you have provided a utm_source parameter, checked the checkbox, and saved the settings, any popup that contains an HTML element with an id attribute equal to mc_embed_signup, or a CSS selector equal to #mc_embed_signup, will be suppressed. Suppression works client-side using JavaScript that runs in the visitor’s browser.

If you have multiple MailChimp signup forms on your site, suppression based on the HTML ID of the form will not work for you. You should add a class to all MailChimp forms in popups, and use that as the selector. For more details about this process, see the FAQ entry "Why does MailChimp popup suppression use #mc_embed_signup" at the plugin's WordPress.org entry.

If you'd like better tracking of MailChimp form sign-ups, we recommend that you follow MailChimp's guide on editing forms for better analytics to track popup conversions.

Need help?

If you have questions, join us in our webinar today (Wednesday, October 25) at 1 p.m. Eastern, or contact us at support@inn.org.

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.

Office Hours June 30: INN WordPress Plugins

We'd like to hear from users of our WordPress plugins this week during our open office hours. Join us from 2 to 3 p.m. Eastern in our weekly video chat and in the notes to talk about what you want to see from our plugins.

We maintain:

We'd love to hear what feedback you have on the plugins and ideas you have for their future development.


Join us from PC, Mac, Linux, iOS or Android at zoom.us/j/298377456

Or by telephone: +1 408 638 0968 (US Toll) or +1 646 558 8656 (US Toll)
Meeting ID: 298 377 456
International numbers are available.

Notes for this week's office hours will be in this etherpad.

Our ongoing office hours schedule is in this Google Sheet.

More about our office hours: nerds.inn.org/category/office-hours/

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.

New WordPress Plugin: Pym Shortcode

We're pleased to announce the release of yet another new WordPress plugin: Pym Shortcode.

If you often find yourself embedding iframes in your WordPress posts, you've probably encountered the hassle involved in making an iframe responsive to the width of its containing element.

To address this problem, NPR Visuals Team released Pym.js, a JavaScript library that goes on the embedding page and the embedded page. The parent page tells the child page what the width of the iframe is, and the child page tells the parent how tall the iframe should be. The iframe, resized, now fits its content and the page. The embed code required is pretty simple:

<div id="example"></div>
<script type="text/javascript" src="pym.js"></script>
<script>
 var pymParent = new pym.Parent('example', 'child.html', {});
</script>

But WordPress' default configuration strips <script> tags from posts, meaning that you can't normally use Pym in WordPress sites.

Enter the pym shortcode. This simple plugin is designed to allow users to place Pym embeds without having to use <script> tags.

Here's an example of how the shortcode would be used:

pym src="http://blog.apps.npr.org/pym.js/examples/table/child.html"

In the goal of making it as useful as possible, we've given the shortcode a couple of other attributes, pymsrc and pymoptions, which are explained in the plugin's docs on GitHub.

If you feel so inclined, you can contribute to the plugin by forking the code on GitHub.

May this help all your interactives to be responsive!

resizing
Tiago Franco's classic "resizing the browser" gif.