Ticket #38748: image-edit.diff

src/wp-admin/js/image-edit.js

@@ -1 +1 @@
 /* global imageEditL10n, ajaxurl, confirm */
+/**
+ * @summary   The functions necessary for editing images.
+ *
+ * @since     2.8.5
+ */
 
 (function($) {
-var imageEdit = window.imageEdit = {
+
+        /**
+         * Contains all the methods to initialise and control the image editor.
+         *
+         * @namespace imageEdit
+         */
+        var imageEdit = window.imageEdit = {
         iasapi : {},
         hold : {},
         postid : '',
         _view : false,
 
+        /**
+         * @summary Converts a value to an integer.
+         *
+         * @memberof imageEdit
+         * @since    2.8.5
+         *
+         * @param {number} f The float value should be converted.
+         *
+         * @return {number} The integer representation from the float value.
+         */
         intval : function(f) {
                 /*
                  * Bitwise OR operator: one of the obscure ways to truncate floating point figures,
@@ -14 +35 @@
                  */
                 return f | 0;
         },
-
+        /**
+         * @summary Adds the disabled attribute and class to a single form element
+         *          or a field set.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {jQuery}         el The element that should be modified.
+         * @param {bool|number}    s  The state for the element. If set to true
+         *                            the element is disabled,
+         *                            else the element is enabled.
+         *                            The function is sometimes called with a 0 or 1
+         *                            instead of true or false.
+         *
+         * @returns {void}
+         */
         setDisabled : function( el, s ) {
                 /*
                  * `el` can be a single form element or a fieldset. Before #28864, the disabled state on
@@ -29 +65 @@
                 }
         },
 
+        /**
+         * @summary Initializes the image editor.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number} postid The post id.
+         *
+         * @returns {void}
+         */
         init : function(postid) {
                 var t = this, old = $('#image-editor-' + t.postid),
                         x = t.intval( $('#imgedit-x-' + postid).val() ),
@@ -48 +94 @@
                 $('input[type="text"]', '#imgedit-panel-' + postid).keypress(function(e) {
                         var k = e.keyCode;
 
+                        // Key codes 37 till 40 are the arrow keys.
                         if ( 36 < k && k < 41 ) {
                                 $(this).blur();
                         }
 
+                        // The key code 13 is the enter key.
                         if ( 13 === k ) {
                                 e.preventDefault();
                                 e.stopPropagation();
@@ -60 +108 @@
                 });
         },
 
+        /**
+         * @summary Toggles the wait/load icon in the editor.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number} postid The post id.
+         * @param {number} toggle Is 0 or 1, fades the icon in then 1 and out when 0.
+         *
+         * @returns {void}
+         */
         toggleEditor : function(postid, toggle) {
                 var wait = $('#imgedit-wait-' + postid);
 
@@ -70 +129 @@
                 }
         },
 
+        /**
+         * @summary Shows or hides the image edit help box.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {HTMLElement} el The element to create the help window in.
+         *
+         * @returns {boolean} Always returns false.
+         */
         toggleHelp : function(el) {
                 var $el = $( el );
                 $el
@@ -79 +148 @@
                 return false;
         },
 
+        /**
+         * @summary Gets the value from the image edit target.
+         *
+         * The image edit target contains the image sizes where the (possible) changes
+         * have to be applied to.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number} postid The post id.
+         *
+         * @returns {string} The value from the imagedit-save-target input field when available,
+         *                   or 'full' when not available.
+         */
         getTarget : function(postid) {
                 return $('input[name="imgedit-target-' + postid + '"]:checked', '#imgedit-save-target-' + postid).val() || 'full';
         },
 
+        /**
+         * @summary Recalculates the height or width and keeps the original aspect ratio.
+         *
+         * If the original image size is exceeded a red exclamation mark is shown.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number}         postid The current post id.
+         * @param {number}         x      Is 0 when it applies the y-axis
+         *                                and 1 when applicable for the x-axis.
+         * @param {jQuery}         el     Element.
+         *
+         * @returns {void}
+         */
         scaleChanged : function( postid, x, el ) {
                 var w = $('#imgedit-scale-width-' + postid), h = $('#imgedit-scale-height-' + postid),
                 warn = $('#imgedit-scale-warn-' + postid), w1 = '', h1 = '';
@@ -106 +204 @@
                 }
         },
 
+        /**
+         * @summary Gets the selected aspect ratio.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number} postid The post id.
+         *
+         * @returns {string} The aspect ratio.
+         */
         getSelRatio : function(postid) {
                 var x = this.hold.w, y = this.hold.h,
                         X = this.intval( $('#imgedit-crop-width-' + postid).val() ),
@@ -122 +230 @@
                 return '1:1';
         },
 
+        /**
+         * @summary Removes the last action from the image edit history
+         * The history consist of (edit)actions performed on the image.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number} postid  The post id.
+         * @param {number} setSize 0 or 1, when 1 the image resets to its original size.
+         *
+         * @returns {string} JSON string containing the history or an empty string if no history exists.
+         */
         filterHistory : function(postid, setSize) {
-                // apply undo state to history
+                // Apply undo state to history.
                 var history = $('#imgedit-history-' + postid).val(), pop, n, o, i, op = [];
 
                 if ( history !== '' ) {
+                        // Read the JSON string with the image edit history.
                         history = JSON.parse(history);
                         pop = this.intval( $('#imgedit-undone-' + postid).val() );
                         if ( pop > 0 ) {
@@ -136 +257 @@
                                 }
                         }
 
+                        // Reset size to it's original state.
                         if ( setSize ) {
                                 if ( !history.length ) {
                                         this.hold.w = this.hold.ow;
@@ -143 +265 @@
                                         return '';
                                 }
 
-                                // restore
+                                // Restore original 'o'.
                                 o = history[history.length - 1];
+
+                                // c = 'crop', r = 'rotate', f = 'flip'
                                 o = o.c || o.r || o.f || false;
 
                                 if ( o ) {
+                                        // fw = Full image width
                                         this.hold.w = o.fw;
+                                        // fh = Full image height
                                         this.hold.h = o.fh;
                                 }
                         }
 
-                        // filter the values
+                        // Filter the last step/action from the history.
                         for ( n in history ) {
                                 i = history[n];
                                 if ( i.hasOwnProperty('c') ) {
@@ -168 +294 @@
                 }
                 return '';
         },
-
+        /**
+         * @summary Binds the necessary events to the image.
+         *
+         * When the image source is reloaded the image will be reloaded.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number}   postid   The post id.
+         * @param {string}   nonce    The nonce to verify the request.
+         * @param {function} callback Function executed when the image is loaded.
+         *
+         * @returns {void}
+         */
         refreshEditor : function(postid, nonce, callback) {
                 var t = this, data, img;
 
@@ -188 +327 @@
                                         t = imageEdit,
                                         historyObj;
 
+                                // Checks if there already is some image-edit history.
                                 if ( '' !== event.data.history ) {
                                         historyObj = JSON.parse( event.data.history );
                                         // If last executed action in history is a crop action.
@@ -230 +370 @@
                         })
                         .attr('src', ajaxurl + '?' + $.param(data));
         },
-
+        /**
+         * @summary Performs an image edit action.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param  {number}  postid The post id.
+         * @param  {string}  nonce  The nonce to verify the request.
+         * @param  {string}  action The action to perform on the image.
+         *                          The possible actions are: "scale" and "restore".
+         *
+         * @returns {boolean|void} Executes a post request that refreshes the page
+         *                         when the action is performed.
+         *                         Returns false if a invalid action is given,
+         *                         or when the action cannot be performed.
+         */
         action : function(postid, nonce, action) {
                 var t = this, data, w, h, fw, fh;
 
@@ -282 +437 @@
                 });
         },
 
+        /**
+         * @summary Stores the changes that are made to the image.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number}  postid   The post id to get the image from the database.
+         * @param {string}  nonce    The nonce to verify the request.
+         *
+         * @returns {boolean|void}  If the actions are successfully saved a response message is shown.
+         *                          Returns false if there is no image editing history,
+         *                          thus there are not edit-actions performed on the image.
+         */
         save : function(postid, nonce) {
                 var data,
                         target = this.getTarget(postid),
@@ -302 +470 @@
                         'context': $('#image-edit-context').length ? $('#image-edit-context').val() : null,
                         'do': 'save'
                 };
-
+                // Post the image edit data to the backend.
                 $.post(ajaxurl, data, function(r) {
+                        // Read the response.
                         var ret = JSON.parse(r);
 
+                        // If a response is returned, close the editor and show an error.
                         if ( ret.error ) {
                                 $('#imgedit-response-' + postid).html('<div class="error"><p>' + ret.error + '</p></div>');
                                 imageEdit.close(postid);
@@ -332 +502 @@
                 });
         },
 
+        /**
+         * @summary Creates the image edit window.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number} postid   The post id for the image.
+         * @param {string} nonce    The nonce to verify the request.
+         * @param {object} view     The image editor view to be used for the editing.
+         *
+         * @returns {void|promise} Either returns void if the button was already activated
+         *                          or returns an instance of the image editor, wrapped in a promise.
+         */
         open : function( postid, nonce, view ) {
                 this._view = view;
 
@@ -376 +559 @@
                 return dfd;
         },
 
+        /**
+         * @summary Initializes the cropping tool and sets a default cropping selection.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number} postid The post id.
+         *
+         * @returns {void}
+         */
         imgLoaded : function(postid) {
                 var img = $('#image-preview-' + postid), parent = $('#imgedit-crop-' + postid);
 
@@ -386 +579 @@
                 $( '.imgedit-wrap .imgedit-help-toggle' ).eq( 0 ).focus();
         },
 
+        /**
+         * @summary Initializes the cropping tool.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number}      postid The post id.
+         * @param {HTMLElement} image  The preview image.
+         * @param {HTMLElement} parent The preview image container.
+         *
+         * @returns {void}
+         */
         initCrop : function(postid, image, parent) {
                 var t = this,
                         selW = $('#imgedit-sel-width-' + postid),
@@ -400 +605 @@
                         minWidth: 3,
                         minHeight: 3,
 
+                        /**
+                         * @summary Sets the CSS styles and binds events for locking the aspect ratio.
+                         *
+                         * @param {jQuery} img The preview image.
+                         */
                         onInit: function( img ) {
-                                // Ensure that the imgareaselect wrapper elements are position:absolute
+                                // Ensure that the imgAreaSelect wrapper elements are position:absolute
                                 // (even if we're in a position:fixed modal)
                                 $img = $( img );
                                 $img.next().css( 'position', 'absolute' )
                                         .nextAll( '.imgareaselect-outer' ).css( 'position', 'absolute' );
-
+                                /**
+                                 * @summary Binds mouse down event to the cropping container.
+                                 *
+                                 * @returns {void}
+                                 */
                                 parent.children().mousedown(function(e){
                                         var ratio = false, sel, defRatio;
 
@@ -422 +636 @@
                                 });
                         },
 
+                        /**
+                         * @summary Event triggered when starting a selection.
+                         *
+                         * @returns {void}
+                         */
                         onSelectStart: function() {
                                 imageEdit.setDisabled($('#imgedit-crop-sel-' + postid), 1);
                         },
-
+                        /**
+                         * @summary Event triggered when the selection is ended.
+                         *
+                         * @param {object} img jQuery object representing the image.
+                         * @param {object} c   The selection.
+                         *
+                         * @returns {object}
+                         */
                         onSelectEnd: function(img, c) {
                                 imageEdit.setCropSelection(postid, c);
                         },
 
+                        /**
+                         * @summary Event triggered when the selection changed.
+                         *
+                         * @param {object} img jQuery object representing the image.
+                         * @param {object} c   The selection.
+                         *
+                         * @returns {void}
+                         */
                         onSelectChange: function(img, c) {
                                 var sizer = imageEdit.hold.sizer;
                                 selW.val( imageEdit.round(c.width / sizer) );
@@ -438 +672 @@
                 });
         },
 
+        /**
+         * @summary Stores the current crop selection.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number} postid The post id.
+         * @param {object} c      The selection.
+         *
+         * @returns {boolean}
+         */
         setCropSelection : function(postid, c) {
                 var sel;
 
@@ -457 +702 @@
                 $('#imgedit-selection-' + postid).val( JSON.stringify(sel) );
         },
 
+
+        /**
+         * @summary Closes the image editor.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number}  postid The post id.
+         * @param {bool}    warn   Warning message.
+         *
+         * @returns {void|bool} Returns false if there is a warning.
+         */
         close : function(postid, warn) {
                 warn = warn || false;
 
@@ -487 +744 @@
 
         },
 
+        /**
+         * @summary Checks if the image edit history is saved.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number} postid The post id.
+         *
+         * @returns {boolean} Returns true if the history is not saved.
+         */
         notsaved : function(postid) {
                 var h = $('#imgedit-history-' + postid).val(),
                         history = ( h !== '' ) ? JSON.parse(h) : [],
@@ -501 +768 @@
                 return false;
         },
 
+        /**
+         * @summary Adds a image edit action to the history.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {object} op     The original position.
+         * @param {number} postid The post id.
+         * @param {string} nonce  The nonce.
+         *
+         * @returns {void}
+         */
         addStep : function(op, postid, nonce) {
                 var t = this, elem = $('#imgedit-history-' + postid),
                         history = ( elem.val() !== '' ) ? JSON.parse( elem.val() ) : [],
@@ -522 +801 @@
                 });
         },
 
