Changeset 41310

Timestamp:

08/24/2017 05:47:58 PM (7 years ago)

Author:

wonderboymusic

Message:

Docs: improve JS docs for editor-expand.js

Props IreneYoast, terwdan.
Fixes #41068.

File:

• trunk/src/wp-admin/js/editor-expand.js (modified) (67 diffs)

trunk/src/wp-admin/js/editor-expand.js

@@ -7 +7 @@
         $footer = $( '#wpfooter' );
 
-    /* Autoresize editor. */
+    /**
+     * @summary Handles the resizing of the editor.
+     *
+     * @since 4.0.0
+     *
+     * @returns {void}
+     */
     $( function() {
         var $wrap = $( '#postdivrich' ),
@@ -54 +60 @@
             };
 
+
+
+
+
+
+
+
+
+
+
         var shrinkTextarea = window._.throttle( function() {
             var x = window.scrollX || document.documentElement.scrollLeft;
@@ -74 +90 @@
         }, 300 );
 
+
+
+
+
+
+
+
+
+
+
+
+
         function textEditorResize() {
             var length = textEditor.value.length;
@@ -95 +123 @@
         }
 
+
+
+
+
+
+
+
+
+
+
+
+
         function getHeights() {
             var windowWidth = $window.width();
@@ -111 +151 @@
             };
 
-            // Adjust for hidden
+            // Adjust for hidden
             if ( heights.menuBarHeight < 3 ) {
                 heights.menuBarHeight = 0;
@@ -118 +158 @@
 
         // We need to wait for TinyMCE to initialize.
+
+
+
+
+
+
+
+
+
+
+
         $document.on( 'tinymce-editor-init.editor-expand', function( event, editor ) {
+
             var VK = window.tinymce.util.VK,
+
+
+
+
+
                 hideFloatPanels = _.debounce( function() {
                     ! $( '.mce-floatpanel:hover' ).length && window.tinymce.ui.FloatPanel.hideAll();
@@ -142 +199 @@
             $menuBar = $contentWrap.find( '.mce-menubar' );
 
+
+
+
+
+
+
             function mceGetCursorOffset() {
                 var node = editor.selection.getNode(),
                     range, view, offset;
 
+
+
+
+
                 if ( editor.wp && editor.wp.getView && ( view = editor.wp.getView( node ) ) ) {
                     offset = view.getBoundingClientRect();
@@ -151 +218 @@
                     range = editor.selection.getRng();
 
+
                     try {
                         offset = range.getClientRects()[0];
                     } catch( er ) {}
 
+
                     if ( ! offset ) {
                         offset = node.getBoundingClientRect();
@@ -163 +232 @@
             }
 
-            // Make sure the cursor is always visible.
-            // This is not only necessary to keep the cursor between the toolbars,
-            // but also to scroll the window when the cursor moves out of the viewport to a wpview.
-            // Setting a buffer > 0 will prevent the browser default.
-            // Some browsers will scroll to the middle,
-            // others to the top/bottom of the *window* when moving the cursor out of the viewport.
+            /**
+             * @summary Filters the special keys that should not be used for scrolling.
+             *
+             * @since 4.0.0
+             *
+             * @param {event} event The event to get the key code from.
+             *
+             * @returns {void}
+             */
             function mceKeyup( event ) {
                 var key = event.keyCode;
 
-                // Bail on special keys.
+                // Bail on special keys.
                 if ( key <= 47 && ! ( key === VK.SPACEBAR || key === VK.ENTER || key === VK.DELETE || key === VK.BACKSPACE || key === VK.UP || key === VK.LEFT || key === VK.DOWN || key === VK.UP ) ) {
                     return;
-                // OS keys, function keys, num lock, scroll lock
+                // OS keys, function keys, num lock, scroll lock
                 } else if ( ( key >= 91 && key <= 93 ) || ( key >= 112 && key <= 123 ) || key === 144 || key === 145 ) {
                     return;
@@ -183 +255 @@
             }
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
             function mceScroll( key ) {
                 var offset = mceGetCursorOffset(),
@@ -188 +275 @@
                     cursorTop, cursorBottom, editorTop, editorBottom;
 
+
                 if ( ! offset ) {
                     return;
                 }
 
+
                 cursorTop = offset.top + editor.iframeElement.getBoundingClientRect().top;
+
+
                 cursorBottom = cursorTop + offset.height;
+
+
                 cursorTop = cursorTop - buffer;
+
+
                 cursorBottom = cursorBottom + buffer;
                 editorTop = heights.adminBarHeight + heights.toolsHeight + heights.menuBarHeight + heights.visualTopHeight;
+
+
+
+
+
                 editorBottom = heights.windowHeight - ( advanced ? heights.bottomHeight + heights.statusBarHeight : 0 );
 
-                // Don't scroll if the node is taller than the visible part of the editor
+                // Don't scroll if the node is taller than the visible part of the editor
                 if ( editorBottom - editorTop < offset.height ) {
                     return;
                 }
 
+
+
+
+
+
                 if ( cursorTop < editorTop && ( key === VK.UP || key === VK.LEFT || key === VK.BACKSPACE ) ) {
                     window.scrollTo( window.pageXOffset, cursorTop + window.pageYOffset - editorTop );
+
+
+
+
+
+
                 } else if ( cursorBottom > editorBottom ) {
                     window.scrollTo( window.pageXOffset, cursorBottom + window.pageYOffset - editorBottom );
@@ -211 +322 @@
             }
 
+
+
+
+
+
+
+
+
+
             function mceFullscreenToggled( event ) {
+
                 if ( ! event.state ) {
                     adjust();
@@ -217 +338 @@
             }
 
-            // Adjust when switching editor modes.
+            /**
+             * @summary Shows the editor when scrolled.
+             *
+             * Binds the hideFloatPanels function on the window scroll.mce-float-panels event.
+             * Executes the wpAutoResize on the active editor.
+             *
+             * @since 4.0.0
+             *
+             * @returns {void}
+             */
             function mceShow() {
                 $window.on( 'scroll.mce-float-panels', hideFloatPanels );
@@ -227 +357 @@
             }
 
+
+
+
+
+
+
+
+
+
+
             function mceHide() {
                 $window.off( 'scroll.mce-float-panels' );
@@ -244 +384 @@
             }
 
+
+
+
+
+
+
+
             function toggleAdvanced() {
                 advanced = ! advanced;
             }
 
+
+
+
+
+
+
+
             mceBind = function() {
                 editor.on( 'keyup', mceKeyup );
@@ -253 +407 @@
                 editor.on( 'hide', mceHide );
                 editor.on( 'wp-toolbar-toggle', toggleAdvanced );
+
                 // Adjust when the editor resizes.
                 editor.on( 'setcontent wp-autoresize wp-toolbar-toggle', adjust );
+
                 // Don't hide the caret after undo/redo.
                 editor.on( 'undo redo', mceScroll );
+
                 // Adjust when exiting TinyMCE's fullscreen mode.
                 editor.on( 'FullscreenStateChanged', mceFullscreenToggled );
@@ -263 +420 @@
             };
 
+
+
+
+
+
+
+
             mceUnbind = function() {
                 editor.off( 'keyup', mceKeyup );
@@ -276 +440 @@
 
             if ( $wrap.hasClass( 'wp-editor-expand' ) ) {
-                // Adjust "immediately"
+
+                // Adjust "immediately".
                 mceBind();
                 initialResize( adjust );
@@ -282 +447 @@
         } );
 
-        // Adjust the toolbars based on the active editor mode.
+        /**
+         * @summary Adjusts the toolbars heights and positions.
+         *
+         * Adjusts the toolbar heights and positions based on the scroll position on the page,
+         * the active editor mode and the heights of the editor, admin bar and side bar.
+         *
+         * @since 4.0.0
+         *
+         * @param {event} event The event that calls this function.
+         *
+         * @returns {void}
+         */
         function adjust( event ) {
-            // Make sure we're not in fullscreen mode.
+
+            // Makes sure we're not in fullscreen mode.
             if ( fullscreen && fullscreen.settings.visible ) {
                 return;
@@ -300 +477 @@
                 topPos, topHeight, editorPos, editorHeight;
 
-            // Refresh the heights
+            /*
+             * Refresh the heights if type isn't 'scroll'
+             * or heights.windowHeight isn't set.
+             */
             if ( resize || ! heights.windowHeight ) {
                 getHeights();
             }
 
+
             if ( ! visual && type === 'resize' ) {
                 textEditorResize();
@@ -319 +500 @@
             }
 
-            // TinyMCE still initializing.
+            // tializing.
             if ( ! visual && ! $top.length ) {
                 return;
@@ -328 +509 @@
             editorHeight = $editor.outerHeight();
 
-            // Should we pin?
+            /*
+             * If in visual mode, checks if the editorHeight is greater than the autoresizeMinHeight + topHeight.
+             * If not in visual mode, checks if the editorHeight is greater than the autoresizeMinHeight + 20.
+             */
             canPin = visual ? autoresizeMinHeight + topHeight : autoresizeMinHeight + 20; // 20px from textarea padding
             canPin = editorHeight > ( canPin + 5 );
@@ -358 +542 @@
                 }
             } else {
-                // Maybe pin the top.
+                // .
                 if ( ( ! fixedTop || resize ) &&
-                    // Handle scrolling down.
                     ( windowPos >= ( topPos - heights.toolsHeight - heights.adminBarHeight ) &&
-                    // Handle scrolling up.
                     windowPos <= ( topPos - heights.toolsHeight - heights.adminBarHeight + editorHeight - buffer ) ) ) {
                     fixedTop = true;
@@ -385 +567 @@
                         width: contentWrapWidth - ( borderWidth * 2 ) - ( visual ? 0 : ( $top.outerWidth() - $top.width() ) )
                     } );
-                // Maybe unpin the top.
+                .
                 } else if ( fixedTop || resize ) {
-                    // Handle scrolling up.
                     if ( windowPos <= ( topPos - heights.toolsHeight - heights.adminBarHeight ) ) {
                         fixedTop = false;
@@ -410 +591 @@
                             width: contentWrapWidth - ( borderWidth * 2 ) - ( visual ? 0 : ( $top.outerWidth() - $top.width() ) )
                         } );
-                    // Handle scrolling down.
                     } else if ( windowPos >= ( topPos - heights.toolsHeight - heights.adminBarHeight + editorHeight - buffer ) ) {
                         fixedTop = false;
@@ -436 +616 @@
                 }
 
-                // Maybe adjust the bottom bar.
+                // .
                 if ( ( ! fixedBottom || ( resize && advanced ) ) &&
-                        // +[n] for the border around the .wp-editor-container.
+                        //  for the border around the .wp-editor-container.
                         ( windowPos + heights.windowHeight ) <= ( editorPos + editorHeight + heights.bottomHeight + heights.statusBarHeight + borderWidth ) ) {
 
@@ -469 +649 @@
             }
 
-            // Sidebar pinning
-            if ( $postboxContainer.width() < 300 && heights.windowWidth > 600 && // sidebar position is changed with @media from CSS, make sure it is on the side
-                $document.height() > ( $sideSortables.height() + postBodyTop + 120 ) && // the sidebar is not the tallest element
-                heights.windowHeight < editorHeight ) { // the editor is taller than the viewport
+            // The postbox container is positioned with @media from CSS. Ensure it is pinned on the side.
+            if ( $postboxContainer.width() < 300 && heights.windowWidth > 600 &&
+
+                // Check if the sidebar is not taller than the document height.
+                $document.height() > ( $sideSortables.height() + postBodyTop + 120 ) &&
+
+                // Check if the editor is taller than the viewport.
+                heights.windowHeight < editorHeight ) {
 
                 if ( ( heights.sideSortablesHeight + pinnedToolsTop + sidebarBottom ) > heights.windowHeight || fixedSideTop || fixedSideBottom ) {
-                    // Reset when scrolling to the top
+
+                    // Reset the sideSortables style when scrolling to the top.
                     if ( windowPos + pinnedToolsTop <= postBodyTop ) {
                         $sideSortables.attr( 'style', '' );
                         fixedSideTop = fixedSideBottom = false;
                     } else {
+
+
                         if ( windowPos > lastScrollPosition ) {
-                            // Scrolling down
                             if ( fixedSideTop ) {
-                                // let it scroll
+
+                                // Let it scroll.
                                 fixedSideTop = false;
                                 sidebarTop = $sideSortables.offset().top - heights.adminBarHeight;
                                 footerTop = $footer.offset().top;
 
-                                // don't get over the footer
+                                // 
                                 if ( footerTop < sidebarTop + heights.sideSortablesHeight + sidebarBottom ) {
                                     sidebarTop = footerTop - heights.sideSortablesHeight - 12;
@@ -499 +686 @@
                                 });
                             } else if ( ! fixedSideBottom && heights.sideSortablesHeight + $sideSortables.offset().top + sidebarBottom < windowPos + heights.windowHeight ) {
-                                // pin the bottom
+                                // 
                                 fixedSideBottom = true;
 
@@ -508 +695 @@
                                 });
                             }
+
+
                         } else if ( windowPos < lastScrollPosition ) {
-                            // Scrolling up
                             if ( fixedSideBottom ) {
-                                // let it scroll
+                                // 
                                 fixedSideBottom = false;
                                 sidebarTop = $sideSortables.offset().top - sidebarBottom;
                                 footerTop = $footer.offset().top;
 
-                                // don't get over the footer
+                                // 
                                 if ( footerTop < sidebarTop + heights.sideSortablesHeight + sidebarBottom ) {
                                     sidebarTop = footerTop - heights.sideSortablesHeight - 12;
@@ -527 +715 @@
                                 });
                             } else if ( ! fixedSideTop && $sideSortables.offset().top >= windowPos + pinnedToolsTop ) {
-                                // pin the top
+                                // 
                                 fixedSideTop = true;
 
@@ -539 +727 @@
                     }
                 } else {
-                    // if the sidebar container is smaller than the viewport, then pin/unpin the top when scrolling
+                    // 
                     if ( windowPos >= ( postBodyTop - pinnedToolsTop ) ) {
 
@@ -576 +764 @@
         }
 
+
+
+
+
+
+
+
         function fullscreenHide() {
             textEditorResize();
@@ -581 +776 @@
         }
 
+
+
+
+
+
+
+
+
+
         function initialResize( callback ) {
             for ( var i = 1; i < 6; i++ ) {
@@ -587 +791 @@
         }
 
+
+
+
+
+
+
+
         function afterScroll() {
             clearTimeout( scrollTimer );
@@ -592 +803 @@
         }
 
+
+
+
+
+
+
+
         function on() {
-            // Scroll to the top when triggering this from JS.
-            // Ensures toolbars are pinned properly.
+            /*
+             * Scroll to the top when triggering this from JS.
+             * Ensure the toolbars are pinned properly.
+             */
             if ( window.pageYOffset && window.pageYOffset > pageYOffsetAtTop ) {
                 window.scrollTo( window.pageXOffset, 0 );
@@ -607 +827 @@
             } );
 
-            // Adjust when collapsing the menu, changing the columns, changing the body class.
+            /*
+             * Adjust when collapsing the menu, changing the columns
+             * or changing the body class.
+             */
             $document.on( 'wp-collapse-menu.editor-expand postboxes-columnchange.editor-expand editor-classchange.editor-expand', adjust )
                 .on( 'postbox-toggled.editor-expand postbox-moved.editor-expand', function() {
@@ -629 +852 @@
             mceBind();
 
-            // Adjust when entering/exiting fullscreen mode.
+            // Adjust when enteringexiting fullscreen mode.
             fullscreen && fullscreen.pubsub.subscribe( 'hidden', fullscreenHide );
 
@@ -650 +873 @@
         }
 
+
+
+
+
+
+
+
         function off() {
             var height = parseInt( window.getUserSetting( 'ed_size', 300 ), 10 );
@@ -659 +889 @@
             }
 
-            // Scroll to the top when triggering this from JS.
-            // Ensures toolbars are reset properly.
+            /*
+             * Scroll to the top when triggering this from JS.
+             * Ensure the toolbars are reset properly.
+             */
             if ( window.pageYOffset && window.pageYOffset > pageYOffsetAtTop ) {
                 window.scrollTo( window.pageXOffset, 0 );
@@ -672 +904 @@
             mceUnbind();
 
-            // Adjust when entering/exiting fullscreen mode.
+            // Adjust when enteringexiting fullscreen mode.
             fullscreen && fullscreen.pubsub.unsubscribe( 'hidden', fullscreenHide );
 
@@ -695 +927 @@
             }
 
+
             if ( height ) {
                 $textEditor.height( height );
@@ -702 +935 @@
         }
 
-        // Start on load
+        // Start on load
         if ( $wrap.hasClass( 'wp-editor-expand' ) ) {
             on();
 
-            // Ideally we need to resize just after CSS has fully loaded and QuickTags is ready.
+            // esize just after CSS has fully loaded and QuickTags is ready.
             if ( $contentWrap.hasClass( 'html-active' ) ) {
                 initialResize( function() {
@@ -715 +948 @@
         }
 
-        // Show the on/off checkbox
+        // Show the on/off checkbox
         $( '#adv-settings .editor-expand' ).show();
         $( '#editor-expand-toggle' ).on( 'change.editor-expand', function() {
@@ -727 +960 @@
         });
 
-        // Expose on() and off()
+        // Expose on() and off()
         window.editorExpand = {
             on: on,
@@ -734 +967 @@
     } );
 
-    /* DFW. */
+    /**
+     * @summary Handles the distraction free writing of TinyMCE.
+     *
+     * @since 4.1.0
+     *
+     * @returns {void}
+     */
     $( function() {
         var $body = $( document.body ),
@@ -778 +1017 @@
         } );
 
+
+
+
+
+
+
+
         function recalcEditorRect() {
             editorRect = $editor.offset();
@@ -784 +1030 @@
         }
 
+
+
+
+
+
+
+
         function activate() {
             if ( ! _isActive ) {
@@ -793 +1046 @@
         }
 
+
+
+
+
+
+
+
         function deactivate() {
             if ( _isActive ) {
@@ -804 +1064 @@
         }
 
+
+
+
+
+
+
+
         function isActive() {
             return _isActive;
         }
 
+
+
+
+
+
+
+
         function on() {
             if ( ! _isOn && _isActive ) {
@@ -824 +1098 @@
         }
 
+
+
+
+
+
+
+
         function off() {
             if ( _isOn ) {
@@ -840 +1121 @@
         }
 
+
+
+
+
+
+
+
         function toggle() {
             if ( _isOn ) {
@@ -848 +1136 @@
         }
 
+
+
+
+
+
+
+
         function isOn() {
             return _isOn;
         }
 
+
+
+
+
+
+
+
+
+
+
+
+
+
         function fadeOut( event ) {
             var isMac,
@@ -860 +1168 @@
             }
 
-            // fadeIn and return on Escape and keyboard shortcut Alt+Shift+W and Ctrl+Opt+W.
+            //  on Escape and keyboard shortcut Alt+Shift+W and Ctrl+Opt+W.
             if ( key === 27 || ( key === 87 && event.altKey && ( ( ! isMac && event.shiftKey ) || ( isMac && event.ctrlKey ) ) ) ) {
                 fadeIn( event );
@@ -866 +1174 @@
             }
 
+
             if ( event && ( event.metaKey || ( event.ctrlKey && ! event.altKey ) || ( event.altKey && event.shiftKey ) || ( key && (
                 // Special keys ( tab, ctrl, alt, esc, arrow keys... )
@@ -893 +1202 @@
 
                 $overlay
-                    // Always recalculate the editor area entering the overlay with the mouse.
+                    // Always recalculate the editor area entering the overlay with the mouse.
                     .on( 'mouseenter.focus', function() {
                         recalcEditorRect();
@@ -960 +1269 @@
                         y = ny;
                     } )
-                    // When the overlay is touched, always fade in and cancel the event.
+
+                    // When the overlay is touched, fade in and cancel the event.
                     .on( 'touchstart.focus', function( event ) {
                         event.preventDefault();
@@ -980 +1290 @@
         }
 
+
+
+
+
+
+
+
+
+
         function fadeIn( event ) {
             if ( faded ) {
@@ -1019 +1338 @@
         }
 
+
+
+
+
+
+
+
         function maybeFadeIn() {
             setTimeout( function() {
@@ -1034 +1360 @@
         }
 
+
+
+
+
+
+
+
         function fadeOutAdminBar() {
             if ( ! fadedAdminBar && faded ) {
@@ -1048 +1381 @@
         }
 
+
+
+
+
+
+
+
         function fadeInAdminBar() {
             if ( fadedAdminBar ) {
@@ -1056 +1396 @@
         }
 
+
+
+
+
+
+
+
         function fadeOutSlug() {
             if ( ! fadedSlug && faded && ! $slug.find( ':focus').length ) {
@@ -1066 +1413 @@
         }
 
+
+
+
+
+
+
+
         function fadeInSlug() {
             if ( fadedSlug ) {
@@ -1076 +1430 @@
         }
 
+
+
+
+
+
+
+
+
+
+
+
         function toggleViaKeyboard( event ) {
             if ( event.altKey && event.shiftKey && 87 === event.keyCode ) {
@@ -1086 +1451 @@
         }
 
+
+
+
+
+
+
+
+
+
+
         $document.on( 'tinymce-editor-setup.focus', function( event, editor ) {
             editor.addButton( 'dfw', {
@@ -1117 +1492 @@
         } );
 
+
+
+
+
+
+
+
+
+
+
         $document.on( 'tinymce-editor-init.focus', function( event, editor ) {
             var mceBind, mceUnbind;
@@ -1152 +1537 @@
                 }
 
+
                 $document.on( 'dfw-on.focus', mceBind ).on( 'dfw-off.focus', mceUnbind );
 
-                // Make sure the body focuses when clicking outside it.
+                // t.
                 editor.on( 'click', function( event ) {
                     if ( event.target === editor.getDoc().documentElement ) {
@@ -1163 +1549 @@
         } );
 
+
+
+
+
+
+
+
+
+
+
         $document.on( 'quicktags-init', function( event, editor ) {
             var $button;
 
+
             if ( editor.settings.buttons && ( ',' + editor.settings.buttons + ',' ).indexOf( ',dfw,' ) !== -1 ) {
                 $button = $( '#' + editor.name + '_dfw' );