Editorial flow for Explanations

[DrewAPicture]

In devising a plan for migration of information from function, hook, and class reference pages from the Codex, it became immediately apparently that we would need some mechanism to handle the content that will make up the "Explanation" section of any given reference article.

Several weeks ago, @coffee2code and I devised an editorial workflow that hoped to accomplish several goals. Those are realized in the attached patch and described below:

• Store Explanations as a separate post type

After going back and forth quite a bit about what we'd like to be able to do with Explanations, we decided that storing them in a separate post type was the way to go. With that, we get:

• Revisions independent of the reference post
• Publishing status independent of the reference post
• More fine-grained control over permissions.

• Create an interface within the reference post type editing screen

In light of making the editorial flow for Explanations separate, the goal of the UI in the reference post editing screen was to make a quickly-grokked interface that would include:

• The post status of the explanation
• Last Modified information (if published)
• Links for creating (AJAX), editing, and/or un-publishing (AJAX) depending on the current post status. We chose to omit the ability to blindly publish a drafted explanation.

No explanation exists:

Nonexistent explanations have a status of 'None', and an 'Add Explanation' link is shown. Clicking the link, a draft explanation is created via AJAX with the post_parent set for reference post. The status label updates to 'Drafted', the create link disappears and is replaced with an 'Edit Content' link pointing to the editing screen for the new explanation.

A drafted explanation exists:

Drafted explanations have a status of 'Drafted' (draft) and an 'Edit Content' link is shown. Clicking the link takes you to the editing screen for the explanation. At the top of this screen is information about what reference post the explanation is associated with including a link back to the reference post-editing screen.

An explanation exists and is 'pending review':

Explanations pending review have a status of 'Pending Review', and the workflow is basically the same as with 'Drafted' explanations. The main difference is that this status could be used in concert with a future front-end submission form for reference posts lacking an explanation section. That's Phase II.

A published explanation exists:

Published explanations have a status of 'Published', and 'Edit Content' and 'Un-publish' links are shown. Clicking 'Un-publish' sets the explanation post status to draft via AJAX. The status label updates to 'Draft' and the 'Un-publish' link disappears. Clicking the 'Edit Content' link takes you to the editing screen for that explanation.

Other stuff:

• An explanation must be published to show up on the front-end. Two template tags were introduced in the patch get_explanation() and get_explanation_field().
• The Parsed Content meta box was changed back to using the post content for the description
• parsed-content.js was renamed to admin.js and re-purposed

What's left:

It works, but:

• The AJAX interactions could probably be improved, possibly slowed down with some kind of spinner or visual feedback.
• Though errors are properly sent via the AJAX handlers, there isn't yet any kind of visual feedback for that.

[coffee2code]

In 1057:

developer.wordpress.org: Reintroduce Explanations, with editorial flow.

• Add explanations as an associated post type
• Add metabox to create, unpublish, and link to edit explanation for a parsed post type
• Add template tags: get_explanation() and get_explanation_field()
• Re-enable display of Explanations on the frontend

props DrewAPicture.
fixes #786.