From 7f94931449a25f2ffe278f3f6d8d2c4c5a16436a Mon Sep 17 00:00:00 2001 From: Anton Timmermans Date: Thu, 4 Jan 2018 14:36:13 +0000 Subject: [PATCH] Docs: Improve JSDoc for `js/media-upload.js`. Props terwdan, diedeexterkate, andizer, ireneyoast. Fixes #42956. git-svn-id: https://develop.svn.wordpress.org/trunk@42426 602fd350-edb4-49c9-b593-d223f7449a82 --- src/wp-admin/js/media-upload.js | 52 +++++++++++++++++++++++++++++++-- 1 file changed, 49 insertions(+), 3 deletions(-) diff --git a/src/wp-admin/js/media-upload.js b/src/wp-admin/js/media-upload.js index cd969b9b3a..b7171a3e9c 100644 --- a/src/wp-admin/js/media-upload.js +++ b/src/wp-admin/js/media-upload.js @@ -1,13 +1,38 @@ /* global tinymce, QTags */ -// send html to the post editor + +/** + * Contains global functions for the media upload within the post edit screen. + * + * Updates the ThickBox anchor href and the ThickBox's own properties in order + * to set the size and position on every resize event. Also adds a function to + * send HTML or text to the currently active editor. + * + * @file + * @since 2.5.0 + * + * @requires jQuery + */ var wpActiveEditor, send_to_editor; +/** + * Sends the HTML passed in the parameters to TinyMCE. + * + * @since 2.5.0 + * + * @global + * + * @param {string} html The HTML to be sent to the editor. + * @returns {void|boolean} Returns false when both TinyMCE and QTags instances + * are unavailable. This means that the HTML was not + * sent to the editor. + */ send_to_editor = function( html ) { var editor, hasTinymce = typeof tinymce !== 'undefined', hasQuicktags = typeof QTags !== 'undefined'; + // If no active editor is set, try to set it. if ( ! wpActiveEditor ) { if ( hasTinymce && tinymce.activeEditor ) { editor = tinymce.activeEditor; @@ -19,23 +44,38 @@ send_to_editor = function( html ) { editor = tinymce.get( wpActiveEditor ); } + // If the editor is set and not hidden, insert the HTML into the content of the + // editor. if ( editor && ! editor.isHidden() ) { editor.execCommand( 'mceInsertContent', false, html ); } else if ( hasQuicktags ) { + // If quick tags are available, insert the HTML into its content. QTags.insertContent( html ); } else { + // If neither the TinyMCE editor and the quick tags are available, add the HTML + // to the current active editor. document.getElementById( wpActiveEditor ).value += html; } - // If the old thickbox remove function exists, call it + // If the old thickbox remove function exists, call it. if ( window.tb_remove ) { try { window.tb_remove(); } catch( e ) {} } }; -// thickbox settings var tb_position; (function($) { + /** + * Recalculates and applies the new ThickBox position based on the current + * window size. + * + * @since 2.6.0 + * + * @global + * + * @returns {Object[]} Array containing jQuery objects for all the found + * ThickBox anchors. + */ tb_position = function() { var tbWindow = $('#TB_window'), width = $(window).width(), @@ -55,6 +95,11 @@ var tb_position; tbWindow.css({'top': 20 + adminbar_height + 'px', 'margin-top': '0'}); } + /** + * Recalculates the new height and width for all links with a ThickBox class. + * + * @since 2.6.0 + */ return $('a.thickbox').each( function() { var href = $(this).attr('href'); if ( ! href ) return; @@ -64,6 +109,7 @@ var tb_position; }); }; + // Add handler to recalculates the ThickBox position when the window is resized. $(window).resize(function(){ tb_position(); }); })(jQuery);