documentcloud / wordpress-documentcloud

Embed DocumentCloud documents that won't be eaten by the visual editor
https://wordpress.org/plugins/documentcloud/
GNU General Public License v2.0
9 stars 14 forks source link

DocumentCloud WordPress plugin

The DocumentCloud WordPress plugin lets you embed DocumentCloud resources into WordPress content using shortcodes.

[documentcloud url="https://www.documentcloud.org/documents/282753-lefler-thesis.html"]

Installation

  1. Upload the contents of the plugin to wp-content/plugins/documentcloud
  2. Activate the plugin through the "Plugins" menu
  3. In your posts, embed documents, pages, or notes using the DocumentCloud button or the [documentcloud] shortcode
  4. Optional: Set a default width/height for all DocumentCloud embeds (which can be overridden on a per-embed basis with the height/width attributes) at Settings > DocumentCloud. (This default width will only be used if you set responsive="false" on an embed.)

Upgrading from Navis DocumentCloud: If you're currently using the Navis DocumentCloud plugin (from which this plugin was built), you'll want to deactivate or delete it before installing this plugin.

Usage

This plugin allows you to embed DocumentCloud resources using either the raw URL on its own line:

Here's something you should really take a look at:

https://www.documentcloud.org/documents/282753-lefler-thesis.html

Isn't that interesting?

Or a custom shortcode:

[documentcloud url="https://www.documentcloud.org/documents/282753-lefler-thesis.html"]

When you save, WordPress fetches and stores the actual embed code HTML from the DocumentCloud servers using oEmbed. You can freely toggle between visual and HTML mode without mangling embed code, and your embed will always be up to date with the latest embed code.

By default, documents will have a responsive width (it will narrow and widen as necessary to fill available content area) and use the theme's default height. If you want to override this, you can either set responsive="false" or explicitly set a width:

[documentcloud url="https://www.documentcloud.org/documents/282753-lefler-thesis.html" width="600"]

You can set your own defaults in Settings > DocumentCloud, but default widths will be ignored unless responsive is disabled:

[documentcloud url="https://www.documentcloud.org/documents/282753-lefler-thesis.html" responsive="false"]

To embed a single page, use any page-specific URL. Pages ignore width/height and always act responsively:

[documentcloud url="https://www.documentcloud.org/documents/282753-lefler-thesis.html#document/p1"]

To embed a note, use any note-specific URL. Notes ignore width/height and always act responsively:

[documentcloud url="https://www.documentcloud.org/documents/282753-lefler-thesis.html#document/p1/a53674"]

Here's the full list of embed options you can pass via shortcode attributes; some are specific to the type of resource you're embedding.

All resources:

Documents only:

You can read more about publishing and embedding DocumentCloud resources on https://www.documentcloud.org/help/publishing.

How the oEmbed endpoint is discovered

To make a resource discoverable by oEmbed consumers, you can include a <link> tag that specifies the oEmbed endpoint URL. So in one version of reality, once you tell WordPress "this resource is oEmbeddable", WordPress would cURL the resource URL, look for the oEmbed link tag in its header, pluck out the oEmbed endpoint from the <link> tag's href, and then hit that endpoint for the embed code. In our actual reality, that's considered a waste of a cURL, so we have to actually describe the format of our oEmbed endpoint within WordPress itself.

Caching

Ideally, when WordPress hits our oEmbed service to fetch the embed code, it would obey the cache_age we return. Despite conversation around this, it doesn't seem to.

Instead, it lets us choose between no cache at all (so every pageload triggers a call to our oEmbed service to get the embed code) or a supposed 24-hour cache stored in the postmeta table. Unfortunately, our tests seem to show this cache is never expired, which means we can choose between no cache (thus possibly DDOSing ourselves) or a permanent cache (thus possibly having stale embed codes). We've chosen the latter; hopefully this cache does eventually expire, and our embed codes shouldn't change that often anyway.

If you find yourself absolutely needing to expire the cache, though, you have two choices:

  1. Delete the appropriate _oembed_* rows from your postmeta table.
  2. Modify the shortcode attributes for the embed, since this is recognized as a new embed by WordPress.

Changelog

0.4.3

0.4.2

0.4.1

0.4.0

0.3.3

0.3.2

0.3.1

0.3

0.2

0.1

License and History

The DocumentCloud WordPress plugin is GPLv2. Initial development of this plugin by Chris Amico (@eyeseast) supported by NPR as part of the StateImpact project. Development continued by Justin Reese (@reefdog) at DocumentCloud.