+        /**
+         * @summary Rotates the image.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {string} angle  The angle the image is rotated with.
+         * @param {number} postid The post id.
+         * @param {string} nonce  The nonce
+         * @param {object} t      The target element.
+         *
+         * @returns {boolean}
+         */
         rotate : function(angle, postid, nonce, t) {
                 if ( $(t).hasClass('disabled') ) {
                         return false;
@@ -530 +822 @@
                 this.addStep({ 'r': { 'r': angle, 'fw': this.hold.h, 'fh': this.hold.w }}, postid, nonce);
         },
 
+        /**
+         * @summary Flips the image.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number} axis   The axle the image is flipped on.
+         * @param {number} postid The post id.
+         * @param {string} nonce  The nonce.
+         * @param {object} t      The target element.
+         *
+         * @returns {boolean}
+         */
         flip : function (axis, postid, nonce, t) {
                 if ( $(t).hasClass('disabled') ) {
                         return false;
@@ -538 +843 @@
                 this.addStep({ 'f': { 'f': axis, 'fw': this.hold.w, 'fh': this.hold.h }}, postid, nonce);
         },
 
+        /**
+         * @summary Crops the image.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number} postid The post id.
+         * @param {string} nonce  The nonce.
+         * @param {object} t      The target object.
+         *
+         * @returns {void|boolean} Returns false if the crop button is disabled.
+         */
         crop : function (postid, nonce, t) {
                 var sel = $('#imgedit-selection-' + postid).val(),
                         w = this.intval( $('#imgedit-sel-width-' + postid).val() ),
@@ -555 +872 @@
                 }
         },
 
+        /**
+         * @summary Undoes a image edit action.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number} postid   The post id.
+         * @param {string} nonce    The nonce.
+         *
+         * @returns {void|false} Returns false if the undo button is disabled.
+         */
         undo : function (postid, nonce) {
                 var t = this, button = $('#image-undo-' + postid), elem = $('#imgedit-undone-' + postid),
                         pop = t.intval( elem.val() ) + 1;
@@ -577 +905 @@
                 });
         },
 
