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.

New WordPress Plugin: Google Analytics Popular Posts

Another day, another plugin. Get excited! We're announcing the release of our Google Analytics Popular Posts plugin.

The plugin (previously called Analytic Bridge) queries Google Analytics for pageview data for your site and uses an algorithm – based on publish date and total number of pageviews – to determine a weighted popularity score for a post.

Using this scoring mechanism, the plugin generates a list of the most popular posts for a given site.

ga-2

The list of popular posts can be displayed on the front end of your site using the included "Google Analytics Popular Posts" widget.

ga-3

We hope to make this the start of a suite of tools to improve the connection between your site and Google Analytics. Stay tuned!

The plugin is available now in the WordPress plugin directory and you can check out the code on Github and create a fork to contribute!

New WordPress Plugin: Term Debt Consolidator

We're pleased to announce the release of a new WordPress plugin: Term Debt Consolidator.

We've all been there. You have an older WordPress site with thousands of tags. Mixed up in there you have misspellings, singular and plural version of the same term, similar terms applied to only a single post and more.

Our new Term Debt Consolidator plugin examines your site's tags and categories and groups them by similarity, allowing you to consolidate groups of similar terms down to a single term of your choosing:

tdc-2

This is useful for sites that have tons of messy tags, some of which are technically unique due to differences in capitalization or minor typos in the term title.

tdc-1

Using Term Debt Consolidator, you can identify and fix these issues quickly.

You can also use the `tdc_enabled_taxonomies` filter to enable the TDC to work with your site's custom taxonomies (it supports the built-in WordPress categories and tags taxonomies by default).

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

New WordPress Plugin: Link Roundups

Many sites we work with collect links from around the web and then either present this feed of links on their sites in a widget or turn them into daily (or weekly) roundup posts and email newsletters.

To improve the workflow for curating and publishing these roundups, we've created a new WordPress plugin called Link Roundups.

