From 048b5f5b845093292a28669905d3ea8d640edd6f Mon Sep 17 00:00:00 2001 From: Ben Keith Date: Tue, 25 Sep 2018 19:01:28 -0400 Subject: [PATCH 1/6] Bump version number, update inn_nerds->innlabs in contributors --- README.md | 20 ++++++++++---------- ds-npr-api.php | 2 +- readme.txt | 6 +++--- 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index d38d2b5..a64a719 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,10 @@ A collection of tools for publishing from and to NPR's Story API. [Find this plugin on the Wordpress.org Plugin Repository](https://wordpress.org/plugins/npr-story-api/). -Contributors: nprds, inn_nerds +Contributors: nprds, innlabs Requires at least: 3.8.14 Tested up to: 4.9 -Stable tag: 1.7.1 +Stable tag: 1.8 License: GPLv2 License URI: https://www.gnu.org/licenses/gpl-2.0.html @@ -68,7 +68,7 @@ NPR Stories having got gotten == Changelog == -= [unreleased](https://github.com/npr/nprapi-wordpress/compare/1.7.1...HEAD) = += V1.8 = * Fixes invalid GMT offset error when creating new DateTimeZone object in post metabox. [PR #53](https://github.com/npr/nprapi-wordpress/pull/53) for [issue #52](https://github.com/npr/nprapi-wordpress/issues/52). * When interacting with a site using the plugin in an unconfigured state, users will be prompted to set the NPR API Push URL. [PR #56](https://github.com/npr/nprapi-wordpress/pull/56) for [issue #51](https://github.com/npr/nprapi-wordpress/issues/51). @@ -171,13 +171,13 @@ This version will allow admins to configure their WordPress site to retrieve mul * Stories retrieved from the NPR API will be created as Posts in WordPress. 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`. The list of npr_ meta fields is: npr_api_link - npr_byline - npr_html_link - npr_last_modified_date - npr_pub_date - npr_retrieved_story - npr_story_content - npr_story_id + npr_byline + npr_html_link + npr_last_modified_date + npr_pub_date + npr_retrieved_story + npr_story_content + npr_story_id * 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, this plugin will re-query the NPR API for those stories, and if the story's content has changed it will update the post in WordPress. diff --git a/ds-npr-api.php b/ds-npr-api.php index 7301536..a2a4282 100644 --- a/ds-npr-api.php +++ b/ds-npr-api.php @@ -2,7 +2,7 @@ /** * Plugin Name: NPR Story API * Description: A collection of tools for reusing content from NPR.org supplied by Digital Services. - * Version: 1.7.1 + * Version: 1.8 * Author: NPR Digital Services * License: GPLv2 */ diff --git a/readme.txt b/readme.txt index 46eee47..88bea88 100644 --- a/readme.txt +++ b/readme.txt @@ -1,10 +1,10 @@ === NPR Story API === -Contributors: nprds, inn_nerds +Contributors: nprds, innlabs Donate link: https://www.npr.org/series/750002/support-public-radio Tags: npr, news, public radio, api Requires at least: 3.8.14 Tested up to: 4.9 -Stable tag: 1.7.1 +Stable tag: 1.8 License: GPLv2 License URI: http://www.gnu.org/licenses/gpl-2.0.html Text Domain: nprapi @@ -73,7 +73,7 @@ NPR Stories having got gotten == Changelog == -= [unreleased](https://github.com/npr/nprapi-wordpress/compare/1.7.1...HEAD) = += V1.8 = * Fixes invalid GMT offset error when creating new DateTimeZone object in post metabox. [PR #53](https://github.com/npr/nprapi-wordpress/pull/53) for [issue #52](https://github.com/npr/nprapi-wordpress/issues/52). * When interacting with a site using the plugin in an unconfigured state, users will be prompted to set the NPR API Push URL. [PR #56](https://github.com/npr/nprapi-wordpress/pull/56) for [issue #51](https://github.com/npr/nprapi-wordpress/issues/51). From 46b7f01c07836ddc1cd695f7d54d64fe0ef40ec3 Mon Sep 17 00:00:00 2001 From: Ben Keith Date: Tue, 25 Sep 2018 19:19:37 -0400 Subject: [PATCH 2/6] Update release.sh to match INN's copy --- release.sh | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/release.sh b/release.sh index a07fb87..d5e1d29 100755 --- a/release.sh +++ b/release.sh @@ -1,4 +1,9 @@ -#!/usr/bin/env bash +#!/usr/bin/env bas +# +# This file is a WordPress.org plugin release script. +# For more about how it works, see the documentation at +# https://github.com/INN/docs/blob/master/projects/wordpress-plugins/release.sh.md +# RELEASE_DIR=release; SVN_PATH=$RELEASE_DIR/svn; SVN_REPO="https://plugins.svn.wordpress.org/npr-story-api/"; @@ -16,6 +21,7 @@ Gruntfile.js release/\* tests/\* node_modules/\* +./\*\*/.\* ); function ensure_release_dir() { @@ -278,6 +284,9 @@ function help_text() { echo ""; echo "--help: Display this help screen and exit."; echo ""; + echo "For more information about this script, see: + https://github.com/INN/docs/blob/master/projects/wordpress-plugins/release.sh.md"; + echo ""; exit 0; } From 13fb608a89f5290d82488e3b200df0fee7584e18 Mon Sep 17 00:00:00 2001 From: Ben Keith Date: Thu, 27 Sep 2018 12:50:03 -0400 Subject: [PATCH 3/6] Update README.md with changelog from readme.txt --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index a64a719..d020390 100644 --- a/README.md +++ b/README.md @@ -68,10 +68,15 @@ NPR Stories having got gotten == Changelog == + + = V1.8 = +* Fixes issue preventing pushing to the API, introduced in V1.7. [PR #60](https://github.com/npr/nprapi-wordpress/pull/60) for [issue #57](https://github.com/npr/nprapi-wordpress/issues/57). +* Fixes issue where images were not properly sideloaded. [PR #60](https://github.com/npr/nprapi-wordpress/pull/60) for [issue #59](https://github.com/npr/nprapi-wordpress/issues/59). * Fixes invalid GMT offset error when creating new DateTimeZone object in post metabox. [PR #53](https://github.com/npr/nprapi-wordpress/pull/53) for [issue #52](https://github.com/npr/nprapi-wordpress/issues/52). * When interacting with a site using the plugin in an unconfigured state, users will be prompted to set the NPR API Push URL. [PR #56](https://github.com/npr/nprapi-wordpress/pull/56) for [issue #51](https://github.com/npr/nprapi-wordpress/issues/51). +* Miscellaneous code quality improvements. = V1.7 = From 2d4573174a2932f492f757023948fbfeedaac757 Mon Sep 17 00:00:00 2001 From: Ben Keith Date: Thu, 27 Sep 2018 12:52:52 -0400 Subject: [PATCH 4/6] Fix headers in README.md --- README.md | 41 +++++++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index d020390..b8df52d 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Stable tag: 1.8 License: GPLv2 License URI: https://www.gnu.org/licenses/gpl-2.0.html -== Description == +## Description The NPR Story API Plugin provides push and pull functionality with the NPR API along with a user-friendly administrative interface. @@ -19,31 +19,31 @@ Access to the NPR API requires an API Key to NPR's legacy APIs. If you are an NP The WordPress plugin is being developed as an Open Source plugin by NPR. 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 [NPR station relations](https://nprsupport.desk.com/customer/login?return_to=%2Fcustomer%2Fportal%2Femails%2Fnew). -== Installation == +## Installation 1. Upload the plugin files to the `/wp-content/plugins/plugin-name` directory, or install the plugin through the WordPress plugins screen directly. 2. Activate the plugin through the 'Plugins' screen in WordPress 3. Use the Settings->NPR API screen to configure the plugin. Begin by entering your API Key, then add your Push URL and Org ID. -== Frequently Asked Questions == +## Frequently Asked Questions -= Can anyone get an NPR API Key? = +### Can anyone get an NPR API Key? We are no longer provisioning public API key for our legacy APIs. If you are an NPR member station or are working with an NPR member station and do not know your key, please [ask NPR station relations for help](https://nprsupport.desk.com/customer/login?return_to=%2Fcustomer%2Fportal%2Femails%2Fnew). -= Can anyone push content into the NPR API using this plugin? = +### Can anyone push content into the NPR API using this plugin? Push requires an Organization ID in the NPR API, which is typically given out to only NPR stations and approved content providers. If that's you, you probably already have an Organization ID. -= Where can I find NPR's documentation on the NPR API? = +### Where can I find NPR's documentation on the NPR API? There is some documentation in the NPR API site: [www.npr.org/api/index.php](https://www.npr.org/api/index.php). -= Is there an easy way to directly query the NPR API? = +### Is there an easy way to directly query the NPR API? You bet, just visit the NPR Query Generator: [www.npr.org/api/queryGenerator.php](https://www.npr.org/api/queryGenerator.php) -== Screenshots == +## Screenshots NPR API Plugin Settings screen @@ -66,11 +66,11 @@ NPR Stories having got gotten ![NPR Stories having got gotten](docs/assets/img/npr-stories.png) -== Changelog == +## Changelog -= V1.8 = +### V1.8 * Fixes issue preventing pushing to the API, introduced in V1.7. [PR #60](https://github.com/npr/nprapi-wordpress/pull/60) for [issue #57](https://github.com/npr/nprapi-wordpress/issues/57). * Fixes issue where images were not properly sideloaded. [PR #60](https://github.com/npr/nprapi-wordpress/pull/60) for [issue #59](https://github.com/npr/nprapi-wordpress/issues/59). @@ -78,7 +78,7 @@ NPR Stories having got gotten * When interacting with a site using the plugin in an unconfigured state, users will be prompted to set the NPR API Push URL. [PR #56](https://github.com/npr/nprapi-wordpress/pull/56) for [issue #51](https://github.com/npr/nprapi-wordpress/issues/51). * Miscellaneous code quality improvements. -= V1.7 = +### V1.7 * The Story API box that appears in the post editor has been refreshed: * Instead of requiring a separate action to push the story to the Story API, the content will be pushed whenever the content is saved in WordPress, if the "Send to NPR API" box is checked. @@ -89,7 +89,7 @@ NPR Stories having got gotten * Several broken links in the documentation have been repaired. ([#44](https://github.com/npr/nprapi-wordpress/pull/44)) * Automated tests are now run against an expanded list of WordPress and PHP versions, as described [in pull request #46](https://github.com/npr/nprapi-wordpress/pull/46). -= V1.6 = +### V1.6 * Added meta box to post edit page to explicitly push a story to NPR One * Added [documentation](https://github.com/nprds/nprapi-wordpress/tree/master/docs) @@ -107,14 +107,14 @@ NPR Stories having got gotten * `DS_NPR_API` class now uses new-style `__construct()` constructor. * Removed `/wp-admin/includes/admin.php`, `/wp-load.php`, `/wp-includes/class-wp-error.php` from the cron job function, see [4b3d65a](https://github.com/nprds/nprapi-wordpress/pull/19/commits/4b3d65a19122b0da5215997939db94c7accf3e5e) and [cf2dfa3](https://github.com/nprds/nprapi-wordpress/pull/19/commits/cf2dfa39c1f118d0ca0c836d7967e09baec63bd6) - the cron job works without them. -= V1.5.2 = +### V1.5.2 * Adding support for enclosures created as metadata by the PowerPress plugin. * Added NPR One checkbox that makes pushed stories available to the NPR One app (unchecked by default). * Users were getting a whitescreen when attempting to push posts. The default byline element -- when used with no mapping or co-authors plugin -- was being sent without a tag name, causing a fatal error.) * General clean up; small doc tweaks; bug fixes. -= V1.5.1 = +### V1.5.1 * Multiple Bylines for pulled stories - When an API story has multiple bylines, we will now populate a meta field `npr_multi_byline` with a pipe (|) deliminated list of names. If the author also has a link for thier byline then there'll be a tilde (~) separating the author's name and the link. - An example of data for multiple bylines: @@ -125,7 +125,7 @@ NPR Stories having got gotten * Do not re-pull stories that are already in draft status - The get multi process would repleatedly re-pull stories into draft mode if there is already a draft copy. This fix will check for `status=any` when checking to see if a story already exists in the WordPress database. -= V1.5 = +### V1.5 * Reversed the order of images and audio that are being pushed to the NPR API. We're now sending them in the order the file was created. * Mapping of media credit and agency - If you have a field that you are storing image credit and agency, you can now send these to the NPR API. In making this change we needed to expose meta fields that begin with an underscore. So you may see more meta fields visable on the mapping page. @@ -143,14 +143,14 @@ NPR Stories having got gotten * When pushing a story with Audio, the audio description will be pushed as well, provided there is one. -= V1.4 = +### V1.4 * Filters for Shortcodes - We've now implemented a hook to a filter that will be used to alter any short codes that a plugin may own in a post before pushing that post to the NPR API. The filter (`npr_ds_shortcode_filter`) will fire before we remove shortcodes when we're pushing the post. Any plugin that has shortcodes should alter those shortcodes via this filter to something that's more HTML-friendly, so that other clients can access that information. As an example of what needs to be done in a plugin to take advantage of this new filter please see the branch for the following plugin: What we've done here is write a function `my_documentCloud_filter` that is linked to the filter `npr_ds_shortcode_filter` (all near the bottom of the PHP file). This function will turn any shortcode created by this plugin into an HTML `` tag to link to what was an embedded document. As with any other filter in WordPress, nothing will happen if you do not have any plugins installed that have implemented the filter. It will be up to any other plugin's maintainer to implement the filter correctly if they wish to take advantage of this functionality. * Bulk Push - From the post list page for you NPR Push post type you can now select multiple posts and using the bulk operation dropdown on that page, push the selected posts to the NPR API. This should helpful for posts that have been living on a site before the NPR API plugin was installed. Note that this will only push a maximum 20 posts at one time. * Publish or Draft for Get Multi - It's now possible for an admin to select Draft or Publish for the posts that come from a query on the get multi page. This way, the return from each query can be reviewed before it's published to a site. * Run Get Multi on Demand - An admin can now select a checkbox if they would like the get multi queries to run when the page is saved. This will allow admins to immediately check queries instead of having to wait for the cron to run. -= V1.3 = +### V1.3 * Permissions - If you have created any NPR API Permissions Groups you can select which (if any) group you would like to use as your default group when pushing content to the NPR API. Learn more about NPR API Permissions Groups here: * Multi-Site - Cron set up and other activation tasks will now happen on every site in a multi-site configuration. @@ -158,12 +158,12 @@ NPR Stories having got gotten * Content and short codes - Instead of blindly removing all shortcodes from a story's content, we are now trying to let any plugins replace the shortcodes with HTML, and then if there are any leftover shortcodes (we delete those?). * Byline URL - We are now saving any links to the author of a story's bio page in the meta field `npr_byline_link`. This should allow you to supply a link for any author who has a biography registered with the NPR API. -= V1.2 = +### V1.2 * Enhance 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. And finally, we've add the ability to retrieve transcripts for stories that have transcripts associated with them. Along with these changes we've added the the ability to save urls for the .m3u files attached to NPR stories. -= V1.1 = +### V1.1 This version will allow admins to configure their WordPress site to retrieve multiple NPR API stories that will be automatically published (via cron) to their site. @@ -189,7 +189,8 @@ This version will allow admins to configure their WordPress site to retrieve mul - 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 to the NPR API again. -= V1.0 = +### V1.0 + As not a lot of users have installed the V1.0 of the NPR API Plugin, there are a couple of things to keep in mind. * On the NPR API settings page (wp-admin/options-general.php?page=ds_npr_api) there are 4 fields. From a1d3b1b64e1556c81f74edfc38f1de12c4d6dedc Mon Sep 17 00:00:00 2001 From: Ben Keith Date: Thu, 27 Sep 2018 12:53:21 -0400 Subject: [PATCH 5/6] Two more headers --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b8df52d..154dd6a 100644 --- a/README.md +++ b/README.md @@ -200,8 +200,8 @@ As not a lot of users have installed the V1.0 of the NPR API Plugin, there are a - Org ID - This is your organization's ID assigned by NPR. If you don't know your Org ID, please contact Digital Services at: * 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 can be story ID from the API, or the URL for the story from npr.org. For help in finding possible query options, please use the Query Generator at Documentation is at: -== Upgrade Notice == +## Upgrade Notice -= 1.5.2 = +### 1.5.2 This version adds export functionality for the NPR One mobile app, in addition to assorted bug fixes. From 05b41cb165cae30cb989c62d91fdd4ca72869c6e Mon Sep 17 00:00:00 2001 From: Ben Keith Date: Thu, 27 Sep 2018 13:01:27 -0400 Subject: [PATCH 6/6] Update 'NPR API' to 'NPR Story API' in most places, for clarity. --- README.md | 78 ++++++++++++++++---------------- docs/field-mapping.md | 10 ++-- docs/installation.md | 2 +- docs/npr-one.md | 10 ++-- docs/pulling-multiple-stories.md | 20 ++++---- docs/pulling-single-story.md | 8 ++-- docs/pushing.md | 20 ++++---- docs/readme.md | 14 +++--- docs/settings.md | 12 ++--- readme.txt | 32 ++++++------- 10 files changed, 103 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index 154dd6a..1926821 100644 --- a/README.md +++ b/README.md @@ -11,11 +11,11 @@ License URI: https://www.gnu.org/licenses/gpl-2.0.html ## Description -The NPR Story API Plugin provides push and pull functionality with the NPR API along with a user-friendly administrative interface. +The NPR Story API Plugin provides push and pull functionality with the NPR Story API along with a user-friendly administrative interface. NPR's API is a content API, which essentially provides a structured way for other computer applications to get NPR stories in a predictable, flexible and powerful way. The content that is available includes audio from most NPR programs dating back to 1995 as well as text, images and other web-only content from NPR and NPR member stations. This archive consists of over 250,000 stories that are grouped into more than 5,000 different aggregations. -Access to the NPR API requires an API Key to NPR's legacy APIs. If you are an NPR member station or are working with an NPR member station and do not know your key, please [ask NPR station relations for help](https://nprsupport.desk.com/customer/login?return_to=%2Fcustomer%2Fportal%2Femails%2Fnew). +Access to the NPR Story API requires an API Key to NPR's legacy APIs. If you are an NPR member station or are working with an NPR member station and do not know your key, please [ask NPR station relations for help](https://nprsupport.desk.com/customer/login?return_to=%2Fcustomer%2Fportal%2Femails%2Fnew). The WordPress plugin is being developed as an Open Source plugin by NPR. 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 [NPR station relations](https://nprsupport.desk.com/customer/login?return_to=%2Fcustomer%2Fportal%2Femails%2Fnew). @@ -23,35 +23,35 @@ The WordPress plugin is being developed as an Open Source plugin by NPR. If you 1. Upload the plugin files to the `/wp-content/plugins/plugin-name` directory, or install the plugin through the WordPress plugins screen directly. 2. Activate the plugin through the 'Plugins' screen in WordPress -3. Use the Settings->NPR API screen to configure the plugin. Begin by entering your API Key, then add your Push URL and Org ID. +3. Use the **Settings -> NPR API** screen to configure the plugin. Begin by entering your API Key, then add your Push URL and Org ID. ## Frequently Asked Questions -### Can anyone get an NPR API Key? +### Can anyone get an NPR Story API Key? We are no longer provisioning public API key for our legacy APIs. If you are an NPR member station or are working with an NPR member station and do not know your key, please [ask NPR station relations for help](https://nprsupport.desk.com/customer/login?return_to=%2Fcustomer%2Fportal%2Femails%2Fnew). -### Can anyone push content into the NPR API using this plugin? +### Can anyone push content into the NPR Story API using this plugin? -Push requires an Organization ID in the NPR API, which is typically given out to only NPR stations and approved content providers. If that's you, you probably already have an Organization ID. +Push requires an Organization ID in the NPR Story API, which is typically given out to only NPR stations and approved content providers. If that's you, you probably already have an Organization ID. -### Where can I find NPR's documentation on the NPR API? +### Where can I find NPR's documentation on the NPR Story API? -There is some documentation in the NPR API site: [www.npr.org/api/index.php](https://www.npr.org/api/index.php). +There is some documentation in the NPR Story API site: [www.npr.org/api/index.php](https://www.npr.org/api/index.php). -### Is there an easy way to directly query the NPR API? +### Is there an easy way to directly query the NPR Story API? You bet, just visit the NPR Query Generator: [www.npr.org/api/queryGenerator.php](https://www.npr.org/api/queryGenerator.php) ## Screenshots -NPR API Plugin Settings screen +NPR Story API Plugin Settings screen -![NPR API Plugin Settings screen](docs/assets/img/npr-api-wp-plugin-settings.png) +![NPR Story API Plugin Settings screen](docs/assets/img/npr-api-wp-plugin-settings.png) -NPR API multiple get settings +NPR Story API multiple get settings -![NPR API multiple get settings](docs/assets/img/npr-api-multiple-get-settings.png) +![NPR Story API multiple get settings](docs/assets/img/npr-api-multiple-get-settings.png) Get NPR Stories link in the dashboard @@ -75,13 +75,13 @@ NPR Stories having got gotten * Fixes issue preventing pushing to the API, introduced in V1.7. [PR #60](https://github.com/npr/nprapi-wordpress/pull/60) for [issue #57](https://github.com/npr/nprapi-wordpress/issues/57). * Fixes issue where images were not properly sideloaded. [PR #60](https://github.com/npr/nprapi-wordpress/pull/60) for [issue #59](https://github.com/npr/nprapi-wordpress/issues/59). * Fixes invalid GMT offset error when creating new DateTimeZone object in post metabox. [PR #53](https://github.com/npr/nprapi-wordpress/pull/53) for [issue #52](https://github.com/npr/nprapi-wordpress/issues/52). -* When interacting with a site using the plugin in an unconfigured state, users will be prompted to set the NPR API Push URL. [PR #56](https://github.com/npr/nprapi-wordpress/pull/56) for [issue #51](https://github.com/npr/nprapi-wordpress/issues/51). +* When interacting with a site using the plugin in an unconfigured state, users will be prompted to set the NPR Story API Push URL. [PR #56](https://github.com/npr/nprapi-wordpress/pull/56) for [issue #51](https://github.com/npr/nprapi-wordpress/issues/51). * Miscellaneous code quality improvements. ### V1.7 * The Story API box that appears in the post editor has been refreshed: - * Instead of requiring a separate action to push the story to the Story API, the content will be pushed whenever the content is saved in WordPress, if the "Send to NPR API" box is checked. + * Instead of requiring a separate action to push the story to the Story API, the content will be pushed whenever the content is saved in WordPress, if the "Send to NPR Story API" box is checked. * The box now includes options to include the story for listening in NPR One, and to set the story as "featured" in NPR One. This feature includes the option to set an expiration date, after which time the story will not appear in NPR One. * HTTPS is now supported for accessing the Story API. ([#44](https://github.com/npr/nprapi-wordpress/pull/44)) * The push and pull post types are now respected, thanks to [#41](https://github.com/npr/nprapi-wordpress/pull/41) from [@chrisenterey](https://github.com/chrisentery). @@ -97,7 +97,7 @@ NPR Stories having got gotten * If it succeeds, a success message is displayed * Rename the plugin to "NPR Story API" * The plugin now requires certain WordPress capabilities before performing API actions: - - deleting posts in the API now requires the `delete_others_posts` capability for the user trying to delete the post. In effect, this limits deletion of stories from the NPR API to admins and editors. + - deleting posts in the API now requires the `delete_others_posts` capability for the user trying to delete the post. In effect, this limits deletion of stories from the NPR Story API to admins and editors. - pushing stories to the API requires the `publish_posts` capability, which means that contributors and guests can't push to NPR. - pulling posts from the API requires the `edit_posts` capability, meaning that contributors and guests can't pull from NPR. We may want to revisit this in the future, or make the permissions filterable if sites using the plugin want to lock permissions down or open them up. * A number of settings in the admin now use the number input type instead of text fields @@ -127,14 +127,14 @@ NPR Stories having got gotten ### V1.5 -* Reversed the order of images and audio that are being pushed to the NPR API. We're now sending them in the order the file was created. -* Mapping of media credit and agency - If you have a field that you are storing image credit and agency, you can now send these to the NPR API. In making this change we needed to expose meta fields that begin with an underscore. So you may see more meta fields visable on the mapping page. -* Multiple bylines are now being pushed to the NPR API if you use the plugin co-author-plus () We insert a byline row for each of the co-authors of a post when we push. You can still use a custom byline field if you want to use that along with the co-authors plugin. -* Retrieved story dates - Now when you retrieve a story from the NPR API the published date for WordPress will be the date from the field in the NPR API. This will better allow stories to fall into their natural order when publishing from the Get Multi page. It's always possible to edit the date by hand when pulling single stories from the NPR API. Do remember though that you are contractually obligated to show the original date when rendering a story from the NPR API. +* Reversed the order of images and audio that are being pushed to the NPR Story API. We're now sending them in the order the file was created. +* Mapping of media credit and agency - If you have a field that you are storing image credit and agency, you can now send these to the NPR Story API. In making this change we needed to expose meta fields that begin with an underscore. So you may see more meta fields visable on the mapping page. +* Multiple bylines are now being pushed to the NPR Story API if you use the plugin co-author-plus () We insert a byline row for each of the co-authors of a post when we push. You can still use a custom byline field if you want to use that along with the co-authors plugin. +* Retrieved story dates - Now when you retrieve a story from the NPR Story API the published date for WordPress will be the date from the field in the NPR Story API. This will better allow stories to fall into their natural order when publishing from the Get Multi page. It's always possible to edit the date by hand when pulling single stories from the NPR Story API. Do remember though that you are contractually obligated to show the original date when rendering a story from the NPR Story API. * Retrieved story order - When you retrieve stories from the API, if you do not include a `sort` parameter in your query, we will insure that the order of the stories is in reverse cron for any stories that have the same storyDate in the API. Often some aggregate groups in the API will publish stories with the same storyDate. Shows like Morning Edition do this often, and prior to this fix stories would appear to be published in reverse order from what the API shows. Now if you do not include `sort` in your query, the stories with the same time will be published in the same order as the API shows them. * Configurable Cron interval - When you use the Get Multi page, which fires off of wp-cron, you can now set the interval for the wp-cron to fire. This is on the Get Multi configuration page, and allows you to enter a number of minutes you want as your wp-cron interval. If you enter any thing that is not a number, or a number less than 1, we will resolve that to 60 minutes...because, well, that's a resonable interval, and the wp-cron doesn't understand 'every now and then' as an interval. * Images from crops - In earlier versions of the plugin we would pull down the image from the URL in ``. Alas, a lot of those images were small, with ?s=12 in the URL, or thumbnails. So now we're bringing down any bigger versions that we can find. We'll look for the following elements under tags. In order ``, ``, ``, and then get `` if those other elements do not exist. This should help with getting bigger images. If you need a smaller image, just theme the bigger one. -* When pushing a story to the NPR API, we will now be checking to see if images exist in the content, if so, add the query string parameter `origin=body` to the image url so CorePublisher will like it. This is only something the Core Publisher uses, but it will help greatly for stories published in Wordpress and retrieved into Core Publisher. +* When pushing a story to the NPR Story API, we will now be checking to see if images exist in the content, if so, add the query string parameter `origin=body` to the image url so CorePublisher will like it. This is only something the Core Publisher uses, but it will help greatly for stories published in Wordpress and retrieved into Core Publisher. * Adding meta data as meta fields to each pulled image. The following meta fields will be attached to the posts for pulled images: npr_image_credit =>$api_image->producer @@ -145,35 +145,35 @@ NPR Stories having got gotten ### V1.4 -* Filters for Shortcodes - We've now implemented a hook to a filter that will be used to alter any short codes that a plugin may own in a post before pushing that post to the NPR API. The filter (`npr_ds_shortcode_filter`) will fire before we remove shortcodes when we're pushing the post. Any plugin that has shortcodes should alter those shortcodes via this filter to something that's more HTML-friendly, so that other clients can access that information. As an example of what needs to be done in a plugin to take advantage of this new filter please see the branch for the following plugin: What we've done here is write a function `my_documentCloud_filter` that is linked to the filter `npr_ds_shortcode_filter` (all near the bottom of the PHP file). This function will turn any shortcode created by this plugin into an HTML `` tag to link to what was an embedded document. As with any other filter in WordPress, nothing will happen if you do not have any plugins installed that have implemented the filter. It will be up to any other plugin's maintainer to implement the filter correctly if they wish to take advantage of this functionality. -* Bulk Push - From the post list page for you NPR Push post type you can now select multiple posts and using the bulk operation dropdown on that page, push the selected posts to the NPR API. This should helpful for posts that have been living on a site before the NPR API plugin was installed. Note that this will only push a maximum 20 posts at one time. +* Filters for Shortcodes - We've now implemented a hook to a filter that will be used to alter any short codes that a plugin may own in a post before pushing that post to the NPR Story API. The filter (`npr_ds_shortcode_filter`) will fire before we remove shortcodes when we're pushing the post. Any plugin that has shortcodes should alter those shortcodes via this filter to something that's more HTML-friendly, so that other clients can access that information. As an example of what needs to be done in a plugin to take advantage of this new filter please see the branch for the following plugin: What we've done here is write a function `my_documentCloud_filter` that is linked to the filter `npr_ds_shortcode_filter` (all near the bottom of the PHP file). This function will turn any shortcode created by this plugin into an HTML `` tag to link to what was an embedded document. As with any other filter in WordPress, nothing will happen if you do not have any plugins installed that have implemented the filter. It will be up to any other plugin's maintainer to implement the filter correctly if they wish to take advantage of this functionality. +* Bulk Push - From the post list page for you NPR Push post type you can now select multiple posts and using the bulk operation dropdown on that page, push the selected posts to the NPR Story API. This should helpful for posts that have been living on a site before the NPR Story API plugin was installed. Note that this will only push a maximum 20 posts at one time. * Publish or Draft for Get Multi - It's now possible for an admin to select Draft or Publish for the posts that come from a query on the get multi page. This way, the return from each query can be reviewed before it's published to a site. * Run Get Multi on Demand - An admin can now select a checkbox if they would like the get multi queries to run when the page is saved. This will allow admins to immediately check queries instead of having to wait for the cron to run. ### V1.3 -* Permissions - If you have created any NPR API Permissions Groups you can select which (if any) group you would like to use as your default group when pushing content to the NPR API. Learn more about NPR API Permissions Groups here: +* Permissions - If you have created any NPR Story API Permissions Groups you can select which (if any) group you would like to use as your default group when pushing content to the NPR Story API. Learn more about NPR Story API Permissions Groups here: * Multi-Site - Cron set up and other activation tasks will now happen on every site in a multi-site configuration. * Cron queries - We won't try to query for any of the configured queries on the Get Multi page if the field isn't filled in with data. * Content and short codes - Instead of blindly removing all shortcodes from a story's content, we are now trying to let any plugins replace the shortcodes with HTML, and then if there are any leftover shortcodes (we delete those?). -* Byline URL - We are now saving any links to the author of a story's bio page in the meta field `npr_byline_link`. This should allow you to supply a link for any author who has a biography registered with the NPR API. +* Byline URL - We are now saving any links to the author of a story's bio page in the meta field `npr_byline_link`. This should allow you to supply a link for any author who has a biography registered with the NPR Story API. ### V1.2 -* Enhance 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. And finally, we've add the ability to retrieve transcripts for stories that have transcripts associated with them. Along with these changes we've added the the ability to save urls for the .m3u files attached to NPR stories. +* Enhance error messages when there are connectivity or permissions issues with your NPR Story 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 Story API. And finally, we've add the ability to retrieve transcripts for stories that have transcripts associated with them. Along with these changes we've added the the ability to save urls for the .m3u files attached to NPR stories. ### V1.1 -This version will allow admins to configure their WordPress site to retrieve multiple NPR API stories that will be automatically published (via cron) to their site. +This version will allow admins to configure their WordPress site to retrieve multiple NPR Story API stories that will be automatically published (via cron) to their site. -* 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. +* From the **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. * These query entries can contain an API ID for a single story, or an ID for a specific category, program, topic, etc. -* The query can also contain the full query string can be created from the NPR API Query Generator: +* The query can also contain the full query string can be created from the NPR Story API Query Generator: * 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 query filters at the npr.org's API documentation page: -* Stories retrieved from the NPR API will be created as Posts in WordPress. 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`. The list of npr_ meta fields is: +* Stories retrieved from the NPR Story API will be created as Posts in WordPress. 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`. The list of npr_ meta fields is: npr_api_link npr_byline @@ -184,21 +184,21 @@ This version will allow admins to configure their WordPress site to retrieve mul npr_story_content npr_story_id -* 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, this plugin will re-query the NPR API for those stories, and if the story's content has changed it 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 to the NPR API again. +* On the All Posts admin screen we've made a couple of modification/additions to help you manage your NPR Story API content. + - There is a new Bulk Action available, 'Update NPR Story'. When one or many NPR Story API Stories are selected and the Update NPR Story action is applied, this plugin will re-query the NPR Story API for those stories, and if the story's content has changed it 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 Story API there will be a link to "Update" the story. Pressing this link will bring the user to the query NPR Story API page with the story ID pre-filled. Pressing "Publish" on this screen will re-query the NPR Story API for the story and update the Post with any changes that may have taken place on the NPR Story API for that story. +* Update and Delete of pushed stories - A story that was written in your Wordpress site and pushed to the NPR Story 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 Story API. If a Trashed Post is resorted, your story will be made available to the NPR Story API again. ### V1.0 -As not a lot of users have installed the V1.0 of the NPR API Plugin, there are a couple of things to keep in mind. +As not a lot of users have installed the V1.0 of the NPR Story API Plugin, there are a couple of things to keep in mind. -* 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 push stories to the NPR API you'll need to have your key configured by NPR Digital Services. Please contact Digital Services with a support request at +* On the NPR Story API settings page (wp-admin/options-general.php?page=ds_npr_api) there are 4 fields. + - API KEY - This is your NPR Story API Key that you can get from NPR. If you wish to push stories to the NPR Story API you'll need to have your key configured by NPR Digital Services. Please contact Digital Services with a support request at - Pull URL - This is the root url for retrieving stories. For testing purposes, you should configure this to be `https://api-s1.npr.org`. NOTE: this url should not contain a trailing 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 server at `https://api-s1.npr.org`. If you do not wish to push your content, or your NPR API has not been authorized, you should leave this field empty and the WordPress plugin will not attempt to push you content to the NPR API. + - Push URL - Much like the pull url, this url is used to pushing stories to the NPR Story API. Again, for testing purposes, you can utilize NPR's staging server at `https://api-s1.npr.org`. If you do not wish to push your content, or your NPR Story API has not been authorized, you should leave this field empty and the WordPress plugin will not attempt to push you content to the NPR Story API. - Org ID - This is your organization's ID assigned by NPR. If you don't know your Org ID, please contact Digital Services at: -* 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 can be story ID from the API, or the URL for the story from npr.org. For help in finding possible query options, please use the Query Generator at Documentation is at: +* You can pull stories one at a time from the NPR Story API by using the Get NPR Stories page under admin Posts menu (wp-admin/edit.php?page=get-npr-stories). This can be story ID from the API, or the URL for the story from npr.org. For help in finding possible query options, please use the Query Generator at Documentation is at: ## Upgrade Notice diff --git a/docs/field-mapping.md b/docs/field-mapping.md index d3dbb35..e35c301 100644 --- a/docs/field-mapping.md +++ b/docs/field-mapping.md @@ -1,9 +1,9 @@ -# NPR API Field Mapping +# NPR Story API Field Mapping -In most cases your posts will successfully push to the NPR API using the standard WordPress fields including the post title and body. If your WordPress site has post types that use custom fields, you can map those fields to the NPR Story API using the settings in **Settings > NPR API Field Mapping**. +In most cases your posts will successfully push to the NPR Story API using the standard WordPress fields including the post title and body. If your WordPress site has post types that use custom fields, you can map those fields to the NPR Story API using the settings in **Settings > NPR API Field Mapping**. -Select your custom fields to map them to the NPR API labels: +Select your custom fields to map them to the NPR Story API labels: -![NPR API push settings for custom fields](assets/img/npr-api-wp-plugin-field-mapping.png) +![NPR Story API push settings for custom fields](assets/img/npr-api-wp-plugin-field-mapping.png) -Don't forget to click **Save Changes**! \ No newline at end of file +Don't forget to click **Save Changes**! diff --git a/docs/installation.md b/docs/installation.md index a8a5dda..fd29e9d 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -3,7 +3,7 @@ 1. Download the plugin files from this repository 2. Unzip and upload the unzipped plugin folder to the `/wp-content/plugins/` directory of your WordPress install OR go to **Plugins > Add New** from the WordPress dashboard and upload the plugin zip file 3. Activate the plugin through the **Plugins** screen in WordPress -4. Use the **Settings > NPR API** screen to configure the plugin. Begin by entering your API Key, then add your Push URL and Org ID. +4. Use the **Settings > NPR Story API** screen to configure the plugin. Begin by entering your API Key, then add your Push URL and Org ID. If you don't have an API Key or Org ID you can request them by [registering for an NPR account](https://secure.npr.org/oauth2/login). diff --git a/docs/npr-one.md b/docs/npr-one.md index b52603b..354842f 100644 --- a/docs/npr-one.md +++ b/docs/npr-one.md @@ -1,13 +1,13 @@ -# Pushing Posts to NPR One +# Pushing Posts to NPR One -You can easily push posts to the [NPR One mobile app](https://www.npr.org/about/products/npr-one/) in addition to the NPR API. +You can easily push posts to the [NPR One mobile app](https://www.npr.org/about/products/npr-one/) in addition to the NPR Story API. -After you [set up the WordPress NPR API Plugin](settings.md) with your API Key and Org ID, you will see a new checkbox in the Post Edit screen for "Include for listening in NPR One": +After you [set up the WordPress NPR Story API Plugin](settings.md) with your API Key and Org ID, you will see a new checkbox in the Post Edit screen for "Include for listening in NPR One": ![Send to NPR One checkbox in the WordPress post edit screen](assets/img/test-post-npr-one.png) -The checkbox is not selected by default. This allows you to push all your stories to the NPR API, but only selected stories to NPR One. +The checkbox is not selected by default. This allows you to push all your stories to the NPR Story API, but only selected stories to NPR One. If you want to push a post to NPR One, check the box and hit the Publish or Update button. -If you are sending the story to NPR One, you can also choose to mark the story as a featured story in NPR One. \ No newline at end of file +If you are sending the story to NPR One, you can also choose to mark the story as a featured story in NPR One. diff --git a/docs/pulling-multiple-stories.md b/docs/pulling-multiple-stories.md index eb19802..ca61ebe 100644 --- a/docs/pulling-multiple-stories.md +++ b/docs/pulling-multiple-stories.md @@ -1,28 +1,28 @@ -# Pulling Multiple Stories from the NPR API By Custom API Query +# Pulling Multiple Stories from the NPR Story API By Custom API Query You can set up and save one or more API queries to pull content based on topic, program, and other filters of your choosing. Once saved, these queries will retrieve new stories every hour, or any time interval you set. -In the WordPress Dashboard go to **Settings > NPR API Get Multi**. This screen offers several **Query String** fields where you can enter a query string for the NPR API. +In the WordPress Dashboard go to **Settings > NPR API Get Multi**. This screen offers several **Query String** fields where you can enter a query string for the NPR Story API. -![NPR API plugin settings for getting multiple stories](assets/img/wp-npr-api-get-multi-settings.png) +![NPR Story API plugin settings for getting multiple stories](assets/img/wp-npr-api-get-multi-settings.png) -Note that "Query String" simply means a URL containing query parameters like a Subject ID, content type, date range, number of results to return, etc. An NPR API query string looks something like this: +Note that "Query String" simply means a URL containing query parameters like a Subject ID, content type, date range, number of results to return, etc. An NPR Story API query string looks something like this: `https://api.npr.org/query?id=1014,2&requiredAssets=audio&startDate=2016-04-01&endDate=2016-06-05&dateType=story&output=NPRML&numResults=10` -You can enter multiple query strings to pull content for different subjects, programs, etc., and set how often the queries will run. Once you save one or more queries, WordPress will continue to run them against the NPR API and return fresh stories as WordPress Posts or Drafts. +You can enter multiple query strings to pull content for different subjects, programs, etc., and set how often the queries will run. Once you save one or more queries, WordPress will continue to run them against the NPR Story API and return fresh stories as WordPress Posts or Drafts. ## How to Create a Query String -You can easily create query strings for API content by visiting the [NPR API Query Generator](https://www.npr.org/api/queryGenerator.php). The Query Generator provides a graphical user interface to create queries by topic, blogs, program, series, stations, and other values in the NPR API. Note that the **Control** tab of the Query Generator adds filtering by date or date range, search terms, and content type. You can also specify the number of results to return for a given query. +You can easily create query strings for API content by visiting the [NPR Story API Query Generator](https://www.npr.org/api/queryGenerator.php). The Query Generator provides a graphical user interface to create queries by topic, blogs, program, series, stations, and other values in the NPR Story API. Note that the **Control** tab of the Query Generator adds filtering by date or date range, search terms, and content type. You can also specify the number of results to return for a given query. After creating a query in the Query Generator, click the button to **Create API Call**: -![Creating a query in the NPR API Query Generator](assets/img/npr-api-query-generator.png) +![Creating a query in the NPR Story API Query Generator](assets/img/npr-api-query-generator.png) After you click the button to create your API call, you'll find the full URL of the query in the **Generated API Call** window: -![a query URL in the NPR API Query Generator](assets/img/npr-api-query-url.png) +![a query URL in the NPR Story API Query Generator](assets/img/npr-api-query-url.png) Now copy the API call string up to the last segment `&apiKey=demo`. Do not include this in copying the query string. _(That segment would only be useful if you were going to run the query in the Query Generator itself, which we're not doing here.)_ @@ -30,7 +30,7 @@ Now that you've created and copied a query string, return to your WordPress Dash ![a query URL entered in the Query String field in WordPress](assets/img/npr-api-multiple-get-settings.png) -When you click **Save Changes**, WordPress will begin pulling NPR API content. Note that it may take up to an hour before stories begin showing up as Posts or Drafts. +When you click **Save Changes**, WordPress will begin pulling NPR Story API content. Note that it may take up to an hour before stories begin showing up as Posts or Drafts. You can add more queries any time. If you run out of Query String fields, just increase the **Number of things to get** setting to add more fields. @@ -46,6 +46,6 @@ Now you can edit any pulled story much like any other post. Although note that u ## Updating Pulled Stories -NPR often updates stories and pushes the updates to the NPR API. The same is true for other sources of content in the NPR API. You can easily update any stories you pulled from the API by visiting the **Posts** screen for your NPR Pull Post Type, and using the **Update NPR Story** Bulk Action: +NPR often updates stories and pushes the updates to the NPR Story API. The same is true for other sources of content in the NPR Story API. You can easily update any stories you pulled from the API by visiting the **Posts** screen for your NPR Pull Post Type, and using the **Update NPR Story** Bulk Action: ![Bulk Action menu link for Updating NPR Stories](assets/img/bulk-actions-update-npr-story.png) diff --git a/docs/pulling-single-story.md b/docs/pulling-single-story.md index 70a6810..52e9d51 100644 --- a/docs/pulling-single-story.md +++ b/docs/pulling-single-story.md @@ -1,6 +1,6 @@ -# Pulling a Single Story from the NPR API +# Pulling a Single Story from the NPR Story API -Once you have the [NPR API Plugin configured](/docs/settings.md), you can easily pull a story from the API into WordPress using a Story ID or URL. +Once you have the [NPR Story API Plugin configured](/docs/settings.md), you can easily pull a story from the API into WordPress using a Story ID or URL. In the WordPress Dashboard under **Posts** you will see a link for **Get NPR Stories**: @@ -30,6 +30,6 @@ Stories in the NPR Story API contain a lot of metadata. When you pull a story fr If you don't see these custom fields in the post edit screen, click **Screen Options** in the upper right and then the checkbox for Custom Fields. -## Using NPR API Custom Fields in your WordPress theme +## Using NPR Story API Custom Fields in your WordPress theme -The custom fields generated by the NPR API provide a lot of flexibility for displaying API content in various ways. If you are familiar with WordPress theming, you could customize your WordPress theme to use the custom fields in your templates. For a reference on how to use these additional fields in your theme, refer to [the relevant documentation](https://codex.wordpress.org/Custom_Fields) in the WordPress Codex. +The custom fields generated by the NPR Story API provide a lot of flexibility for displaying API content in various ways. If you are familiar with WordPress theming, you could customize your WordPress theme to use the custom fields in your templates. For a reference on how to use these additional fields in your theme, refer to [the relevant documentation](https://codex.wordpress.org/Custom_Fields) in the WordPress Codex. diff --git a/docs/pushing.md b/docs/pushing.md index 87b038f..5ed3554 100644 --- a/docs/pushing.md +++ b/docs/pushing.md @@ -1,12 +1,12 @@ -# Pushing Stories to the NPR API +# Pushing Stories to the NPR Story API -You can push any of your posts to the NPR API by checking the "Send to NPR API" box in the "NPR Story API" meta box in the post editor. Once this box is checked, publishing the post or saving an updated version of a published post will send the post to the NPR API. +You can push any of your posts to the NPR Story API by checking the "Send to NPR Story API" box in the "NPR Story API" meta box in the post editor. Once this box is checked, publishing the post or saving an updated version of a published post will send the post to the NPR Story API. ![Push to NPR button in the post edit screen](assets/img/push-to-npr-api.png) -By default any standard WordPress post can be pushed to the NPR API. If you have a custom post type you want to reserve for stories pushed to the API, you can select this in the **Settings > NPR API > NPR Push Post Type** setting, and only those posts will be pushed. +By default any standard WordPress post can be pushed to the NPR Story API. If you have a custom post type you want to reserve for stories pushed to the API, you can select this in the **Settings > NPR Story API > NPR Push Post Type** setting, and only those posts will be pushed. -![NPR API plugin settings page](assets/img/npr-api-wp-plugin-settings.png) +![NPR Story API plugin settings page](assets/img/npr-api-wp-plugin-settings.png) ## Verifying Pushed Stories @@ -16,16 +16,16 @@ After publishing the post and pushing it to NPR we can easily verify that it was If the push fails you will instead see an error message in a custom field named `npr_push_story_error`: -![NPR API push error message](assets/img/npr-api-push-error.png) +![NPR Story API push error message](assets/img/npr-api-push-error.png) -If you get push errors, check **Settings > NPR API** to make sure correct values are entered for your API Key, Pull URL, Push URL, Org ID, and NPR Push Post Type. (See the [NPR API Plugin Settings page for details](settings.md).) +If you get push errors, check **Settings > NPR API** to make sure correct values are entered for your API Key, Pull URL, Push URL, Org ID, and NPR Push Post Type. (See the [NPR Story API Plugin Settings page for details](settings.md).) If you don't see these custom fields in the post edit screen, click **Screen Options** in the upper right and then the checkbox for Custom Fields. -## Pushing Story Updates to the NPR API +## Pushing Story Updates to the NPR Story API -If you edit a story that's previously been pushed to the NPR API, the changes will be pushed to the NPR API. +If you edit a story that's previously been pushed to the NPR Story API, the changes will be pushed to the NPR Story API. -## Deleting Posts from the NPR API +## Deleting Posts from the NPR Story API -You can delete any of your stories from the NPR API by simply deleting them in WordPress. Stories you pull from the API can't be deleted in this way, as you only have delete access to stories pushed to the API from your WordPress site. +You can delete any of your stories from the NPR Story API by simply deleting them in WordPress. Stories you pull from the API can't be deleted in this way, as you only have delete access to stories pushed to the API from your WordPress site. diff --git a/docs/readme.md b/docs/readme.md index d18f67a..eeb725d 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -1,10 +1,10 @@ -# NPR API Plugin Docs +# NPR Story API Plugin Docs -The NPR Story API Plugin provides push and pull functionality with the [NPR API](https://www.npr.org/api/index) along with a user-friendly administrative interface. +The NPR Story API Plugin provides push and pull functionality with the [NPR Story API](https://www.npr.org/api/index) along with a user-friendly administrative interface. -NPR's API is a content API, which essentially provides a structured way for other computer applications to pull NPR stories in a predictable, flexible and powerful way. The content that is available includes audio from most NPR programs dating back to 1995 as well as text, images and other web-only content from NPR and NPR member stations. This archive consists of over 250,000 stories that are grouped into more than 5,000 different aggregations. +NPR's Story API is a content API, which essentially provides a structured way for other computer applications to pull NPR stories in a predictable, flexible and powerful way. The content that is available includes audio from most NPR programs dating back to 1995 as well as text, images and other web-only content from NPR and NPR member stations. This archive consists of over 250,000 stories that are grouped into more than 5,000 different aggregations. -Access to the NPR API requires an API Key which you can get by [registering for an NPR account](https://secure.npr.org/oauth2/login). +Access to the NPR Story API requires an API Key which you can get by [registering for an NPR account](https://secure.npr.org/oauth2/login). The WordPress plugin is being developed as an Open Source plugin by NPR Digital Services. 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 [https://info.ds.npr.org/support.html](https://info.ds.npr.org/support.html). @@ -12,8 +12,8 @@ The WordPress plugin is being developed as an Open Source plugin by NPR Digital - [Installation](installation.md) - [Plugin Settings](settings.md) -- [Pulling a Single Story from the NPR API](pulling-single-story.md) -- [Pulling Multiple Stories from the NPR API By Custom API Query](pulling-multiple-stories.md) -- [Pushing Content to the NPR API](pushing.md) +- [Pulling a Single Story from the NPR Story API](pulling-single-story.md) +- [Pulling Multiple Stories from the NPR Story API By Custom API Query](pulling-multiple-stories.md) +- [Pushing Content to the NPR Story API](pushing.md) - [Pushing Content to the NPR One app](npr-one.md) - [Custom Field Mapping](field-mapping.md) diff --git a/docs/settings.md b/docs/settings.md index f281156..66ba243 100644 --- a/docs/settings.md +++ b/docs/settings.md @@ -2,11 +2,11 @@ ## Before you start -To pull content from the NPR API you'll need an API Key. Please contact [NPR's Member Partnership team](https://nprsupport.desk.com/customer/login) to acquire a key. +To pull content from the NPR Story API you'll need an API Key. Please contact [NPR's Member Partnership team](https://nprsupport.desk.com/customer/login) to acquire a key. -If you are planning to push content to the NPR API you'll also need an NPR API Org ID. If you are an NPR station or affiliated producer you can find your Org ID at [NPR StationConnect](https://stationconnect.org/login?redirect=%2F). +If you are planning to push content to the NPR Story API you'll also need an NPR Story API Org ID. If you are an NPR station or affiliated producer you can find your Org ID at [NPR StationConnect](https://stationconnect.org/login?redirect=%2F). -If you don't have an Org ID or don't intend to push content into the NPR API you can still pull content from the API, but be mindful of the [Terms of Use](https://www.npr.org/about-npr/179876898/terms-of-use). +If you don't have an Org ID or don't intend to push content into the NPR Story API you can still pull content from the API, but be mindful of the [Terms of Use](https://www.npr.org/about-npr/179876898/terms-of-use). ## Configure your settings @@ -18,10 +18,10 @@ For NPR Pull Post Type you can leave the default or pick a custom post type. You For NPR Push Post Type you can leave the default or set it to another post type, like `post`. -If you have configured any Permissions Groups for content you distribute through the NPR API you can optionally add them in the NPR Permissions setting. Note that by default all content in the NPR API is open to everyone, unless you restrict access to a Permissions Group. For more on setting these up see the [NPR API Content Permissions Control page](https://nprsupport.desk.com/customer/en/portal/articles/1995557-npr-api-content-permissions-control). +If you have configured any Permissions Groups for content you distribute through the NPR Story API you can optionally add them in the NPR Permissions setting. Note that by default all content in the NPR Story API is open to everyone, unless you restrict access to a Permissions Group. For more on setting these up see the [NPR Story API Content Permissions Control page](https://nprsupport.desk.com/customer/en/portal/articles/1995557-npr-api-content-permissions-control). Once you have all the above entered your settings panel should look something like this: -![NPR API plugin settings page with values filled in as described above](assets/img/npr-api-wp-plugin-settings.png) +![NPR Story API plugin settings page with values filled in as described above](assets/img/npr-api-wp-plugin-settings.png) -Hit **Save Changes** and you're ready to start using the NPR API. +Hit **Save Changes** and you're ready to start using the NPR Story API. diff --git a/readme.txt b/readme.txt index 2957afe..a0c65c9 100644 --- a/readme.txt +++ b/readme.txt @@ -13,11 +13,11 @@ A collection of tools for reusing content from NPR.org supplied by Digital Servi == Description == -The NPR Story API Plugin provides push and pull functionality with the NPR API along with a user-friendly administrative interface. +The NPR Story API Plugin provides push and pull functionality with the NPR Story API along with a user-friendly administrative interface. NPR's API is a content API, which essentially provides a structured way for other computer applications to get NPR stories in a predictable, flexible and powerful way. The content that is available includes audio from most NPR programs dating back to 1995 as well as text, images and other web-only content from NPR and NPR member stations. This archive consists of over 250,000 stories that are grouped into more than 5,000 different aggregations. -Access to the NPR API requires an API Key which you can get by [registering for an NPR account](https://secure.npr.org/oauth2/login). +Access to the NPR Story API requires an API Key which you can get by [registering for an NPR account](https://secure.npr.org/oauth2/login). The WordPress plugin is being developed as an Open Source plugin by NPR Digital Services. 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 [https://info.ds.npr.org/support.html](https://info.ds.npr.org/support.html). @@ -25,38 +25,38 @@ The WordPress plugin is being developed as an Open Source plugin by NPR Digital 1. Upload the plugin files to the `/wp-content/plugins/plugin-name` directory, or install the plugin through the WordPress plugins screen directly. 2. Activate the plugin through the 'Plugins' screen in WordPress -3. Use the Settings->NPR API screen to configure the plugin. Begin by entering your API Key, then add your Push URL and Org ID. +3. Use the **Settings > NPR API** screen to configure the plugin. Begin by entering your API Key, then add your Push URL and Org ID. == Frequently Asked Questions == -= Can anyone get an NPR API Key? = += Can anyone get an NPR Story API Key? = That's up to NPR but you can [register for an account here](https://secure.npr.org/oauth2/login). -= Can anyone push content into the NPR API using this plugin? = += Can anyone push content into the NPR Story API using this plugin? = -Push requires an Organization ID in the NPR API, which is typically given out to only NPR stations and approved content providers. If that's you, you probably already have an Organization ID. +Push requires an Organization ID in the NPR Story API, which is typically given out to only NPR stations and approved content providers. If that's you, you probably already have an Organization ID. -= Where can I find NPR's documentation on the NPR API? = += Where can I find NPR's documentation on the NPR Story API? = -The best resource for general information about the NPR API is here: [https://nprsupport.desk.com/customer/en/portal/topics/783619-api/articles](https://nprsupport.desk.com/customer/en/portal/topics/783619-api/articles). +The best resource for general information about the NPR Story API is here: [https://nprsupport.desk.com/customer/en/portal/topics/783619-api/articles](https://nprsupport.desk.com/customer/en/portal/topics/783619-api/articles). -There's also the documentation in the NPR API site: [https://www.npr.org/api/index.php](https://www.npr.org/api/index.php). +There's also the documentation in the NPR Story API site: [https://www.npr.org/api/index.php](https://www.npr.org/api/index.php). -= Is there an easy way to directly query the NPR API? = += Is there an easy way to directly query the NPR Story API? = You bet, just visit the NPR Query Generator: [https://www.npr.org/api/queryGenerator.php](https://www.npr.org/api/queryGenerator.php) == Screenshots == -NPR API Plugin Settings screen +NPR Story API Plugin Settings screen -![NPR API Plugin Settings screen](docs/assets/img/npr-api-wp-plugin-settings.png) +![NPR Story API Plugin Settings screen](docs/assets/img/npr-api-wp-plugin-settings.png) -NPR API multiple get settings +NPR Story API multiple get settings -![NPR API multiple get settings](docs/assets/img/npr-api-multiple-get-settings.png) +![NPR Story API multiple get settings](docs/assets/img/npr-api-multiple-get-settings.png) Get NPR Stories link in the dashboard @@ -78,7 +78,7 @@ NPR Stories having got gotten * Fixes issue preventing pushing to the API, introduced in V1.7. [PR #60](https://github.com/npr/nprapi-wordpress/pull/60) for [issue #57](https://github.com/npr/nprapi-wordpress/issues/57). * Fixes issue where images were not properly sideloaded. [PR #60](https://github.com/npr/nprapi-wordpress/pull/60) for [issue #59](https://github.com/npr/nprapi-wordpress/issues/59). * Fixes invalid GMT offset error when creating new DateTimeZone object in post metabox. [PR #53](https://github.com/npr/nprapi-wordpress/pull/53) for [issue #52](https://github.com/npr/nprapi-wordpress/issues/52). -* When interacting with a site using the plugin in an unconfigured state, users will be prompted to set the NPR API Push URL. [PR #56](https://github.com/npr/nprapi-wordpress/pull/56) for [issue #51](https://github.com/npr/nprapi-wordpress/issues/51). +* When interacting with a site using the plugin in an unconfigured state, users will be prompted to set the NPR Story API Push URL. [PR #56](https://github.com/npr/nprapi-wordpress/pull/56) for [issue #51](https://github.com/npr/nprapi-wordpress/issues/51). * Miscellaneous code quality improvements. = V1.7.1 = @@ -175,7 +175,7 @@ NPR Stories having got gotten This version will allow admins to configure their WordPress site to retrieve multiple NPR API stories that will be automatically published (via cron) to their site. -* 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. +* From the **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. * These query entries can contain an API ID for a single story, or an ID for a specific category, program, topic, etc. * The query can also contain the full query string can be created from the NPR API Query Generator: * You can also enter the URL for a story you found on npr.org.