Digital Services WordPress API Plugin Features

Jan 30, 2013

Digital Services has released a plugin for use with the WordPress content management system.  Released in November of 2012, this plugin will allow stations to interact with the NPR API through easy to configure plugin features that work with the latest versions of the WordPress CMS.  

This plugin is hosted on GitHub https://github.com/npr/WP-DS-NPR-API and available to any user of the NPR API .  To use the plugin an organization should already be set up with NPR API access.

The WordPress plugin is being developed as an Open Source plugin.  If you would like to suggest features or bug fixes, or better yet if you would like to contribute new features or bug fixes please contact Digital Services through our support page at http://info.ds.npr.org//support.html.

Below is a list of features from the release notes for the plugin :

From V1.0

  • On the NPR API settings page (wp-admin/options-general.php?page=ds_npr_api) there are 4 fields.
  •     API KEY - This is your NPR API Key that you can get from NPR.  If you wish to ingest your stories to the NPR API you'll need to have your keep configured by NPR Digital Services.  Please contact Digital Services with a support request at http://info.ds.npr.org//support.html,
  •     Pull URL - This is the root url for retrieving stories.  For testing purposes, you should configure this to be http://api-s1.npr.org.  NOTE : this url should not contain an ending slash.
  •     Push URL - Much like the pull url, this url is used to pushing stories to the NPR API.  Again, for testing purposes, you can utilize NPR's staging servers available at http://api-s1.npr.org.  If you do not wish to ingest your content, or your NPR API has not been authorized, you should leave this field empty and the WP plugin will not attempt to push you content to the NPR API.
  •     Org ID - This is your organizations ID assigned by NPR.  If you don't know your Org ID, please contact Digital Services at: http://info.ds.npr.org//support.html 
  • You can pull stories one at a time from the NPR API by using the Get NPR Stories page under admin Posts menu (wp-admin/edit.php?page=get-npr-stories).  This allows the admin to enter a story ID from the API, or the URL for the story from npr.org.  There are number of aggregates that you can use, such as ID=1001 is Top News, or the show "All Things Considered" is ID=37.  For help in finding possible query options, please see the Query Generator http://www.npr.org/api/queryGenerator.php and documentation  (http://www.npr.org/api/inputReference.php) at npr.org.

From V 1.1

  • This version will allow admins to configure their Wordpress site to retrieve multiple NPR API query returns to be automatically published to their blog on an hourly cron basis.  From the Admin -> Settings -> NPR API Get Multi page (wp-admin/options-general.php?page=ds_npr_api_get_multi_settings) an admin can add a number of queries they would like to query the API with.  These query entries can contain an API ID for a single story, or an aggregate.  The query can also contain the full query string that can be created from the NPR API Query Generator (http://www.npr.org/api/queryGenerator.php).  You can also enter the URL for a story you found on npr.org.  The entered queries will be executed via the Wordpress cron functionality, hourly.  Any new stories that are available will be automatically published.  You can find a list of aggregates at the npr.org's API documentation page (http://www.npr.org/api/inputReference.php).
  • Stories retrieved from the NPR API will be created as Posts in Word Press.  Each post will have a number of meta fields associated with the post.  These meta fields will all begin with 'npr_' and can be viewed on a post edit screen with Custom Fields option enabled through Screen Options.  A story from the API that has a primary image defined will have that image set as the featured image of the Wordpress Post.  Any bylines for the NPR Story will be stored in the meta field npr_byline.
  • On the All Posts admin screen we've made a couple of modification/additions to help you manage your NPR API content.  
  • There is a new Bulk Action available, 'Update NPR Story'.  When one or many NPR API Stories are selected and the Update NPR Story action is applied, the plugin will re-query the NPR API for those stories, and if the story's content has changed the plugin will update the post in Wordpress.
  • There is also a new column added to this page titled "Update Story".  For any Post retrieved from the NPR API there will be a link to "Update" the story.   Pressing this link will bring the user to the query NPR API page with the story ID pre-filled.  Pressing "Publish" on this screen will re-query the NPR API for the story and update the Post with any changes that may have taken place on the NPR API for that story.
  • Update and Delete of pushed stories.  A story that was written in your Wordpress site and pushed to the NPR API will be automatically be updated in the API when your story is updated in Wordpress.  When your Post is moved to the Trash in Wordpress, your story will be deleted from the NPR API.  If a Trashed Post is resorted, your story will be made available from the NPR API again.

From V 1.2

  • This version of the Wordpress NPR API Plugin will have changes to enhance our error messages when there are connectivity or permissions issues with your NPR API work.  We have also included the ability for admins to map custom Meta fields to certain Post fields that are pushed to the NPR API. We've also added the ability to retrieve transcripts for stories that have transcripts associated with them.  Along with these changes we've added the saving of audio file urls for .m3u files of NPR stories pulled to your site.
  • Better Error messages - We've gone through lots of our possible error scenarios when connecting with the NPR API.  For story pull we've moved our error messages to the UI to better keep the admin informed of possible issues.  For story push, where the WP redirect to the edit form after save prohibits us from writing error messages to the screen, we've created a meta field for the post named NPR_PUSH_STORY_ERROR.  This will be displayed under custom fields if an error occurred while pushing a story to the NPR API. 
  • Transcripts -  Many NPR API stories contain transcripts from the program segment they are referencing.  Transcripts are stored in a separate API at NPR, but now when a story you have pulled from the NPR API has transcripts that transcript data will be appended to the body of your post.
  • Custom Post Types -  Now the NPR API Plug-in can use your custom post types.  We will also create a custom post type for stories pulled from the NPR API.  From the NPR API settings page (wp-admin/options-general.php?page=ds_npr_api) you can now select which post type you would like the plug-in to pull content into.  For your convenience we also created the custom post type name npr_story_post.  You do not have to use it.  You can also select which post type you will push to the NPR API.  If neither of these options are not set, we will use the post, post type.
  • Mapping Push Fields -  You can now map any custom field to Title, Body or Byline for posts being pushed to the NPR API.  From the NPR API Field Mapping page (wp-admin/options-general.php?page=ds_npr_api_push_mapping) you can select which meta fields are used from your selected post type for push, to be sent to the API for Title, Body and Byline.  You can also leave this with the default setting, or not check the "Use Custom Settings" checkbox, and the plug-in will use the default WordPress fields.
  • Audio -  We are now going to be saving a link to .m3u files for stories retrieved with audio.  It seems that not all .mp3 files are always available, but more often than not the .m3u file is available.  If there are more than one .mp3 or .m3u file for one story, they will be included in a coma separated list.  M3U files will be stored in the meta field named npr_audio_m3u.
  • BUG FIX -  We found a bug where if there was a story from the API that had images attached, and the story was updated on the API and you used the "Update" function, we would reload the images from the API creating duplicates.  This is now fixed and we will not download or attach images with the same name as the images that are already attached to a story.

 Version 1.3 is currently in development.  Features will be announced when this version is released.