Change the display layout of help tabs

[jane]

In-admin help is cool. But! There's so much of it! All that scrolling and a mountain of long-line-length rows that are hard to read (let alone scan) on complex screens makes it much less effective than it should be. Let's redesign the inside of the help layers. Break each screen's help content into smaller bits (Overview, Display, Actions, whatever is applicable per screen) and have those labels on left, readable line-length content in the middle, and the more info links on the right. See attached sketch.

Koop will set it up if no one beats him to it, but it would be awesome if someone beat him to it, because he's working on the new user and new feature bits. If someone makes the structure today, we can have afternoon hackathon people help make patches to do the content splitting up parts this afternoon.

Sketch of new help layout proposal

+1

I had thought about splitting the content into two columns but this is a better idea.

The help box max-height could do with being increased too, maybe to 300px.

Thinking that would be a good place to split in columns using css3 as it only contains text (and eventually images?). This would make scaling for responsive admin a lot better.

Quick example of how that would look. Of course the columns will be switchable to 2 or 1 depending on screen width.

And what about browsers that don't support CSS3 columns?

@azaozz: I do not want that 3-column text layout. The whole point is less text on screen, more clicky things. :)

Hacked on this @ #wcpdx. Two others were doing:

• content output from add_contextual_help()
• CSS formatting

Tab JS wasn't decided, but I can't work on it tomorrow. Here's my suggested method for common.dev.js. Needs corrected id|classes (from, ​http://www.sohtanaka.com/web-design/simple-tabs-w-css-jquery/):

$(document).ready(function() {

	//When page loads...
	$(".tab_content").hide(); //Hide all content
	$("ul.tabs li:first").addClass("active").show(); //Activate first tab
	$(".tab_content:first").show(); //Show first tab content

	//On Click Event
	$("ul.tabs li").click(function() {

		$("ul.tabs li").removeClass("active"); //Remove any "active" class
		$(this).addClass("active"); //Add "active" class to selected tab
		$(".tab_content").hide(); //Hide all tab content

		var activeTab = $(this).find("a").attr("href"); //Find the href attribute value to identify the active tab + content
		$(activeTab).fadeIn(0); //Show content from active ID, 0=>instant
		return false;
	});

});

Modified .wp-admin/includes/template.php, to output nested divs. TO-WORK REQUIRES: nested array of content from add_contextual_help(), CSS formatting. (!!! Currently outputs debugging content from add_contextual_help(), MUST-REMOVE for production !!!)

Hey #wcpdx guys, I couldn't make it in today to meet with you guys but added some checks to my PHP code from yesterday:

1.) It checks to see if the tab_title is empty, if not it processes the value in the array. If not, no output, but it still doesn't check for unique tab_titles.

2.) I added a forced array-output in the add_contextual_help() method. Please remove it once you have valid array-nesting in the doc files.
---

In general, this code always checks if the content is in an array or not (so no need to update all the docs files at-once). If it's a string (like old content) then it outputs in old style. If it's an array then it checks for the keys 'contextual-help-tabs' and 'contextual-help-links' & if they exist then outputs as we discussed yesterday.

Expands on the patch to template.php in 18690.template.php.diff above, and an example of the markup as applied to one admin page (edit-form-advanced.php)

Includes CSS & JS, and @goldenapple's last patch (with one slight markup change)

Couple things to note:

-The height of the help container needs to be declared in fixed units, in two places in the CSS (noteworthy in case the height gets changed in the future, as discussed.)

-Both ul.contextual-help-tabs and div.contextual-help-links have overflow: auto on them in case they go too long. It won't be pretty, but the content will be accessible.

-It still looks good, even if help gets a boring old string, not a fancy new array.

Thanks guys, I had a lot of fun with this.

Working on the text breakdowns with @dougwrites, Koop will be looking over the code.

This is all good, but add_contextual_help() is something I want to deprecate. We've been talking about turning the $current_screen object into a proper WP_Screen class and have methods like add_help_tab(), add_help_link(), and so on.

The gist of WP_Screen

Bring it all together

Add $id arg to add_help_tab()

We briefly discussed making WP_Screen a singleton in IRC. I'm game if anyone wants to have a go.

I like where 18690.2.diff goes and the new functionality and ui layout it implements.

Great improvement on the current help system.

Daryl and I talked about making screen options one of the tabs in the new help layout. Showed the idea to 7 people during testing the last two days, seemed to go over well. Let's try to work this in.

In [18779]:

Introduce help tabs and WP_Screen. props mbijon, goldenapples, natebedortha, ryan. see #18690.

In [18780]:

Use correct variable. see #18690.

