Changeset 41930

Timestamp:

10/18/17 21:59:34 (5 days ago)

Author:

westonruter

Message:

Customize: Draw attention to "Add Items" button after creating a new menu.

Introduce wp.customize.utils.highlightButton() and wp.customize.Menus.MenuSection#highlightNewItemButton().

Props bpayton, melchoyce, afercia, westonruter.
Fixes #42114.

Location:

trunk/src/wp-admin/js

Files:

• customize-controls.js (modified) (1 diff)
• customize-nav-menus.js (modified) (3 diffs)

trunk/src/wp-admin/js/customize-controls.js

@@ -749 +749 @@
         );
         return equal;
+    };
+
+    /**
+     * Highlight the existence of a button.
+     *
+     * This function reminds the user of a button represented by the specified
+     * UI element, after an optional delay. If the user focuses the element
+     * before the delay passes, the reminder is canceled.
+     *
+     * @since 4.9.0
+     *
+     * @param {jQuery} button - The element to highlight.
+     * @param {object} [options] - Options.
+     * @param {number} [options.delay=0] - Delay in milliseconds.
+     * @param {jQuery} [options.focusTarget] - A target for user focus that defaults to the highlighted element.
+     *                                         If the user focuses the target before the delay passes, the reminder
+     *                                         is canceled. This option exists to accommodate compound buttons
+     *                                         containing auxiliary UI, such as the Publish button augmented with a
+     *                                         Settings button.
+     * @returns {Function} An idempotent function that cancels the reminder.
+     */
+    api.utils.highlightButton = function highlightButton( button, options ) {
+        var animationClass = 'button-see-me',
+            canceled = false,
+            params;
+
+        params = _.extend(
+            {
+                delay: 0,
+                focusTarget: button
+            },
+            options
+        );
+
+        function cancelReminder() {
+            canceled = true;
+        }
+
+        // Remove animation class in case it was already applied.
+        button.removeClass( animationClass );
+
+        params.focusTarget.on( 'focusin', cancelReminder );
+        setTimeout( function() {
+            params.focusTarget.off( 'focusin', cancelReminder );
+
+            if ( ! canceled ) {
+                button.addClass( animationClass );
+            }
+        }, params.delay );
+
+        return cancelReminder;
     };
 

trunk/src/wp-admin/js/customize-nav-menus.js

@@ -1143 +1143 @@
             }
             api.Section.prototype.onChangeExpanded.call( section, expanded, args );
+        },
+
+        /**
+         * Highlight how a user may create new menu items.
+         *
+         * This method reminds the user to create new menu items and how.
+         * It's exposed this way because this class knows best which UI needs
+         * highlighted but those expanding this section know more about why and
+         * when the affordance should be highlighted.
+         *
+         * @since 4.9.0
+         *
+         * @returns {void}
+         */
+        highlightNewItemButton: function() {
+            api.utils.highlightButton( this.contentContainer.find( '.add-new-menu-item' ), { delay: 2000 } );
         }
     });
@@ -1326 +1342 @@
                 menuSection,
                 customizeId,
+                editMenuSection,
                 placeholderId = api.Menus.generatePlaceholderAutoIncrementId();
 
@@ -1384 +1401 @@
 
             // Focus on the new menu section.
-            api.section( customizeId ).focus(); // @todo should we focus on the new menu's control and open the add-items panel? Thinking user flow...
+            editMenuSection = api.section( customizeId );
+            editMenuSection.focus( {
+                completeCallback: function() {
+                    editMenuSection.highlightNewItemButton();
+                }
+            } ); // @todo should we focus on the new menu's control and open the add-items panel? Thinking user flow...
         },