Options page and settings

docs/updating-pym.md → docs/maintainer-notes.md

@@ -1,4 +1,6 @@
-## Notes for Plugin maintainers
+# Notes for Plugin maintainers
+
+### Updating Pym.js
 
 `js/pym.v1.min.js` in this plugin should be kept up-to-date with the current version of https://pym.nprapps.org/pym.v1.min.js.
 
@@ -10,3 +12,18 @@ To update:
 - update this plugin's version number to the `Pym.js` version number
 
 NPR Visuals Team's [stated intention](https://github.com/nprapps/pym.js/tree/master#versioning) is that versions of `Pym.js` will be backwards-compatible for `0.x` and `0.0.x` releases, so we can copy those in directly. When a `x.0.0` release comes around, we'll need to figure out a plan for that. See discussion in https://github.com/INN/pym-shortcode/issues/12
+
+### Updating the plugin
+
+The plugin's `A.B.C` version number should match the version number of the bundled copy of `Pym.js`. We started doing this in plugin release 1.1.2.
+
+The plugin's [version history](https://github.com/INN/pym-shortcode/releases) looks like this:
+
+- 0.1: initial release
+- 1.1.2
+- 1.2.0
+- 1.2.0.1: a fix in this plugin
+- 1.2.0.2: a fix in this plugin
+- 1.3.1
+- 1.3.2
+- 1.3.2.1: Gutenberg and settings page

docs/readme.md

