<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[39493] trunk/src/wp-admin/js/image-edit.js: Docs: Add inline documentation for `image-edit.js`.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta" style="font-size: 105%">
<dt style="float: left; width: 6em; font-weight: bold">Revision</dt> <dd><a style="font-weight: bold" href="https://core.trac.wordpress.org/changeset/39493">39493</a><script type="application/ld+json">{"@context":"http://schema.org","@type":"EmailMessage","description":"Review this Commit","action":{"@type":"ViewAction","url":"https://core.trac.wordpress.org/changeset/39493","name":"Review Commit"}}</script></dd>
<dt style="float: left; width: 6em; font-weight: bold">Author</dt> <dd>adamsilverstein</dd>
<dt style="float: left; width: 6em; font-weight: bold">Date</dt> <dd>2016-12-04 21:34:11 +0000 (Sun, 04 Dec 2016)</dd>
</dl>
<pre style='padding-left: 1em; margin: 2em 0; border-left: 2px solid #ccc; line-height: 1.25; font-size: 105%; font-family: sans-serif'>Docs: Add inline documentation for `image-edit.js`.
Adds JSDoc DocBlocks to the imageEdit methods.
Props: andizer, rensw90.
Fixes <a href="https://core.trac.wordpress.org/ticket/38748">#38748</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpadminjsimageeditjs">trunk/src/wp-admin/js/image-edit.js</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpadminjsimageeditjs"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/src/wp-admin/js/image-edit.js</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/src/wp-admin/js/image-edit.js 2016-12-04 21:20:44 UTC (rev 39492)
+++ trunk/src/wp-admin/js/image-edit.js 2016-12-04 21:34:11 UTC (rev 39493)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -1,12 +1,33 @@
</span><span class="cx" style="display: block; padding: 0 10px"> /* global imageEditL10n, ajaxurl, confirm */
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+/**
+ * @summary The functions necessary for editing images.
+ *
+ * @since 2.8.5
+ */
</ins><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> (function($) {
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">-var imageEdit = window.imageEdit = {
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ /**
+ * Contains all the methods to initialise and control the image editor.
+ *
+ * @namespace imageEdit
+ */
+ var imageEdit = window.imageEdit = {
</ins><span class="cx" style="display: block; padding: 0 10px"> iasapi : {},
</span><span class="cx" style="display: block; padding: 0 10px"> hold : {},
</span><span class="cx" style="display: block; padding: 0 10px"> postid : '',
</span><span class="cx" style="display: block; padding: 0 10px"> _view : false,
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> intval : function(f) {
</span><span class="cx" style="display: block; padding: 0 10px"> /*
</span><span class="cx" style="display: block; padding: 0 10px"> * Bitwise OR operator: one of the obscure ways to truncate floating point figures,
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -15,6 +36,22 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return f | 0;
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> setDisabled : function( el, s ) {
</span><span class="cx" style="display: block; padding: 0 10px"> /*
</span><span class="cx" style="display: block; padding: 0 10px"> * `el` can be a single form element or a fieldset. Before #28864, the disabled state on
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -29,6 +66,16 @@
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @summary Initializes the image editor.
+ *
+ * @memberof imageEdit
+ * @since 2.9
+ *
+ * @param {number} postid The post id.
+ *
+ * @returns {void}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> init : function(postid) {
</span><span class="cx" style="display: block; padding: 0 10px"> var t = this, old = $('#image-editor-' + t.postid),
</span><span class="cx" style="display: block; padding: 0 10px"> x = t.intval( $('#imgedit-x-' + postid).val() ),
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -48,10 +95,12 @@
</span><span class="cx" style="display: block; padding: 0 10px"> $('input[type="text"]', '#imgedit-panel-' + postid).keypress(function(e) {
</span><span class="cx" style="display: block; padding: 0 10px"> var k = e.keyCode;
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Key codes 37 thru 40 are the arrow keys.
</ins><span class="cx" style="display: block; padding: 0 10px"> if ( 36 < k && k < 41 ) {
</span><span class="cx" style="display: block; padding: 0 10px"> $(this).blur();
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // The key code 13 is the enter key.
</ins><span class="cx" style="display: block; padding: 0 10px"> if ( 13 === k ) {
</span><span class="cx" style="display: block; padding: 0 10px"> e.preventDefault();
</span><span class="cx" style="display: block; padding: 0 10px"> e.stopPropagation();
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -60,6 +109,17 @@
</span><span class="cx" style="display: block; padding: 0 10px"> });
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> toggleEditor : function(postid, toggle) {
</span><span class="cx" style="display: block; padding: 0 10px"> var wait = $('#imgedit-wait-' + postid);
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -70,6 +130,16 @@
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> toggleHelp : function(el) {
</span><span class="cx" style="display: block; padding: 0 10px"> var $el = $( el );
</span><span class="cx" style="display: block; padding: 0 10px"> $el
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -79,10 +149,39 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return false;
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> getTarget : function(postid) {
</span><span class="cx" style="display: block; padding: 0 10px"> return $('input[name="imgedit-target-' + postid + '"]:checked', '#imgedit-save-target-' + postid).val() || 'full';
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> scaleChanged : function( postid, x, el ) {
</span><span class="cx" style="display: block; padding: 0 10px"> var w = $('#imgedit-scale-width-' + postid), h = $('#imgedit-scale-height-' + postid),
</span><span class="cx" style="display: block; padding: 0 10px"> warn = $('#imgedit-scale-warn-' + postid), w1 = '', h1 = '';
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -106,6 +205,16 @@
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @summary Gets the selected aspect ratio.
+ *
+ * @memberof imageEdit
+ * @since 2.9
+ *
+ * @param {number} postid The post id.
+ *
+ * @returns {string} The aspect ratio.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> getSelRatio : function(postid) {
</span><span class="cx" style="display: block; padding: 0 10px"> var x = this.hold.w, y = this.hold.h,
</span><span class="cx" style="display: block; padding: 0 10px"> X = this.intval( $('#imgedit-crop-width-' + postid).val() ),
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -122,11 +231,24 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return '1:1';
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> filterHistory : function(postid, setSize) {
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- // apply undo state to history
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Apply undo state to history.
</ins><span class="cx" style="display: block; padding: 0 10px"> var history = $('#imgedit-history-' + postid).val(), pop, n, o, i, op = [];
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> if ( history !== '' ) {
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Read the JSON string with the image edit history.
</ins><span class="cx" style="display: block; padding: 0 10px"> history = JSON.parse(history);
</span><span class="cx" style="display: block; padding: 0 10px"> pop = this.intval( $('#imgedit-undone-' + postid).val() );
</span><span class="cx" style="display: block; padding: 0 10px"> if ( pop > 0 ) {
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -136,6 +258,7 @@
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Reset size to it's original state.
</ins><span class="cx" style="display: block; padding: 0 10px"> if ( setSize ) {
</span><span class="cx" style="display: block; padding: 0 10px"> if ( !history.length ) {
</span><span class="cx" style="display: block; padding: 0 10px"> this.hold.w = this.hold.ow;
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -143,17 +266,21 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return '';
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- // restore
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Restore original 'o'.
</ins><span class="cx" style="display: block; padding: 0 10px"> o = history[history.length - 1];
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ // c = 'crop', r = 'rotate', f = 'flip'
</ins><span class="cx" style="display: block; padding: 0 10px"> o = o.c || o.r || o.f || false;
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> if ( o ) {
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // fw = Full image width
</ins><span class="cx" style="display: block; padding: 0 10px"> this.hold.w = o.fw;
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // fh = Full image height
</ins><span class="cx" style="display: block; padding: 0 10px"> this.hold.h = o.fh;
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- // filter the values
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Filter the last step/action from the history.
</ins><span class="cx" style="display: block; padding: 0 10px"> for ( n in history ) {
</span><span class="cx" style="display: block; padding: 0 10px"> i = history[n];
</span><span class="cx" style="display: block; padding: 0 10px"> if ( i.hasOwnProperty('c') ) {
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -168,7 +295,20 @@
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px"> return '';
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">-
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> refreshEditor : function(postid, nonce, callback) {
</span><span class="cx" style="display: block; padding: 0 10px"> var t = this, data, img;
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -188,6 +328,7 @@
</span><span class="cx" style="display: block; padding: 0 10px"> t = imageEdit,
</span><span class="cx" style="display: block; padding: 0 10px"> historyObj;
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Checks if there already is some image-edit history.
</ins><span class="cx" style="display: block; padding: 0 10px"> if ( '' !== event.data.history ) {
</span><span class="cx" style="display: block; padding: 0 10px"> historyObj = JSON.parse( event.data.history );
</span><span class="cx" style="display: block; padding: 0 10px"> // If last executed action in history is a crop action.
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -230,7 +371,22 @@
</span><span class="cx" style="display: block; padding: 0 10px"> })
</span><span class="cx" style="display: block; padding: 0 10px"> .attr('src', ajaxurl + '?' + $.param(data));
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">-
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> action : function(postid, nonce, action) {
</span><span class="cx" style="display: block; padding: 0 10px"> var t = this, data, w, h, fw, fh;
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -282,6 +438,19 @@
</span><span class="cx" style="display: block; padding: 0 10px"> });
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> save : function(postid, nonce) {
</span><span class="cx" style="display: block; padding: 0 10px"> var data,
</span><span class="cx" style="display: block; padding: 0 10px"> target = this.getTarget(postid),
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -302,10 +471,12 @@
</span><span class="cx" style="display: block; padding: 0 10px"> 'context': $('#image-edit-context').length ? $('#image-edit-context').val() : null,
</span><span class="cx" style="display: block; padding: 0 10px"> 'do': 'save'
</span><span class="cx" style="display: block; padding: 0 10px"> };
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">-
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Post the image edit data to the backend.
</ins><span class="cx" style="display: block; padding: 0 10px"> $.post(ajaxurl, data, function(r) {
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Read the response.
</ins><span class="cx" style="display: block; padding: 0 10px"> var ret = JSON.parse(r);
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // If a response is returned, close the editor and show an error.
</ins><span class="cx" style="display: block; padding: 0 10px"> if ( ret.error ) {
</span><span class="cx" style="display: block; padding: 0 10px"> $('#imgedit-response-' + postid).html('<div class="error"><p>' + ret.error + '</p></div>');
</span><span class="cx" style="display: block; padding: 0 10px"> imageEdit.close(postid);
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -332,6 +503,19 @@
</span><span class="cx" style="display: block; padding: 0 10px"> });
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> open : function( postid, nonce, view ) {
</span><span class="cx" style="display: block; padding: 0 10px"> this._view = view;
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -376,6 +560,16 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return dfd;
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @summary Initializes the cropping tool and sets a default cropping selection.
+ *
+ * @memberof imageEdit
+ * @since 2.9
+ *
+ * @param {number} postid The post id.
+ *
+ * @returns {void}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> imgLoaded : function(postid) {
</span><span class="cx" style="display: block; padding: 0 10px"> var img = $('#image-preview-' + postid), parent = $('#imgedit-crop-' + postid);
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -386,6 +580,18 @@
</span><span class="cx" style="display: block; padding: 0 10px"> $( '.imgedit-wrap .imgedit-help-toggle' ).eq( 0 ).focus();
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> initCrop : function(postid, image, parent) {
</span><span class="cx" style="display: block; padding: 0 10px"> var t = this,
</span><span class="cx" style="display: block; padding: 0 10px"> selW = $('#imgedit-sel-width-' + postid),
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -400,13 +606,22 @@
</span><span class="cx" style="display: block; padding: 0 10px"> minWidth: 3,
</span><span class="cx" style="display: block; padding: 0 10px"> minHeight: 3,
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @summary Sets the CSS styles and binds events for locking the aspect ratio.
+ *
+ * @param {jQuery} img The preview image.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> onInit: function( img ) {
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">- // Ensure that the imgareaselect wrapper elements are position:absolute
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ // Ensure that the imgAreaSelect wrapper elements are position:absolute.
</ins><span class="cx" style="display: block; padding: 0 10px"> // (even if we're in a position:fixed modal)
</span><span class="cx" style="display: block; padding: 0 10px"> $img = $( img );
</span><span class="cx" style="display: block; padding: 0 10px"> $img.next().css( 'position', 'absolute' )
</span><span class="cx" style="display: block; padding: 0 10px"> .nextAll( '.imgareaselect-outer' ).css( 'position', 'absolute' );
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">-
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @summary Binds mouse down event to the cropping container.
+ *
+ * @returns {void}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> parent.children().mousedown(function(e){
</span><span class="cx" style="display: block; padding: 0 10px"> var ratio = false, sel, defRatio;
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -422,14 +637,34 @@
</span><span class="cx" style="display: block; padding: 0 10px"> });
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @summary Event triggered when starting a selection.
+ *
+ * @returns {void}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> onSelectStart: function() {
</span><span class="cx" style="display: block; padding: 0 10px"> imageEdit.setDisabled($('#imgedit-crop-sel-' + postid), 1);
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">-
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @summary Event triggered when the selection is ended.
+ *
+ * @param {object} img jQuery object representing the image.
+ * @param {object} c The selection.
+ *
+ * @returns {object}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> onSelectEnd: function(img, c) {
</span><span class="cx" style="display: block; padding: 0 10px"> imageEdit.setCropSelection(postid, c);
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @summary Event triggered when the selection changes.
+ *
+ * @param {object} img jQuery object representing the image.
+ * @param {object} c The selection.
+ *
+ * @returns {void}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> onSelectChange: function(img, c) {
</span><span class="cx" style="display: block; padding: 0 10px"> var sizer = imageEdit.hold.sizer;
</span><span class="cx" style="display: block; padding: 0 10px"> selW.val( imageEdit.round(c.width / sizer) );
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -438,6 +673,17 @@
</span><span class="cx" style="display: block; padding: 0 10px"> });
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @summary Stores the current crop selection.
+ *
+ * @memberof imageEdit
+ * @since 2.9
+ *
+ * @param {number} postid The post id.
+ * @param {object} c The selection.
+ *
+ * @returns {boolean}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> setCropSelection : function(postid, c) {
</span><span class="cx" style="display: block; padding: 0 10px"> var sel;
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -457,6 +703,18 @@
</span><span class="cx" style="display: block; padding: 0 10px"> $('#imgedit-selection-' + postid).val( JSON.stringify(sel) );
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+
+ /**
+ * @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.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> close : function(postid, warn) {
</span><span class="cx" style="display: block; padding: 0 10px"> warn = warn || false;
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -487,6 +745,16 @@
</span><span class="cx" style="display: block; padding: 0 10px">
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> notsaved : function(postid) {
</span><span class="cx" style="display: block; padding: 0 10px"> var h = $('#imgedit-history-' + postid).val(),
</span><span class="cx" style="display: block; padding: 0 10px"> history = ( h !== '' ) ? JSON.parse(h) : [],
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -501,6 +769,18 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return false;
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> addStep : function(op, postid, nonce) {
</span><span class="cx" style="display: block; padding: 0 10px"> var t = this, elem = $('#imgedit-history-' + postid),
</span><span class="cx" style="display: block; padding: 0 10px"> history = ( elem.val() !== '' ) ? JSON.parse( elem.val() ) : [],
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -522,6 +802,19 @@
</span><span class="cx" style="display: block; padding: 0 10px"> });
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> rotate : function(angle, postid, nonce, t) {
</span><span class="cx" style="display: block; padding: 0 10px"> if ( $(t).hasClass('disabled') ) {
</span><span class="cx" style="display: block; padding: 0 10px"> return false;
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -530,6 +823,19 @@
</span><span class="cx" style="display: block; padding: 0 10px"> this.addStep({ 'r': { 'r': angle, 'fw': this.hold.h, 'fh': this.hold.w }}, postid, nonce);
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> flip : function (axis, postid, nonce, t) {
</span><span class="cx" style="display: block; padding: 0 10px"> if ( $(t).hasClass('disabled') ) {
</span><span class="cx" style="display: block; padding: 0 10px"> return false;
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -538,6 +844,18 @@
</span><span class="cx" style="display: block; padding: 0 10px"> this.addStep({ 'f': { 'f': axis, 'fw': this.hold.w, 'fh': this.hold.h }}, postid, nonce);
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> crop : function (postid, nonce, t) {
</span><span class="cx" style="display: block; padding: 0 10px"> var sel = $('#imgedit-selection-' + postid).val(),
</span><span class="cx" style="display: block; padding: 0 10px"> w = this.intval( $('#imgedit-sel-width-' + postid).val() ),
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -555,6 +873,17 @@
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> undo : function (postid, nonce) {
</span><span class="cx" style="display: block; padding: 0 10px"> var t = this, button = $('#image-undo-' + postid), elem = $('#imgedit-undone-' + postid),
</span><span class="cx" style="display: block; padding: 0 10px"> pop = t.intval( elem.val() ) + 1;
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -577,6 +906,17 @@
</span><span class="cx" style="display: block; padding: 0 10px"> });
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * Reverts a undo action.
+ *
+ * @memberof imageEdit
+ * @since 2.9
+ *
+ * @param {number} postid The post id.
+ * @param {string} nonce The nonce.
+ *
+ * @returns {void}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> redo : function(postid, nonce) {
</span><span class="cx" style="display: block; padding: 0 10px"> var t = this, button = $('#image-redo-' + postid), elem = $('#imgedit-undone-' + postid),
</span><span class="cx" style="display: block; padding: 0 10px"> pop = t.intval( elem.val() ) - 1;
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -596,6 +936,19 @@
</span><span class="cx" style="display: block; padding: 0 10px"> });
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * @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.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> setNumSelection : function( postid, el ) {
</span><span class="cx" style="display: block; padding: 0 10px"> var sel, elX = $('#imgedit-sel-width-' + postid), elY = $('#imgedit-sel-height-' + postid),
</span><span class="cx" style="display: block; padding: 0 10px"> x = this.intval( elX.val() ), y = this.intval( elY.val() ),
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -640,6 +993,16 @@
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * 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.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> round : function(num) {
</span><span class="cx" style="display: block; padding: 0 10px"> var s;
</span><span class="cx" style="display: block; padding: 0 10px"> num = Math.round(num);
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -659,6 +1022,18 @@
</span><span class="cx" style="display: block; padding: 0 10px"> return num;
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * 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}
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> setRatioSelection : function(postid, n, el) {
</span><span class="cx" style="display: block; padding: 0 10px"> var sel, r, x = this.intval( $('#imgedit-crop-width-' + postid).val() ),
</span><span class="cx" style="display: block; padding: 0 10px"> y = this.intval( $('#imgedit-crop-height-' + postid).val() ),
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -691,6 +1066,17 @@
</span><span class="cx" style="display: block; padding: 0 10px"> }
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px">
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ /**
+ * 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.
+ */
</ins><span class="cx" style="display: block; padding: 0 10px"> validateNumeric: function( el ) {
</span><span class="cx" style="display: block; padding: 0 10px"> if ( ! this.intval( $( el ).val() ) ) {
</span><span class="cx" style="display: block; padding: 0 10px"> $( el ).val( '' );
</span></span></pre>
</div>
</div>
</body>
</html>