The plugin borrows some patterns and a bit of the original code from a plugin called Argo Links, but has been almost completely rewritten with a number of new features added (if you are a current Argo Links user, we've included an update script to help you migrate).

Features

Some of the key features of the plugin include:

bookmarklet-popup

A browser bookmarklet to collect links as you browse, add your own description, tags and then save the link directly to your WordPress site, all without having to leave the site you're on. This bookmarklet will also attempt to automatically pull in the title, source and a featured image for the links so you don't have to populate these fields manually.

Widgets for saved links and link roundups to display the links you've saved or your recently published roundups in any WordPress widget area.

published-roundupA WordPress custom post type called Link Roundups with a way to browse your saved links and compile roundup posts to be published on your site.

Integration with MailChimp to simplify the process of sending the roundup posts to your newsletter subscribers.

Plugin options to control the display of saved links in roundups, manually specify the anchor text to be used and a number of other nice enhancements to give you the flexibility to format link roundups the way you want.

Installation

You can find documentation and installation instructions on GitHub and the plugin is also now available from the WordPress.org plugin directory.

What's Next?

In our next release we plan to add the ability to share links you save directly to Facebook/Twitter at the same time as they are saved to your site, improve documentation and add a number of other features.

You can submit feature requests and see our plans for future releases on the project's GitHub repository. Feedback, bug reports and questions are most welcome!

Thanks!

Finally, we want to thank INN member Fresh Energy who funded some of the development of this plugin as part of our recent redesign of their Midwest Energy News site. Thanks also to Aspen Journalism for offering some helpful feedback.

INN’s WordPress Framework For News Sites Now Fully Supports HTTPS

We're pleased to announce the release of version 0.5.2 of our popular Largo WordPress framework for news sites.

With this update, Largo is now fully-compatible with https out of the box. Also included are some enhancements to managing featured media for your stories, some new footer layout options and a number of minor enhancements and bugfixes.

Full HTTPS Support

For many news sites, user privacy and security are significant concerns. With this release we wanted to ensure that sites using Largo would be able to use https out of the box. We're proud to say that this is now the case. Starting from a base installation of Largo you should not have any issues enabling https for your entire site.

WordPress has a guide explaining how to do that, but the details will vary depending on the hosting company you use.

A couple of caveats:

  • If you are migrating to Largo from a different WordPress theme or even updating Largo from a previous version and enable https, you may find that you have http links hard-coded into the body of your stories or elsewhere in your site settings. To get rid of potential mixed content warnings you would need to perform a search and replace to change these URLs to https. We use and recommend this tool, but please be sure to backup your site before doing anything potentially destructive.
  • If you have done any custom work in a child theme using Largo as your parent theme, you may also need to review the code in your child theme to make sure it also fully supports https.
  • If you install third-party plugins or insert/embed content from other sites or services (ad networks, embedded media, etc.) you will need to ensure that those plugins/sites/services support delivery via https or you may also run into mixed content warnings, missing ads or other issues. This is sometimes a major tripping point for sites switching to https, so just be aware that a significant amount or work and testing may be required depending on the number and type of third-party services you're using on your site.

If you are an INN member using our hosted version of Largo and would like to enable https for your site, let us know and we'll explain how the process works, the cost involved, etc. and help you get switched over.

Enhancements to the "Featured Media" editor

In Largo 0.5 we introduced the ability to use a video, slideshow or other embedded media in the place of a featured image for each story. With Largo 0.5.2, we have added a number of enhancements to this functionality to make it work better in a number of additional contexts, including:

  • The ability to set a thumbnail for embed and video featured media types to be used on the homepage, category pages, widgets or anywhere else a thumbnail/featured image might appear
  • The video featured media editor will attempt to automatically pull a thumbnail from any available oEmbed provider (YouTube, Vimeo, etc.) but still give authors the ability to upload their own thumbnail images if they would prefer
  • For theme developers, we have also added "featured-media" and "featured-media-{type}" classes to story containers for use in customizing the appearance of different types of featured media via CSS (adding overlays, icons, etc. to call out posts containing video, slideshows or other rich media)

New footer layout options

In working on a few recent client projects (Nonprofit Quarterly, Midwest Energy News and the redesign of our own site) we've developed a couple of new layout options for the footer of Largo sites, specifically:

  • A 4-column asymmetrical layout, with three narrow columns and one wide column, well suited for three menu areas and a donation, subscription or newsletter signup banner or widget.
  • A minimal 1-column centered layout, well-suited for sites who want a simpler, more minimal footer limited to simple navigation instead of having more widget areas to populate and manage.
  • For theme developers, an easier way to register and use a custom footer layout.

And of course a number of other bugfixes and enhancements.

We encourage you to download the new version and update your sites at your earliest convenience. If you host your site with us, we're making this update for you today. If you host your site elsewhere, you can download the new version from GitHub.

If you have questions or need assistance please check out the release notes and documentation first and if you're still stuck, open a ticket through the Largo help desk.

What's next?

Over the next couple of months we'll be working fast and furious on polishing a number of existing features gearing up for our next full point release, version 0.6 (currently slated for late October). Look for a new release almost every week in between now and then and if you're interested in following along or contributing to the project, you can check out the upcoming milestones on GitHub.

Nerd Alert Issue 35: So easy a snake person could use it!

nerdalertfinal

"We cannot always build the future for our websites,
but we can build our websites for the future."
- Franklin D. Roosevelt

HOT LINKS

What we're reading this week

  Adam: A lot of good ideas in this post by Olivia Cheng, a designer at the Sunlight Foundation, about how they’re working to make their design process more open.

  Ben: Here’s how a recent WordPress vulnerability was found. Don’t worry! The patch has already been released.

  Dani: Uber’s model to predict where we are actually going. Warning: fun statistics math ahead.

  David: A handsome, open source, DIY Netflix app to run on your server. BYO on the binge viewers.

  Kaeti: Research often means admitting what you don’t know and interrogating your assumptions. Scary stuff. Erika Hall breaks down why it’s so essential and how to make it happen.

  Ryan: Making self-driving cars, it turns out, is hard. Consider the split-second decisions the machine might need to make in an emergency situation and you'll understand why they're not (yet) in widespread use.

  Bert: This is why we can't have nice things.

This week's guest contributor: Retha Hill, Director of the Innovation and Entrepreneurship Lab, Professor of Practice at The Cronkite School.

Look around your non-profit newsroom. Is there anything missing? Say, a brown or black face? If the answer is yes, you are more like mainstream media in one important regard -- diversity, or lack thereof. A new Nieman Reports has eye-opening looks at Race and Reporting and makes the case for more inclusion. But what is a better read is Alex T. Williams’ look behind the numbers into why we have a diversity problem today despite the availability of young journalists of color.

Check it out, then look around your newsroom one more time, then look in the mirror and ask yourself what you might need to change to do better.


Each week we ask someone from outside our team to contribute a link, tool or idea. Are you our next guest star? We think you might be. Send us a note at nerds@inn.org.

SHOUT OUT

Work we admire by our journalism peers

One year in Ferguson

An immersive multimedia project from St. Louis Public Radio.

SOME OTHER STUFF

Gather ye rosebuds

LISTEN: Sick beats.

COOK: Not October yet, so still OK to share pumpkin things. But these are way more than pumpkin things.

WATCH: Squad goals to be this cool and fearless.

GIF: Summer is for getting outdoors! Seize the weekend.

get_outside

Largo 0.5.1 released!

On July 16, we tagged Largo v0.5.1 with another slew of bug fixes and updates.

Amongst the bug fixes and enhancements:

Google Custom Search results are now displayed on the standard WordPress search results page and are compatible with the standard WordPress search results conventions including the /search/search%20term and /?s=search%20term url structures.

We've also added a menu to the WordPress Admin Bar with several useful Largo-related links.

Further, we fixed a nasty bug/oversight which resulted in the optional "donate" button not displaying on smaller screens. The donate link we're referring to shows up in the site's sticky navigation.

On the documentation front, we merged a ton of developer documentation that came about as a result of our participation in the OpenNews Code Convening in Portland The developer docs now include:

  • Revised technical notes
  • Instructions for setting up a development environment (based on the development rig we use at INN)
  • Details for working with Largo to create Child Themes
  • A first pass at Largo API documentation

A special note on a breaking change -- if you redefined largo_load_more_posts in your child theme, you will need to update it with code from this release, as the old logic will fail to load the correct posts.

That said, the "Load more posts" button can now be used multiple times per page and no longer relies on the global $wp_query. Further, you can customize the text of the button by using the largo_next_posts_link filter.

Read the complete release notes and download the version here.

Announcing Largo Version 0.5

Announcing the version 0.5 release of Largo, everyone's favorite responsive WordPress theme for news sites!

Where v0.4 was dedicated to a major overhaul of user-facing features and touching nearly all corners of the project, v0.5 brings a handful of new features for developers as well as some much-needed project cleanup, additional documentation and a few performance enhancements.

For this release, we audited the use of third-party PHP and javascript libraries throughout the project. Wherever possible, we updated third-party libraries to their most recent release or found suitable, well-maintained replacements.

We've also started an initiative — which will carry on through subsequent releases — to evaluate Largo's performance. No one wants a slow site, so we're doing what we can to cut down on wasteful resource usage. In this release, we've started using minified CSS and Javascript and refactored code to make less expensive database queries.

The shortlist of features added in this release:

  • LESS source maps in all unminified CSS, to help in debugging styles while developing for Largo.
  • Updated slideshows to use slick instead of slidejs since it is no longer maintained.
  • Polished the styles for the Largo recent posts widget
  • Added a LARGO_DEBUG constant, which is currently used to determine whether or not to include unminified, uncompressed Javascript and CSS. When developing your Largo site, use:
    define('LARGO_DEBUG', true);

    When pushing your site live, use:

    define('LARGO_DEBUG', false);
  • Updated all "Investigative News Network" references to "Institute for Nonprofit News" after INN's recent rebranding
  • Moved the "member of INN" badge to the footer and improved the styling of the social media icons in the footer
  • Use the single column layout for single post pages by default

For more information and a complete list of new features and bugfixes in this release, see the release notes on Github.

How to debug email-related theme and plugin functionality in WordPress

Let's say you're having trouble with a WordPress theme or plugin that uses wp_mail. How can you inspect the email that wp_mail composes or verify that it is actually sending (or at least attempting to send)?

Well, one simple way is to tell WordPress to use Python's smtpd DebuggingServer to "send" email.

The DebuggingServer doesn't actually send email, so don't go checking your inbox. It's only meant to show you the email that would be sent, headers included, if it were an actual SMTP server.

Note that this guide assumes you're debugging wp_mail issues during local development.

Let's get started.

Set up the smtpd DebuggingServer

If you have Python installed (comes with Mac OS X and most distributions of Linux by default), this is the one-liner you can use to get the debugging mail server running. From the command line, run:

$ python -m smtpd -n -c DebuggingServer localhost:1025

So that you don't have to remember that command, you can add an alias to your shell profile (e.g., ~/.profile), making it super easy to run the debugging mail server at a moment's notice.

To do this, open your shell profile in your favorite text editor and add the following line:

alias mailserve='python -m smtpd -n -c DebuggingServer localhost:1025'

Save your shell profile and source it in your shell to make sure the new mailserve alias is available:

$ source ~/.profile

Note: ~/.profile is probably the most common shell profile location. If you don't have this file, you can create one by running:

$ touch ~/.profile

Keep in mind that you might already have a shell profile for your specific shell. For example, ~/.basrhc for bash or ~/.zshrc for zsh. If you have a ~/.bashrc or ~/.zshrc, you can try adding the mailserve alias to one of them instead.

Once you have the mailserve alias defined and your profile sourced, running the server is as simple as:

$ mailserve

Note: there won't be any output from running this command initially. The debugging server runs, waiting for an application to connect and attempt to send a message.

Tell WordPress to send mail via the DebuggingServer

Now, in your WordPress theme or plugin, you can add some debugging code that will tell WordPress to send email via the debugging server you have running.

To accomplish this, add the following code to your theme's functions.php or to your plugin's main file:

function phpmailer_debug_settings($phpmailer) {
    $phpmailer->isSMTP();
    $phpmailer->Host = 'localhost';
    $phpmailer->Port = 1025;
}
add_action('phpmailer_init', 'phpmailer_debug_settings');

This code changes the configuration of the $phpmailer object used by wp_mail, telling it to use the SMTP server on localhost, port number 1025. If you look back at the Python command used to fire up the debugging mail server, you'll see the $phpmailer settings correspond to the arguments passed in that command:

$ python -m smtpd -n -c DebuggingServer localhost:1025

Once you have the debugging mail server running and the code above included in your theme/plugin, you can try sending mail with WordPress and see the entire message contents, SMTP headers, etc in your shell. Here's some example output:

vagrant@precise64:~$ mailserve
---------- MESSAGE FOLLOWS ----------
Date: Thu, 12 Mar 2015 16:21:54 +0000
Return-Path: <ryan@inn.org>
To: "\"Investigative News Network\"" <webmaster@investigativenewsnetwork.org>
From: Ryan <ryan@inn.org>
Cc: info@investigativenewsnetwork.org
Subject: [INN Website Contact] This is a test email subject line
Message-ID: <e538a998dbba308e2e6437a0b3ca4a50@vagrant.dev>
X-Priority: 3
X-Mailer: PHPMailer 5.2.7 (https://github.com/PHPMailer/PHPMailer/)
X-Originating-IP: 192.168.33.1
X-Mailer: WP Clean-Contact (vagrant.dev)
MIME-Version: 1.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
X-Peer: 127.0.0.1

This is the test email body.

------------ END MESSAGE ------------

Why do I need this?

This can be helpful if you're trying to track down missing parts of an email (e.g., hey, where'd my "from" address go?) or need to verify the contents or formatting of an email that your theme/plugin sends to users.

Keep in mind that, although this post describes how to use the Python smtpd DebuggingServer with WordPress, you can also use this guide with other applications as long as you can configure said applications to connect to the DebuggingServer.