In [18782]:

Move WP_Screen and friends (15 functions) into admin/includes/screen.php. see #18690.

I shifted WP_Screen and screen-related cleanup to #18785.

Is it worth considering renaming this to WP_Admin_Screen?

In [18793]:

First pass of WP_Screen phpdoc. see #18690

In [18794]:

Revert fat fingers in [18793]. see #18690

In [18797]:

Add dashboard help tabs, revise help tab layout and code. see #18690.

Screenshot of new help layout styling per MT

In [18853]:

Make screen options a help tab. Move screen option functions into WP_Screen. see #18690, #18785.

In [18854]:

Properly print per-page options. see #18690, [18853].

1. Open Help on Posts screen.
2. Click "Screen Options" tab.
3. Click "Screen Info" tab.
4. There'll be two scrollbars (see the screenshot).

Tested in Firefox 7, Chrome 14.

In [18861]:

Separate the tab title from the help section title, see #18690

In [18862]:

Add phpdoc for the section title, see #18690

In [18864]:

Add screen_options with contextual content, see #18690

In [18866]:

Help style refresh, part 1. A few elements left to add/tweak. see #18690.

In [18867]:

Use add_option() method, introduce add_option_context() method for adding specific text above the screen options, see #18690

In [18874]:

Deprecate favorite_actions(), add_contextual_help(), add_screen_option(), move meta_box_prefs() and get_screen_icon() in WP_Screen, see #18690

Closed #18856 as a duplicate of this. - Plugins page needs to be updated to use $current_screen->add_help_tab()

Replying to azaozz:

In [18867]:

Use add_option() method, introduce add_option_context() method for adding specific text above the screen options, see #18690

function add_option( $option = false, $args ) {

You shouldn't precede an argument that has no default value, with one that has.

Jumping the gun on this, but is there any informal documentation regarding how themes / plugins that add their own admin screens should be making use of WP_Screen?

Replying to dd32:

Yes, most screens will have to be converted to using WP_Screen, we will do that while revising the help text.

Replying to GaryJ:

You shouldn't precede an argument that has no default value, with one that has.

Was 50/50 whether to swap the order of args or make the first one optional. Currently $current_screen->add_option() is used for both the built-in options (screen layout, table columns, etc.) and for the HTML for custom options. The first requires option_mane and an array, the second is just the HTML string.

Alternatively we could split the method into two: $current_screen->add_default_option($name, $settings) and $current_screen->add_custom_option($html).

Replying to GaryJ:

Not much documentation yet since it's still in development. The idea is to use add_action('add_screen_help_and_options', '...'); and then $current_screen->add_help_tab() and/or $current_screen->add_option().

Replying to azaozz:

Alternatively we could split the method into two: $current_screen->add_default_option($name, $settings) and $current_screen->add_custom_option($html).

That would be my preference, since they are then more self-documenting via the method and argument names.

How about just keeping the first method as add_option() (since I suspect this would be used for more often to tweak one of the existing options, than adding a whole new option)?

Replying to azaozz:

Replying to GaryJ:

Not much documentation yet since it's still in development. The idea is to use add_action('add_screen_help_and_options', '...'); and then $current_screen->add_help_tab() and/or $current_screen->add_option().

Thanks. So, in summary, it's just for dealing with all the fluffy bits, that the Settings API doesn't cover for the main body of an admin page?

Replying to GaryJ:

That would be my preference, since they are then more self-documenting via the method and argument names.

Actually we can check if the second arg is an array and add it accordingly. Not a big fan of adding two functions that do approximately the same thing :)

In [18879]:

Make $current_screen->add_option() easier to use, see #18690

Following a discussion in #wordpress-dev it was decided to use the old functions and the new API (WP_Screen) in parallel in 3.3 and revisit it again in 3.4.

In that terms we can (should?) add get_column_headers(), get_hidden_columns() and get_hidden_meta_boxes() equivalents in WP_Screen so we can deprecate the stand-alone functions later.

18690.widgets-accessibility-mode.patch​ is an attempt to restore screen options for Widgets screen, missing since [18853].

Please post all patches and comments regarding WP_Screen on #18785. I'm working through all of it now. Thanks. This is the ticket for help only.

Wrong ticket, see ​https://core.trac.wordpress.org/ticket/18785#comment:17 :)

At this point, I think this feature is in. Should do the tab content changes on a separate ticket. I'm working on those, will make ticket. Bugs found with help tabs from here on should get their own bug ticket opened.

In [18896]:

Refine new help styles. see #18690.

Related: #18920

In [19045]:

Adjust the height of the help columns on 'Help' tab open. see #18690.