Twenty Fourteen: add in contextual help for setting up Featured Content

[lancewillett]

To help authors use the theme to its full potential, let's add in as much help and tips as we can.

Things like maybe on Posts list screen, add a help screen for how to feature posts and add featured images.

Then, in the Customizer where we have all the FC settings, let's use labels and help text as much as the UI allows.

Two most important items to educate, showcase, and help with are:

1. Featured Content
2. Featured Images

[lancewillett]

It'd be cool to also develop visual tutorials, using images and video, to illustrate how to use the theme to its fullest potential. Maybe linking them in the contextual help, hosted on the Codex or somewhere on WP.org.

[rachelbaker]

Replying to lancewillett:

It'd be cool to also develop visual tutorials, using images and video, to illustrate how to use the theme to its fullest potential. Maybe linking them in the contextual help, hosted on the Codex or somewhere on WP.org.

Also want to be sure to inform users that the background of the Twentyfourteen theme is only displayed on wide-screens, when they are in the Background page. Possibly through use of add_help_tab() to put text in the Help area. related #25869

[lancewillett]

In 26045:

Twenty Fourteen: add brief inline help text for Featured Content controls in Customizer. See #25837.

[lancewillett]

An idea: in the Customizer Featured Content pane, when we mention "featured" posts, link to that exact view: can we link from "featured" tag posts to their posts list?
/wp-admin/edit-tags.php?taxonomy=post_tag&post_type=post&s=featured

[iamtakashi]

Replying to lancewillett:

An idea: in the Customizer Featured Content pane, when we mention "featured" posts, link to that exact view: can we link from "featured" tag posts to their posts list?
/wp-admin/edit-tags.php?taxonomy=post_tag&post_type=post&s=featured

I like the idea. Did you mean here?
/wp-admin/edit.php?tag=featured

[lancewillett]

Replying to iamtakashi:

Replying to lancewillett:

I like the idea. Did you mean here?
/wp-admin/edit.php?tag=featured

Yes, much better. :) Thank you.

[iamtakashi]

Just noting so that we don't forget. We probably should mention the maximum number of featured contents is six.

[lancewillett]

In 26092:

Twenty Fourteen: update the theme description with more information about theme features such as Featured Content and how to set it up. See #25837.

[lancewillett]

In 26101:

Twenty Fourteen: add in more contextual help for setting up Featured Content, links to "featured" tag posts and "sticky" posts from inside the Customizer. See #25837.

[taupecat]

I'm looking into editing the content in the welcome panel, but can only find two ways of customizing it:

1) Replace the text that's currently in the welcome panel via jQuery.

or

2) Disable the welcome panel via an action hook and build a new one to include via an action hook.

Either solution seems rather extreme. Suggestions?

[lancewillett]

Replying to taupecat:

I'm looking into editing the content in the welcome panel, but can only find two ways of customizing it:
2) Disable the welcome panel via an action hook and build a new one to include via an action hook.

I agree it's a bit extreme to remove the default completely with the welcome_panel action, and with the big "Customize" link right there in the default Welcome screen, that'd be enough to get a new author into the Customizer and they'd discover Featured Content there.

A few ideas:

1. Maybe with JavaScript change out the "More Actions" links to point to Featured Content and Featured Images setup? We'd need to make a Codex page for both (or point to existing).
2. Could we add a Welcome-style screen to another admin page, like themes.php? I'm not sure how difficult that would be. If Twenty Fourteen is the active theme, show a message above the theme grid with specific instructions for Twenty Fourteen? Maybe dismissable and just one or two links (also to the Codex).

[lancewillett]

Tracking an idea celloexpressions mentioned, would be be allowed HTML in the theme description? To add in URLs to point to key editing pages. If not in style.css, maybe with a custom function override the description shown in themes.php to add in URLs.

[lancewillett]

For "Help" tab content, I think we should look at adding at least a line or URL or two to the following:

1. Appearance > Themes: wp-admin/themes.php
2. Edit Posts: wp-admin/edit.php

In there, mentioning the key things we mention in the Customizer pane:

• Easily feature all posts with the "featured" tag [link in-admin] or a tag of your choice; if no posts match the tag, "sticky" posts [link in-admin] will be displayed instead.
• Enhance your design with Featured Images [link to how-to article]

[lancewillett]

In 26135:

Twenty Fourteen: use numbered placeholders for Customizer help text in case they get swapped during translation, props obenland. See #25837.

[nacin]

There is not a dedicated hook for adding help tabs, but admin_head-$page would be most preferred.

[lancewillett]

Working from obenland's .1 patch, proper actions and better title and text