+        /**
+         * Reverts a undo action.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number} postid The post id.
+         * @param {string} nonce  The nonce.
+         *
+         * @returns {void}
+         */
         redo : function(postid, nonce) {
                 var t = this, button = $('#image-redo-' + postid), elem = $('#imgedit-undone-' + postid),
                         pop = t.intval( elem.val() ) - 1;
@@ -596 +935 @@
                 });
         },
 
+        /**
+         * @summary Sets the selection for the height and width in pixels.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number} postid The post id.
+         * @param {jQuery} el     The element containing the values.
+         *
+         * @returns {void|boolean} Returns false when the x or y value is lower than 1,
+         *                         void when the value is not numeric or when the operation
+         *                         is successful.
+         */
         setNumSelection : function( postid, el ) {
                 var sel, elX = $('#imgedit-sel-width-' + postid), elY = $('#imgedit-sel-height-' + postid),
                         x = this.intval( elX.val() ), y = this.intval( elY.val() ),
@@ -640 +992 @@
                 }
         },
 
+        /**
+         * Rounds a number to a whole.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number} num The number.
+         *
+         * @returns {number} The number rounded to a whole number.
+         */
         round : function(num) {
                 var s;
                 num = Math.round(num);
@@ -659 +1021 @@
                 return num;
         },
 
+        /**
+         * Sets a locked aspect ratio for the selection.
+         *
+         * @memberof imageEdit
+         * @since    2.9
+         *
+         * @param {number} postid     The post id.
+         * @param {number} n          The ratio to set.
+         * @param {jQuery} el         The element containing the values.
+         *
+         * @returns {void}
+         */
         setRatioSelection : function(postid, n, el) {
                 var sel, r, x = this.intval( $('#imgedit-crop-width-' + postid).val() ),
                         y = this.intval( $('#imgedit-crop-height-' + postid).val() ),
@@ -691 +1065 @@
                 }
         },
 
+        /**
+         * Validates if a value in a jQuery.HTMLElement is numeric.
+         *
+         * @memberof imageEdit
+         * @since    4.6
+         *
+         * @param {jQuery} el The html element.
+         *
+         * @returns {void|boolean} Returns false if the value is not numeric,
+         * void when it is.
+         */
         validateNumeric: function( el ) {
                 if ( ! this.intval( $( el ).val() ) ) {
                         $( el ).val( '' );