WordPress.org

Make WordPress Core

Opened 3 years ago

Closed 3 years ago

Last modified 2 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 3 years ago.
Sketch of new help layout proposal
3 columns help.jpg (149.3 KB) - added by azaozz 3 years ago.
18690.template.php.diff (5.0 KB) - added by mbijon 3 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 3 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 3 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 3 years ago.
The gist of WP_Screen
18690.diff (24.8 KB) - added by ryan 3 years ago.
Bring it all together
18690.2.diff (24.9 KB) - added by ryan 3 years ago.
Add $id arg to add_help_tab()
help-layout.png (69.0 KB) - added by jane 3 years ago.
Screenshot of new help layout styling per MT
18960.two-scrollbars.png (71.9 KB) - added by SergeyBiryukov 3 years ago.
18690.widgets-accessibility-mode.patch (352 bytes) - added by SergeyBiryukov 3 years ago.

Download all attachments as: .zip

Change History (64)

jane3 years ago

Sketch of new help layout proposal

comment:1 scribu3 years ago

  • Description modified (diff)

comment:2 johnbillion3 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.

comment:3 azaozz3 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.

azaozz3 years ago

comment:4 azaozz3 years ago

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

comment:5 scribu3 years ago

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

Version 0, edited 3 years ago by scribu (next)

comment:6 jane3 years ago

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

comment:7 mbijon3 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;
	});

});


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

comment:8 mbijon3 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.

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

comment:9 goldenapples3 years ago

  • Cc goldenapples added

natebedortha3 years ago

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

comment:10 natebedortha3 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.

comment:11 mbijon3 years ago

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

comment:12 jane3 years ago

  • Owner changed from jane to koopersmith

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

comment:13 jane3 years ago

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

comment:14 dougwrites3 years ago

  • Cc heymrpro@… added

comment:15 ryan3 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.

ryan3 years ago

The gist of WP_Screen

ryan3 years ago

Bring it all together

ryan3 years ago

Add $id arg to add_help_tab()

comment:16 ryan3 years ago

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

comment:17 westi3 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.

comment:18 ocean903 years ago

  • Cc ocean90 added

comment:19 jane3 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.

comment:20 koopersmith3 years ago

In [18779]:

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

comment:21 nacin3 years ago

In [18780]:

Use correct variable. see #18690.

comment:22 nacin3 years ago

In [18782]:

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

comment:23 nacin3 years ago

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

comment:24 johnjamesjacoby3 years ago

Is it worth considering renaming this to WP_Admin_Screen?

comment:25 ryan3 years ago

In [18793]:

First pass of WP_Screen phpdoc. see #18690

comment:26 ryan3 years ago

In [18794]:

Revert fat fingers in [18793]. see #18690

comment:27 koopersmith3 years ago

In [18797]:

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

jane3 years ago

Screenshot of new help layout styling per MT

comment:28 koopersmith3 years ago

In [18853]:

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

comment:29 koopersmith3 years ago

In [18854]:

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

comment:30 SergeyBiryukov3 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.

comment:31 azaozz3 years ago

In [18861]:

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

comment:32 azaozz3 years ago

In [18862]:

Add phpdoc for the section title, see #18690

comment:33 azaozz3 years ago

In [18864]:

Add screen_options with contextual content, see #18690

comment:34 koopersmith3 years ago

In [18866]:

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

comment:35 follow-up: azaozz3 years ago

In [18867]:

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

comment:36 azaozz3 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

comment:37 dd323 years ago

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

comment:38 in reply to: ↑ 35 ; follow-up: GaryJ3 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.

comment:39 follow-up: GaryJ3 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?

comment:40 in reply to: ↑ 38 ; follow-up: azaozz3 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).

comment:41 in reply to: ↑ 39 ; follow-up: azaozz3 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().

comment:42 in reply to: ↑ 40 ; follow-up: GaryJ3 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)?

comment:43 in reply to: ↑ 41 GaryJ3 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?

comment:44 in reply to: ↑ 42 azaozz3 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 :)

comment:45 azaozz3 years ago

In [18879]:

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

comment:46 azaozz3 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.

comment:47 SergeyBiryukov3 years ago

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

comment:48 nacin3 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.

comment:50 jane3 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.

comment:51 koopersmith3 years ago

In [18896]:

Refine new help styles. see #18690.

comment:52 ocean903 years ago

Related: #18920

comment:53 nacin2 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.