WordPress.org

Make WordPress Core

Opened 10 years ago

Closed 10 years ago

Last modified 9 years ago

#18690 closed task (blessed) (fixed)

Change the display layout of help tabs

Reported by: jane Owned by: koopersmith
Milestone: 3.3 Priority: normal
Severity: normal Version: 3.3
Component: UI Keywords: has-patch dev-feedback needs-testing
Focuses: Cc:

Description (last modified by scribu)

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.

Attachments (11)

photo.jpg (234.6 KB) - added by jane 10 years ago.
Sketch of new help layout proposal
3 columns help.jpg (149.3 KB) - added by azaozz 10 years ago.
18690.template.php.diff (5.0 KB) - added by mbijon 10 years ago.
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 !!!)
18690.2.patch.diff (16.4 KB) - added by goldenapples 10 years ago.
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)
18690.3.patch.diff (20.0 KB) - added by natebedortha 10 years ago.
Includes CSS & JS, and @goldenapple's last patch (with one slight markup change)
18690-wp-screen.diff (10.1 KB) - added by ryan 10 years ago.
The gist of WP_Screen
18690.diff (24.8 KB) - added by ryan 10 years ago.
Bring it all together
18690.2.diff (24.9 KB) - added by ryan 10 years ago.
Add $id arg to add_help_tab()
help-layout.png (69.0 KB) - added by jane 10 years ago.
Screenshot of new help layout styling per MT
18960.two-scrollbars.png (71.9 KB) - added by SergeyBiryukov 10 years ago.
18690.widgets-accessibility-mode.patch (352 bytes) - added by SergeyBiryukov 10 years ago.

Download all attachments as: .zip

Change History (64)

@jane
10 years ago

Sketch of new help layout proposal

#1 @scribu
10 years ago

  • Description modified (diff)

#2 @johnbillion
10 years ago

+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.

#3 @azaozz
10 years ago

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.

#4 @azaozz
10 years ago

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

#5 @scribu
10 years ago

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

Last edited 10 years ago by scribu (previous) (diff)

#6 @jane
10 years ago

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

#7 @mbijon
10 years ago

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;
	});

});


@mbijon
10 years ago

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 !!!)

#8 @mbijon
10 years ago

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.

@goldenapples
10 years ago

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)

#9 @goldenapples
10 years ago

  • Cc goldenapples added

@natebedortha
10 years ago

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

#10 @natebedortha
10 years ago

  • Cc natebedortha added

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.

#11 @mbijon
10 years ago

  • Cc mbijon added
  • Owner set to jane
  • Status changed from new to reviewing

#12 @jane
10 years ago

  • Owner changed from jane to koopersmith

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

#13 @jane
10 years ago

  • Keywords has-patch dev-feedback needs-testing added; needs-patch removed

#14 @dougwrites
10 years ago

  • Cc heymrpro@… added

#15 @ryan
10 years ago

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.

@ryan
10 years ago

The gist of WP_Screen

@ryan
10 years ago

Bring it all together

@ryan
10 years ago

Add $id arg to add_help_tab()

#16 @ryan
10 years ago

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

#17 @westi
10 years ago

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

Great improvement on the current help system.

#18 @ocean90
10 years ago

  • Cc ocean90 added

#19 @jane
10 years ago

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.

#20 @koopersmith
10 years ago

In [18779]:

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

#21 @nacin
10 years ago

In [18780]:

Use correct variable. see #18690.

#22 @nacin
10 years ago

In [18782]:

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

#23 @nacin
10 years ago

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

#24 @johnjamesjacoby
10 years ago

Is it worth considering renaming this to WP_Admin_Screen?

#25 @ryan
10 years ago

In [18793]:

First pass of WP_Screen phpdoc. see #18690

#26 @ryan
10 years ago

In [18794]:

Revert fat fingers in [18793]. see #18690

#27 @koopersmith
10 years ago

In [18797]:

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

@jane
10 years ago

Screenshot of new help layout styling per MT

#28 @koopersmith
10 years ago

In [18853]:

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

#29 @koopersmith
10 years ago

In [18854]:

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

#30 @SergeyBiryukov
10 years ago

  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.

#31 @azaozz
10 years ago

In [18861]:

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

#32 @azaozz
10 years ago

In [18862]:

Add phpdoc for the section title, see #18690

#33 @azaozz
10 years ago

In [18864]:

Add screen_options with contextual content, see #18690

#34 @koopersmith
10 years ago

In [18866]:

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

#35 follow-up: @azaozz
10 years ago

In [18867]:

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

#36 @azaozz
10 years ago

In [18874]:

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

#37 @dd32
10 years ago

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

#38 in reply to: ↑ 35 ; follow-up: @GaryJ
10 years ago

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.

#39 follow-up: @GaryJ
10 years ago

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?

#40 in reply to: ↑ 38 ; follow-up: @azaozz
10 years ago

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).

#41 in reply to: ↑ 39 ; follow-up: @azaozz
10 years ago

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().

#42 in reply to: ↑ 40 ; follow-up: @GaryJ
10 years ago

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)?

#43 in reply to: ↑ 41 @GaryJ
10 years ago

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?

#44 in reply to: ↑ 42 @azaozz
10 years ago

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 :)

#45 @azaozz
10 years ago

In [18879]:

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

#46 @azaozz
10 years ago

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.

#47 @SergeyBiryukov
10 years ago

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

#48 @nacin
10 years ago

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.

#50 @jane
10 years ago

  • Resolution set to fixed
  • Status changed from reviewing to closed

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.

#51 @koopersmith
10 years ago

In [18896]:

Refine new help styles. see #18690.

#53 @nacin
9 years ago

In [19045]:

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

Note: See TracTickets for help on using tickets.