From 123c1abe8a0db8cb813c6b721d631b3d993e762c Mon Sep 17 00:00:00 2001 From: Ben Keith Date: Tue, 4 Sep 2018 20:50:58 -0400 Subject: [PATCH 1/2] Rename the plugin to Pym.js Embeds in most places. --- README.md | 4 ++-- docs/readme.md | 34 +++++++++++++++++----------------- pym-shortcode.php | 2 +- readme.txt | 13 ++++++++----- 4 files changed, 28 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 1cf8f51..a7379ce 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -# Pym Shortcode +# Pym.js Embeds -This plugin allows the use of NPR's [Pym.js](http://blog.apps.npr.org/pym.js/) responsive iframe script on WordPress sites, through the use of shortcodes and Gutenberg block. +This plugin allows the use of NPR's [Pym.js](http://blog.apps.npr.org/pym.js/) responsive iframe script on WordPress sites, through the use of shortcodes and Gutenberg blocks. For detailed examples, ➡️ [read the docs!](./docs/) ⬅️ diff --git a/docs/readme.md b/docs/readme.md index 4723e24..1ec66b8 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -1,6 +1,6 @@ -# Pym Shortcode +# Pym.js Embeds for WordPress -Pym Shortcode will responsively resize an iframe's height depending on the width of its container. The plugin uses [Pym.js](http://blog.apps.npr.org/pym.js/), developed by the [NPR Visuals Team](http://blog.apps.npr.org/), to allow embedded content in WordPress posts and pages using a simple shortcode. Using `Pym.js`, it bypasses the usual cross-domain issues. +Pym.js Embeds provides shortcode and Gutenberg block wrappers for embedding responsive iframes using [Pym.js](http://blog.apps.npr.org/pym.js/), developed by the NPR Visuals Team. Embedded content resizes vertically to match its container's width. Contents: @@ -31,13 +31,13 @@ Contents: ## Plugin Installation -1. In the WordPress Dashboard go to **Plugins**, then click the **Add Plugins** button and search the WordPress Plugins Directory for Pym Shortcode. Alternatively, you can download the zip file from this Github repo and upload it manually to your WordPress site. -2. Activate the plugin through the 'Plugins' screen in WordPress -3. Nothing to configure, just begin using Pym Shortcode! +1. In the WordPress Dashboard go to **Plugins**, then click the **Add Plugins** button and search the WordPress Plugins Directory for Pym.js Embeds. Alternatively, you can download the zip file from this Github repo and upload it manually to your WordPress site. +2. Activate the plugin through the 'Plugins' screen in WordPress. +3. Nothing to configure, just begin using Pym.js Embeds! ## The Pym Shortcode -In a WordPress post or page use Pym Shortcode like this: +In a WordPress post or page, use Pym Shortcode like this: `[pym src="https://blog.apps.npr.org/pym.js/examples/table/child.html"]` @@ -51,7 +51,7 @@ Example in a post: ![Screenshot of the Pym Embed block in a post, with the block settings pane opened to show the block's options and advanced options](img/block-in-editor.png) -For the block, all options available via shortcode arguments are available through the block's advanced options panel. +For the block, all options available via shortcode arguments are available through the block's Advanced Options panel. ## Options @@ -73,7 +73,7 @@ Here's what the setting looks like in a block: ![A Pym embed block in use in a post, showing its alignment controls](img/block.png) -### `pymsrc`, the URL for pym.js +### `pymsrc`, the URL for Pym.js `pymsrc` is optional; only set this if you need to specify a different source for `Pym.js` than the default. The default `Pym.js` source URL is `js/pym.v1.min.js` in this plugin's directory on your server. [NPR recommends](http://blog.apps.npr.org/pym.js/#get-pym-cdn) that you use the CDN version of `Pym.js` in most cases, which is available at `https://pym.nprapps.org/pym.v1.min.js`. An example shortcode using this option is as follows: @@ -81,7 +81,7 @@ Here's what the setting looks like in a block: [pym src="https://blog.apps.npr.org/pym.js/examples/table/child.html" pymsrc="https://pym.nprapps.org/pym.v1.min.js"] ``` -### `pymoptions`, settings for Pym +### `pymoptions`, settings for Pym.js `pymoptions` is optional; this should be a javascript object without the surrounding `{}`, and is given in the event that options need to be passed to the `pymParent`. NPR gives [this example](http://blog.apps.npr.org/pym.js/#examples) javascript: @@ -89,7 +89,7 @@ Here's what the setting looks like in a block: pym.Parent('example', 'https://blog.apps.npr.org/pym.js/examples/table/child.html', { xdomain: '*\.npr\.org' }); ``` -To do the same thing with this Pym shortcode, you would write: +To do the same thing with this Pym Shortcode, you would write: ``` [pym src="https://blog.apps.npr.org/pym.js/examples/table/child.html" pymoptions=" xdomain: '\\*\.npr\.org' "] @@ -127,25 +127,25 @@ For example, the shortcode `[pym src="https://blog.apps.npr.org/pym.js/examples/ ## Frequently Asked Questions -### Why would I want to use Pym in the first place? +### Why would I want to use Pym.js in the first place? Using iframes in a responsive page can be frustrating. It’s easy enough to make an iframe’s width span 100% of its container, but sizing its height is tricky — especially if the content of the iframe changes height depending on page width (for example, because of text wrapping or media queries) or events within the iframe. For more information, see [NPR's documentation for `Pym.js`](http://blog.apps.npr.org/pym.js). ### Why is a WordPress plugin needed to use `Pym.js`? -Normally WordPress strips out JavaScript inserted in posts and pages, so the usual HTML `Pym.js` embed code's `', - wp_json_encode( __( 'Hi Pym user! It looks like your post has multiple values for pymsrc for the blocks and shortcodes in use on this page. This may be causing problems for your Pym embeds. For more details, see https://github.com/INN/pym-shortcode/tree/master/docs#ive-set-a-different-pymsrc-option-but-now-im-seeing-a-message-in-the-console', 'pym_shortcode' ) ), + wp_json_encode( __( 'Hi Pym.js user! It looks like your post has multiple values for pymsrc for the blocks and shortcodes in use on this page. This may be causing problems for your Pym.js embeds. For more details, see https://github.com/INN/pym-shortcode/tree/master/docs#ive-set-a-different-pymsrc-option-but-now-im-seeing-a-message-in-the-console', 'pym_shortcode' ) ), wp_json_encode( $this->sources ) ); } diff --git a/inc/info-page.php b/inc/info-page.php index 4ec534e..73783af 100644 --- a/inc/info-page.php +++ b/inc/info-page.php @@ -3,6 +3,8 @@ * The informational page for this plugin. * * This is available to everyone who can edit posts, because they'll need this info if they're creating new child pages for embed using the shortcode or plugin. + * + * @package pym-embeds */ namespace INN\PymEmbeds\Info; diff --git a/inc/settings-page.php b/inc/settings-page.php index ace28e6..8b549e0 100644 --- a/inc/settings-page.php +++ b/inc/settings-page.php @@ -2,6 +2,7 @@ /** * The settings page for this plugin. * + * @package pym-embeds */ namespace INN\PymEmbeds\Settings; diff --git a/inc/shortcode.php b/inc/shortcode.php index cf73074..0eff0c0 100644 --- a/inc/shortcode.php +++ b/inc/shortcode.php @@ -2,7 +2,7 @@ /** * The [pym] shortcode and related functions * - * @package pym-shortcode + * @package pym-embeds */ use INN\PymEmbeds\Settings\option_key; @@ -10,7 +10,8 @@ /** * A shortcode to simplify the process of embedding articles using pym.js * - * This function also powers the Pym Embed block output. + * This function also powers the Pym.js Embed block output in Gutenberg, + * as the render callback for a dynamic block. * * @param Array $atts the attributes passed in the shortcode. * @param String $content the enclosed content; should be empty for this shortcode. @@ -72,8 +73,10 @@ function pym_shortcode( $atts = array(), $content = '', $tag = '' ) { $pymsrc = $atts['pymsrc']; } - // If this is the first Pym element on the page, output the pymsrc script tag - // or if the pymsrc is set, output that. + // If this is the first Pym.js element on the page, + // register the default pymsrc script tag for output. + // + // Or, if the pymsrc is set, register that specific pymsrc for output. if ( 0 === $pym_id || ! empty( $atts['pymsrc'] ) ) { $pymsrc_output = Pymsrc_Output::get_instance(); $pymsrc_output->add( $pymsrc ); @@ -111,19 +114,19 @@ function pym_shortcode( $atts = array(), $content = '', $tag = '' ) { * @link https://github.com/INN/pym-shortcode/issues/19 * * @param Array $args Has the following indices: - * - 'pym_id' Which Pym instance this is on the page, provided for + * - 'pym_id' Which Pym.js embed instance this is on the page, provided for * informational purposes. In this function, the pym_id value is * used as the variable name in `var pym_id = new pym.Parent(...);` - * - 'actual_id' the element ID used for the Pym container element, + * - 'actual_id' the element ID used for the Pym.js container element, * which is at this point set on the page and not changeable from * this function. This is the first argument for `new pym.Parent()`. - * - 'src' the URL for the Pym child page. This is the second argument + * - 'src' the URL for the Pym.js child page. This is the second argument * for `new pym.Parent()`. * - 'pymoptions' The third argument for `pym.Parent()` See the xdomain * argument in http://blog.apps.npr.org/pym.js/#example-block - * - 'actual_classes' The classes used on the Pym container element, + * - 'actual_classes' The classes used on the Pym.js container element, * provided to this function for informational purposes. - * - 'pymsrc' The URL from which Pym is to be loaded for this emebed, + * - 'pymsrc' The URL from which Pym.js is to be loaded for this emebed, * based on the shortcode/block options and the plugin settings. * * @since 1.3.2.1 diff --git a/js/block.js b/js/block.js index 691fcbc..9e9b1f3 100755 --- a/js/block.js +++ b/js/block.js @@ -49,7 +49,7 @@ * This is the display title for your block, which can be translated with `i18n` functions. * The block inserter will show this name. */ - title: __( 'Pym Embed' ), + title: __( 'Pym.js Embed' ), /** * An icon property should be specified to make it easier to identify a block. @@ -114,10 +114,10 @@ icon: 'analytics' }, ), - __( 'Pym Child URL' ) + __( 'Pym.js Child URL' ) ], value: props.attributes.src, - placeholder: __( 'What is the URL of your Pym child page?' ), + placeholder: __( 'What is the URL of your Pym.js child page?' ), onChange: ( value ) => { props.setAttributes( { src: value } ); }, } ) ), @@ -130,26 +130,26 @@ */ el( InspectorControls, {}, el( TextControl, { - label: __( 'Pym Child URL' ), + label: __( 'Pym.js Child URL' ), value: props.attributes.src, - placeholder: __( 'What is the URL of your Pym child page?' ), + placeholder: __( 'What is the URL of your Pym.js child page?' ), onChange: ( value ) => { props.setAttributes( { src: value } ); }, } ), ), el( InspectorAdvancedControls, {}, el( TextControl, { - label: __( 'Parent element ID (optional)' ), + label: __( 'Parent Element ID (optional)' ), value: props.attributes.id, onChange: ( value ) => { props.setAttributes( { id: value } ); }, - help: __( 'The Pym block will automatically generate an ID for the parent element and use that to initiate the Pym embed. If your child page\'s code requires its parent to have a specific element ID, set that here.' ), + help: __( 'The Pym.js block will automatically generate an ID for the parent element and use that to initiate the Pym.js embed. If your child page\'s code requires its parent to have a specific element ID, set that here.' ), } ), el( TextControl, { - label: __( 'Pym.js source URL (optional)' ), + label: __( 'Pym.js Source URL (optional)' ), value: props.attributes.pymsrc, onChange: ( value ) => { props.setAttributes( { pymsrc: value } ); }, } ), el( TextControl, { - label: __( 'Pym Options' ), + label: __( 'Pym.js Options' ), value: props.attributes.pymoptions, onChange: ( value ) => { props.setAttributes( { pymoptions: value } ); }, // @todo make this translatable https://github.com/WordPress/gutenberg/blob/master/packages/i18n/README.md diff --git a/readme.txt b/readme.txt index d6656cd..b0776d4 100644 --- a/readme.txt +++ b/readme.txt @@ -32,17 +32,17 @@ Embeddable table from NPR: ![an embeddable table from NPR](img/responsive-iframe-npr.png) -Pym Shortcode in a WordPress post: +Pym.js Shortcode in a WordPress post: -![Pym Shortcode in a WordPress post](img/pym-shortcode-in-post.png) +![Pym.js Shortcode in a WordPress post](img/pym-shortcode-in-post.png) -Desktop view of the WordPress post with the NPR embed using Pym Shortcode: +Desktop view of the WordPress post with the NPR embed using Pym.js Shortcode: -![Desktop view of the WordPress post with the NPR embed using Pym Shortcode](img/pym-example-desktop.png) +![Desktop view of the WordPress post with the NPR embed using Pym.js Shortcode](img/pym-example-desktop.png) -Mobile view of the WordPress post with the NPR embed using Pym Shortcode: +Mobile view of the WordPress post with the NPR embed using Pym.js Shortcode: -![Mobile view of the WordPress post with the NPR embed using Pym Shortcode](img/pym-example-phone.png) +![Mobile view of the WordPress post with the NPR embed using Pym.js Shortcode](img/pym-example-phone.png) == Changelog == @@ -54,10 +54,8 @@ Following the practice begun at plugin version 1.1.2 of [having the plugin versi New features: -Adds Gutenberg support. - * Plugin renamed from "Pym Shortcode" to "Pym.js Embeds". -* Adds a "Pym Embed" block for use in Gutenberg. [PR #34](https://github.com/INN/pym-shortcode/pull/34) for issue [#28](https://github.com/INN/pym-shortcode/issues/28). +* Adds a "Pym.js Embed" block for use in Gutenberg. [PR #34](https://github.com/INN/pym-shortcode/pull/34) for issue [#28](https://github.com/INN/pym-shortcode/issues/28). * If a block is created using this plugin and Gutenberg, and Gutenberg is then disabled, the block will show a link to the embedded graphic. * Through the settings page, you can now serve pym.js using your newsroom's CDN or NPR's CDN! [PR #45]() for [issue #31](https://github.com/INN/pym-shortcode/issues/31). * Adds a settings page, available to those with the `manage_options` capability, with the following options: @@ -80,7 +78,7 @@ Changes: = 1.3.2 = -* *RECOMMENDED UPDATE* : Pym users, NPR has released an update that closes a potential security hole. We recommend everyone update to 1.3.2. +* *RECOMMENDED UPDATE* : Pym.js users, NPR has released an update that closes a potential security hole. We recommend everyone update to 1.3.2. * Update to pym.js version 1.3.2: https://github.com/nprapps/pym.js/releases/tag/v1.3.2 (Changelog at https://github.com/nprapps/pym.js/blob/v1.3.2/CHANGELOG) = 1.3.1 = @@ -121,11 +119,7 @@ Changes: * First release of the plugin -== Upgrade Notice == - -No updates at this time. - -== Pym Resources from NPR == +== Pym.js Resources from NPR == You may also want to look at NPR's Pym.js resources: