Use oEmbed

[Justin Reese]

We're adding an oEmbed service to DocumentCloud, so I'll be adapting this plugin to take advantage of it. The syntax of the shortcodes won't change, so it'll be backwards-compatible.

Goals:

1. Fetch the embed code from our oEmbed service, natch
2. Support existing [documentcloud] shortcodes for documents, but prefer [dc-document] going forward to distinguish among target resources; option syntax remains the same
3. Add new shortcodes support for other resources: notes (#4), collections/searches (#3), and (eventually) pages
4. Add support for recognizing resource URLs on their own line, as described here; if #15 were accomplished, then this would only be enabled for versions of WP prior to that
5. Use this implementation as a meta guide for future plugin authors

Edited: Abandoned design of separate shortcodes for different resources. Going to instead parse URL and determine resource type from there.

[Justin Reese]

@eyeseast While building this, I ran into the documents and wide_assets post metadata you're saving on save(). Can't figure out what these are used for, though. Help?

[Chris Amico]

Hey @reefdog, @knowtheory can we talk about this at some point? Sounds like you guys are taking this plugin in a new direction and I'm feeling a little out of the loop. Should bring in @aschweigert, too, since INN has been recommending this plugin in Largo.

[Chris Amico]

@reefdog: To your question about wide assets, that was something we did in a lot of the @argoproject / @stateimpact plugins. The basic idea was that plugin could set a post meta variable saying that it was meant for a wider post format (like a full-width document) and a theme could deal with that. It's meant to be a loose contract, hence settings for normal width and full width.

[Ted Han]

@eyeseast Definitely! Would you prefer to jump on the phone or would posting here be suitable?

[Chris Amico]

Thanks. Posting here is great. I'm on the road this week, which is putting me further behind.

[Justin Reese]

Let's definitely chat, I feel a bit sheepish. I'm new to DocumentCloud, and while Ted gave me some ancestry on the plugin, I had it in my head that we'd already taken over maintenance and I let myself come in like a wrecking ball. Should've kept you guys in the loop much better, mea culpa!

[Chris Amico]

Totally ok. I'm happy to see work being done on this. The sudden flurry of activity just caught me by surprise. I'm back to work in just over a week.

[Ted Han]

@reefdog i wouldn't sweat it, the responsibility for this one is all on me.

So our general disposition is this (all of this is open for discussion, this is just describing where our heads are at):

Any changes we're making to the plugin should be 100% backwards compatible from a user POV, and any forward changes should add functionality (in this case adding notes and searches). The only additional change we've made thus far is to allow the pasting of document URLs directly in and having them create a default embedding (which we can/should make as sensible as possible).

If one wants to configure any documentcloud related embed code they should use shortcodes.

IMO it'd be nice to be able to use a single [documentcloud] shortcode, and use that as a kind of polymorphic interface based on the type of resource it's been passed (although happy to discuss the pros & cons of that).

From the POV of the internals, our main goal in using the plugin as an oEmbed consumer were to 1) give us a test consumer for the DocumentCloud API, and 2) extract the logic for constructing embed codes out into one location (our API), so that in the event that the structure of our embeds change, the logic for that only needs to be rewritten in the API rather than both in the API and here in the plugin.

@eyeseast: We've got what we need at the moment to test the API, but ultimately it'd be nice to be able to announce the oEmbed endpoint plus an update to the wordpress plugin together. We're happy to hold off for now until we discuss further (esp since we'll want to get this into the plugin repo before doing an announcement). That work for you? :)

cc/ @aschweigert same goes for you! Interested in your opinions :)

[Justin Reese]

Status of the oembed branch:

• Raw URLs and [documentcloud] shortcodes both generate embeds using oEmbed
• Previous shortcode attributes supported and defaults respected
• New attributes added for remaining embed options (container, notes, responsive, etc.)
• save() function minimally modified (just for compatibility with name changes)
• get_defaults() and embed_shortcode() left for examination, but replaced with get_default_atts() and handle_dc_shortcode()

I want oEmbed to drop in seamlessly without disrupting existing users. If any of you regular users have time to update to the latest version from the oembed branch and see if anything breaks, I'd be grateful.

[Chris Amico]

I think we can close this now that #21 is merged. Thanks for all your hard work on this @reefdog and @knowtheory.

[Justin Reese]

For sure, thanks for all your patience as we hammered this out!

[Ted Han]

@eyeseast thanks to you & @aschweigert for your guidance! :)

[Anthony DeBarros]

+1!