Upstream/WordPress
1
0
Fork 0
mirror of https://github.com/WordPress/WordPress.git synced 2024-06-28 07:45:02 +02:00
Code Issues Projects Releases Wiki Activity

Docs: Add inline documentation for image-edit.js.

Browse Source 
Adds JSDoc DocBlocks to the imageEdit methods.

Props: andizer, rensw90.
Fixes #38748.

Built from https://develop.svn.wordpress.org/trunk@39493


git-svn-id: http://core.svn.wordpress.org/trunk@39433 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Adam Silverstein 2016-12-04 21:35:40 +00:00
parent e72d3d6b5d
commit 113833953d
2 changed files with 397 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

406
wp-admin/js/image-edit.js
View File

@ -1,12 +1,33 @@
/* 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 that 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,
@ -15,6 +36,22 @@ var imageEdit = window.imageEdit = {
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,
* otherwise 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,6 +66,16 @@ var imageEdit = window.imageEdit = {
}
},
/**
* @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,10 +95,12 @@ var imageEdit = window.imageEdit = {
$('input[type="text"]', '#imgedit-panel-' + postid).keypress(function(e) {
var k = e.keyCode;
// Key codes 37 thru 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,6 +109,17 @@ var imageEdit = window.imageEdit = {
});
},
/**
* @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,6 +130,16 @@ var imageEdit = window.imageEdit = {
}
},
/**
* @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,10 +149,39 @@ var imageEdit = window.imageEdit = {
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,6 +205,16 @@ var imageEdit = window.imageEdit = {
}
},
/**
* @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,11 +231,24 @@ var imageEdit = window.imageEdit = {
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,6 +258,7 @@ var imageEdit = window.imageEdit = {
}
}
// Reset size to it's original state.
if ( setSize ) {
if ( !history.length ) {
this.hold.w = this.hold.ow;
@ -143,17 +266,21 @@ var imageEdit = window.imageEdit = {
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,7 +295,20 @@ var imageEdit = window.imageEdit = {
}
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 to execute when the image is loaded.
*
* @returns {void}
*/
refreshEditor : function(postid, nonce, callback) {
var t = this, data, img;
@ -188,6 +328,7 @@ var imageEdit = window.imageEdit = {
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,7 +371,22 @@ var imageEdit = window.imageEdit = {
})
.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,6 +438,19 @@ var imageEdit = window.imageEdit = {
});
},
/**
* @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,10 +471,12 @@ var imageEdit = window.imageEdit = {
'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,6 +503,19 @@ var imageEdit = window.imageEdit = {
});
},
/**
* @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,6 +560,16 @@ var imageEdit = window.imageEdit = {
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,6 +580,18 @@ var imageEdit = window.imageEdit = {
$( '.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,13 +606,22 @@ var imageEdit = window.imageEdit = {
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,14 +637,34 @@ var imageEdit = window.imageEdit = {
});
},
/**
* @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 changes.
*
* @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,6 +673,17 @@ var imageEdit = window.imageEdit = {
});
},
/**
* @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,6 +703,18 @@ var imageEdit = window.imageEdit = {
$('#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,6 +745,16 @@ var imageEdit = window.imageEdit = {
},
/**
* @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,6 +769,18 @@ var imageEdit = window.imageEdit = {
return false;
},
/**
* @summary Adds an 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,6 +802,19 @@ var imageEdit = window.imageEdit = {
});
},
/**
* @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,6 +823,19 @@ var imageEdit = window.imageEdit = {
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,6 +844,18 @@ var imageEdit = window.imageEdit = {
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,6 +873,17 @@ var imageEdit = window.imageEdit = {
}
},
/**
* @summary Undoes an 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,6 +906,17 @@ var imageEdit = window.imageEdit = {
});
},
/**
* 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,6 +936,19 @@ var imageEdit = window.imageEdit = {
});
},
/**
* @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,6 +993,16 @@ var imageEdit = window.imageEdit = {
}
},
/**
* 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,6 +1022,18 @@ var imageEdit = window.imageEdit = {
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,6 +1066,17 @@ var imageEdit = window.imageEdit = {
}
},
/**
* 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( '' );

2
wp-includes/version.php
View File

@ -4,7 +4,7 @@
*
* @global string $wp_version
*/
$wp_version = '4.8-alpha-39492';
$wp_version = '4.8-alpha-39493';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.