@@ -7,13 +7,14 @@ Contents:
 1. [Plugin Installation](#plugin-installation)
 2. [The Pym Shortcode](#the-pym-shortcode)
 3. [The Pym Block](#the-pym-block)
-4. [Options](#options)
-	1. [src: the only required argument](#src-the-child-url)
-	2. pymsrc
-	3. pymoptions
-	4. class
-	5. align
-	6. id
+4. [Embed Options](#embed-options)
+	1. [src: the only required argument](#src-the-child-url-required-argument)
+	2. [pymsrc](#pymsrc-the-url-for-pymjs)
+	3. [pymoptions](#pymoptions-settings-for-pym)
+	4. [class](#class-to-add-html-classes-to-the-pym-parent-element)
+	5. [align](#align-for-wordpress-alignment-support)
+	6. [id](#id-to-set-the-pym-parent-elements-id)
+5. [Plugin Options](#plugin-options)
 5. [Frequently Asked Questions](#frequently-asked-questions)
 	1. [Why would I want to use Pym in the first place?](#why-would-i-want-to-use-pym-in-the-first-place)
 	2. [Why is a WordPress plugin needed to use Pym.js?](#why-is-a-wordpress-plugin-needed-to-use-pymjs)
@@ -53,7 +54,7 @@ Example in a post:
 
 For the block, all options available via shortcode arguments are available through the block's advanced options panel.
 
-## Options
+## Embed Options
 
 ```
 [pym src="" pymsrc="" pymoptions="" class="" align="" id="" ]
@@ -102,7 +103,9 @@ To do the same thing with this Pym shortcode, you would write:
 For example, the shortcode `[pym src="https://blog.apps.npr.org/pym.js/examples/table/child.html" class="one two three four float-left mw_50"]` results in the following output:
 
 ```html
-<div id="pym_0" class="pym one two three four float-left mw_50"></div><script src="http://example.org/wp-content/plugins/pym-shortcode/js/pym.v1.min.js"></script><script>var pym_0 = new pym.Parent('pym_0', 'https://blog.apps.npr.org/pym.js/examples/table/child.html', {})</script>
+<div id="pym_0" class="pym one two three four float-left mw_50"></div>
+...
+<script>var pym_0 = new pym.Parent('pym_0', 'https://blog.apps.npr.org/pym.js/examples/table/child.html', {})</script>
 ```
 
 If you do not want the class `'pym'` output on container elements, [add a filter](https://codex.wordpress.org/Plugin_API/Filter_Reference) to the hook `pym_shortcode_default_class` that returns an empty string.
@@ -122,9 +125,35 @@ In the Gutenberg editor, the alignment options are provided by the alignment con
 For example, the shortcode `[pym src="https://blog.apps.npr.org/pym.js/examples/table/child.html" id="extremely_specific_id"]` results in the following output:
 
 ```html
-<div id="extremely_specific_id" class="pym"></div><script src="http://example.org/wp-content/plugins/pym-shortcode/js/pym.v1.min.js"></script><script>var pym_0 = new pym.Parent('extremely_specific_example', 'https://blog.apps.npr.org/pym.js/examples/table/child.html', {})</script>
+<div id="extremely_specific_id" class="pym">
+...
+<script>var pym_0 = new pym.Parent('extremely_specific_example', 'https://blog.apps.npr.org/pym.js/examples/table/child.html', {})</script>
 ```
 
+## Plugin Options
+
+The Pym.js Embed Settings page can be found under WordPress' "Settings" menu.
+
+The settings page provides two options: the default pymsrc and the option to override all pymsrc arguments.
+
+We **strongly recommend** that you set the default pymsrc to `https://pym.nprapps.org/pym.v1.min.js` and check the box to enable the pymsrc override.
+
+### Default pymsrc
+
+As explained in the documentation for [the pymsrc embed option](#pymsrc-the-url-for-pymjs), the default copy of `Pym.js` used by this plugin is the copy bundled with this plugin. NPR recommends, and we recommend, that you use the copy of `Pym.js` provided by NPR's CDN. However, this plugin cannot force you to do so; the WordPress.org plugin guidelines generally [prohibit plugin use of third-party scripts without user consent](https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/#7-plugins-may-not-track-users-without-their-consent), and frown upon plugins that use CDNs by default. Therefore, we give you the option to use NPR's CDN, or your nwesroom's CDN, and ship the plugin in a state that defaults to no CDN.
+
+Shortcodes and blocks have the the option to specify an alternate source for `Pym.js` at a per-embed level, which allows you to opt into using the CDN version of the script on a per-embed level. This is less than optimal; every time you create a `Pym.js` embed on your site, you will need to check that the pymsrc option is set.
+
+To save time and effort, set the "Default pymsrc" option in the plugin settings to NPR's CDN copy of `Pym.js`: `https://pym.nprapps.org/pym.v1.min.js`
+
+### Override pymsrc
+
+Anyone who can edit a post can set the pymsrc URL on a shortcode or a block, and the pymsrc URL can be *any* resource. Browsers will try to load it as JavaScript, even if the set URL is for an image, a 404 page, or a non-`Pym.js` library. This is not good.
+
+We **strongly recommend** that you check this box, to force all `Pym.js` Embed shortcodes and blocks to use the plugin's default pymsrc.
+
+This box is not checked by default, because defaulting to overriding the pymsrc URL would potentially break existing shortcodes on sites that used this plugin before release version 1.3.2.1. If you used this plugin to create `[pym]` shortcodes before release 1.3.2.1, and wish to test your embeds before enabling the override, read [this testing advice](./upgrade-testing.md).
+
 ## Frequently Asked Questions
 
 ### Why would I want to use Pym in the first place?
@@ -153,13 +182,15 @@ Assuming that you have installed this plugin via the wordpress.org plugin reposi
 
 You can check the validity of that assumption by putting a shortcode or block in a post, then viewing the post from the frontend. In the source code of the page, you should see a script tag loading `pym.v1.min.js`. 
 
+The URL can also be found on the "Pym Plugin Info" page, found under the "Tools" menu in your site's admin dashboard.
+
 Or, you can specify the URL from which to load `Pym.js`.
 
 ### What is the difference between `Pym.js` and `pym.v1.min.js`?
 
 In this document, `Pym.js` is used to refer to the JavaScript library.
 
-`pym.v1.min.js` is a specific copy of that library, hosted on your server at a given URL. It's named following [NPR's `Pym.js` versioning strategy](https://github.com/nprapps/pym.js/tree/master#versioning). It is kept up to date with the CDN version of the library by this plugin's maintainers, [following these instructions](https://github.com/INN/pym-shortcode/blob/master/docs/updating-pym.md).
+`pym.v1.min.js` is a specific copy of that library, hosted on your server at a given URL. It's named following [NPR's `Pym.js` versioning strategy](https://github.com/nprapps/pym.js/tree/master#versioning). It is kept up to date with the CDN version of the library by this plugin's maintainers, [following these instructions](https://github.com/INN/pym-shortcode/blob/master/docs/maintainer-notes.md).
 
 The CDN version of `Pym.js` is at https://pym.nprapps.org/pym.v1.min.js .
 

docs/upgrade-testing.md

@@ -0,0 +1,87 @@
+# Testing advice for upgrading the plugin
+
+We recommend that you perform testing in a copy of your production environment, such as a staging or development server, or a local development environment. You should try to test with as complete a copy as possible, to include themes, plugins, and a copy of the database.
+
+If your live site uses an HTTPS certificate, your testing environment should use an HTTPS certificate. Talk to your hosting provider or consult your local development environment's docs for information about enabling HTTPS.
+
+## Finding posts that use the `[pym]` shortcode
+
+### site search
+
+Depending on what search engine is enabled on your site, you may be able to find pymsrc posts using the search function: `example.org/?s=pymsrc`
+
+### wp-cli
+
+If you have [wp-cli](https://wp-cli.org/) installed in your environment, you can get a list of posts using the `[pym]` shortcode by running a search using [wp post list](https://developer.wordpress.org/cli/commands/post/list/):
+
+```
+wp post list --s='[pym'
+```
+Your terminal should return a list of posts and their IDs:
+
+```
++----+------------------------------------------+-------------------+---------------------+-------------+
+| ID | post_title                               | post_name         | post_date           | post_status |
++----+------------------------------------------+-------------------+---------------------+-------------+
+| 5  | Pym Example: multiple tables and pymsrcs | pym-example-table | 2018-08-22 20:44:23 | publish     |
++----+------------------------------------------+-------------------+---------------------+-------------+
+```
+
+To find posts containing shortcode or blocks with a custom pymsrc set:
+
+```
+$ wp post list --s='pymsrc'
++----+------------------------------------------+------------------------+---------------------+-------------+
+| ID | post_title                               | post_name              | post_date           | post_status |
++----+------------------------------------------+------------------------+---------------------+-------------+
+| 5  | Pym Example: multiple tables and pymsrcs | pym-example-table      | 2018-08-22 20:44:23 | publish     |
+| 10 | Single pym child block                   | single-pym-child-block | 2018-08-29 22:52:19 | publish     |
++----+------------------------------------------+------------------------+---------------------+-------------+
+```
+
+You can change the formatting of the list and the information it contains for each post using the arguments of [wp post list](https://developer.wordpress.org/cli/commands/post/list/).
+
+As an example, here's how to use `wp post list`, on a [local Valet development install running on a Mac](https://github.com/INN/docs/blob/master/projects/largo/site-setup-valet.md), to open in your default web browser every single post containing a pymsrc setting:
+
+```
+wp post list --s='pymsrc' --format=ids | tr "[:space:]" "\n" | xargs -I % open http://pym-shortcode.test/?p=%
+```
+
+This opened two tabs: one each for post `5` and `10`. Use this with caution if you have a lot of stories with `Pym.js` embeds; you might crash your web browser.
+
+## Testing the pymsrc override
+
+1. Enable the override option in **Settings > Pym.js Embeds Settings > Override pymsrc**
+2. Find all posts using the pymsrc option in a shortcode or block, using one of the methods above.
+3. For a representative sample of posts, or for all posts if you can, open each post in a browser.
+	1. Does the embed load correctly?
+	2. Open the browser console. Are there any notices, warnings, or errors?
+	3. 
+
+You may want to take the time to edit your embedded pages so that they all use the NPR CDN version of `Pym.js`, or use your newsroom's CDN version of `Pym.js`. You should be using [the most-recent version of `Pym.js`](http://blog.apps.npr.org/pym.js/) in any case.
+
+## Testing embed alignment
+
+Version 1.3.2.1 of this plugin introduced [support for WordPress' alignment CSS classes](./readme.md#align-for-wordpress-alignment-support).
+
+For advice on styling the alignment classes, see [the Gutenberg docs](https://wordpress.org/gutenberg/handbook/extensibility/theme-support/#wide-alignments-and-floats).
+
+### Shortcode testing
+
+Test your theme's alignment CSS classes with the following shortcodes:
+
+```
+[pym src="https://blog.apps.npr.org/pym.js/examples/table/child.html" align=""]
+[pym src="https://blog.apps.npr.org/pym.js/examples/table/child.html" align="none"]
+[pym src="https://blog.apps.npr.org/pym.js/examples/table/child.html" align="left"]
+[pym src="https://blog.apps.npr.org/pym.js/examples/table/child.html" align="center"]
+[pym src="https://blog.apps.npr.org/pym.js/examples/table/child.html" align="right"]
+[pym src="https://blog.apps.npr.org/pym.js/examples/table/child.html" align="wide"]
+[pym src="https://blog.apps.npr.org/pym.js/examples/table/child.html" align="full"]
+```
+
+You'll want to check that the embeds are positioned correctly on the page in all browsers that you support and at all viewport widths.
+
+### Block testing
+
+Test your theme's alignment CSS by creating blocks with each alignment option. Your theme may need to [declare wide alignment](https://wordpress.org/gutenberg/handbook/extensibility/theme-support/#wide-alignment) in order to see the "wide" and "full" options.

inc/info-page.php

@@ -0,0 +1,54 @@
+<?php
+/**
+ * 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.
+ */
+
+namespace INN\PymEmbeds\Info;
+
+/**
+ * Create the option page
+ *
+ * @since 1.3.2.1
+ */
+function register_options_page() {
+	add_submenu_page(
+		'tools.php',
+		__( 'Pym.js Embeds Plugin Information', 'pym-shortcode' ), // title of page
+		__( 'Pym.js Embeds Info', 'pym-shortcode' ), // menu text
+		'edit_posts', // capability required
+		'pym-embeds-info', // menu slug
+		__NAMESPACE__ . '\options_page_callback' // callback for options page display
+	);
+}
+add_action( 'admin_menu', __NAMESPACE__ . '\register_options_page' );
+
+/**
+ * Options page display callback
+ *
+ * @since 1.3.2.1
+ * @link https://developer.wordpress.org/plugins/settings/custom-settings-page/
+ */
+function options_page_callback() {
+	printf(
+		'<h1>%1$s</h1>',
+		esc_html( get_admin_page_title() )
+	);
+
+	printf(
+		'<p>%1$s</p>',
+		wp_kses_post( __( 'For information on how to use the block and shortcode provided by the Pym.js Embeds plugin, read the plugin\'s documentation <a href="https://github.com/INN/pym-shortcode/tree/master/docs">on GitHub</a>.', 'pym-shortcode' ) )
+	);
+
+	printf(
+		'<label for="local_url">%1$s</label>',
+		esc_html__( 'The URL for the copy of Pym.js hosted on this site is:', 'pym-shortcode' )
+	);
+
+	// copying how qz.com does their share links
+	printf(
+		'<input id="local_url" type="text" readonly value="%1$s" style="clear:both; width: 100%%; display: block;"/>',
+		esc_attr( pym_pymsrc_local_url() )
+	);
+}