[lancewillett]

In 26153:

Twenty Fourteen: first pass at adding help text to to "Help" tab for edit.php and themes.php screens. Props obenland for starter patch, see #25837.

[obenland]

Having it hooked into 'admin_head-edit.php' will also add it in the page list and any custom post type, as far as I can tell without testing (Mavericks mangled my sandbox). Intentionally?

We could check $typenow to avoid this, like in my original patch.

[lancewillett]

Intentional for pages, but not post types. I'm open to changing it to just "post" post type.

[dimadin]

For translators comments like in [26153] we're using /* translators: */ block, not context (e.g. ​http://core.trac.wordpress.org/browser/trunk/src/wp-admin/includes/media.php?rev=25727#L237). In this examples I don't actually see need for any translators comments.

[lancewillett]

Replying to dimadin:

For translators comments like in [26153] we're using /* translators: */ block, not context (e.g. ​http://core.trac.wordpress.org/browser/trunk/src/wp-admin/includes/media.php?rev=25727#L237). In this examples I don't actually see need for any translators comments.

Hmm, good point on not really needed here.

[lancewillett]

In 26190:

Twenty Fourteen: remove unneeded translator context from theme Help tab text, props domain. See #25837.

[lancewillett]

Still pending for this to be complete (see notes above):

1. Welcome Screen additions
2. Filtering stylesheet "description" field in themes.php -- maybe via a filter
3. Limit Help tab to only "post" post type edit screen

[dd32]

[26153] <a href="%2$s">Appearance > Customize</a>

That middle > will need to be changed or encoded since it's a reserved character in HTML.

[lancewillett]

In 26211:

Twenty Fourteen: use HTML entity for arrow in Help text string, props dd32. See #25837.

[lancewillett]

Replying to lancewillett:

In 26190:

Twenty Fourteen: remove unneeded translator context from theme Help tab text, props domain. See #25837.

Sorry, dimadin -- your props got missed (my fault, typo).

[lancewillett]

For welcome screen, here's some sample code in case it's a starting point: ​https://gist.github.com/lancewillett/7491863

[lancewillett]

Replying to lancewillett:

Still pending for this to be complete (see notes above):

2. Filtering stylesheet "description" field in themes.php -- maybe via a filter

Chatted with Matías and Nacin in IRC (​see log), it's a no-go since there are no filters on purpose for exposing the stylesheet data.

[lancewillett]

Another idea is to add an activation message. After the theme is activated, show a short note on how the theme works and point to a longer explanation / tutorial to get it set up with Featured Content.

[siobhan]

Updating theme description

[siobhan]

Updates customizer text

[lancewillett]

In 26360:

Twenty Fourteen: update theme description to be less instructional and more promotional. Pushing the how-to to the Codex and other documentation. Props siobhan, see #25837.

[lancewillett]

In 26361:

Twenty Fourteen: update Customizer inline help text. Props siobhan, see #25837.

[siobhan]

Updates help text

[lancewillett]

Still needs patches. :)

1. Limit Help tab to only "post" post type edit screen
2. Welcome Screen additions.

[chipbennett]

Replying to lancewillett:

Still needs patches. :)

1. Limit Help tab to only "post" post type edit screen
2. Welcome Screen additions.

That first one should be a pretty easy fix; I'll take a look tomorrow.

[Hanni]

Looks like the help text for Twenty Fourteen on the Themes page is in <li> tags, which aren't quite styled in same way as other help text wrapped in p tags (the li text i s larger).

[SergeyBiryukov]

Replying to Hanni:

Looks like the help text for Twenty Fourteen on the Themes page is in <li> tags, which aren't quite styled in same way as other help text wrapped in p tags (the li text i s larger).

Related: #26300

[obenland]

Limits Help tab to only "post" post type edit screen

[lancewillett]

In 26555:

Twenty Fourteen: limit Help tab text to only "post" post type edit screen. Props obenland, see #25837.

[lancewillett]

Going to forgo the Welcome Screen changes; we can look again at that in a future release.

[lancewillett]

In 26556:

Twenty Fourteen: update comment blocks to match inline docs standards. Props DrewAPicture, see #25837.

[lancewillett]

Thanks to @siobhan we now have a Codex page for explaining how Twenty Fourteen works: ​http://codex.wordpress.org/Twenty_Fourteen

Rather than littering lots of text in the theme comments or contextual help, we can put all the longer explanations there and point to it.

[lancewillett]

In 26630:

Twenty Fourteen: add link to Codex documentation in Help text, and minor cleanup based on siobhan feedback. See #25837.