WordPress.org

Make WordPress Core

Changeset 39493


Ignore:
Timestamp:
12/04/16 21:34:11 (8 months ago)
Author:
adamsilverstein
Message:

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

Adds JSDoc DocBlocks to the imageEdit methods.

Props: andizer, rensw90.
Fixes #38748.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/js/image-edit.js

    r37966 r39493  
    11/* global imageEditL10n, ajaxurl, confirm */ 
     2/** 
     3 * @summary   The functions necessary for editing images. 
     4 * 
     5 * @since     2.8.5 
     6 */ 
    27 
    38(function($) { 
    4 var imageEdit = window.imageEdit = { 
     9 
     10    /** 
     11     * Contains all the methods to initialise and control the image editor. 
     12     * 
     13     * @namespace imageEdit 
     14     */ 
     15    var imageEdit = window.imageEdit = { 
    516    iasapi : {}, 
    617    hold : {}, 
     
    819    _view : false, 
    920 
     21    /** 
     22     * @summary Converts a value to an integer. 
     23     * 
     24     * @memberof imageEdit 
     25     * @since    2.8.5 
     26     * 
     27     * @param {number} f The float value that should be converted. 
     28     * 
     29     * @return {number} The integer representation from the float value. 
     30     */ 
    1031    intval : function(f) { 
    1132        /* 
     
    1637    }, 
    1738 
     39    /** 
     40     * @summary Adds the disabled attribute and class to a single form element 
     41     *          or a field set. 
     42     * 
     43     * @memberof imageEdit 
     44     * @since    2.9 
     45     * 
     46     * @param {jQuery}         el The element that should be modified. 
     47     * @param {bool|number}    s  The state for the element. If set to true 
     48     *                            the element is disabled, 
     49     *                            otherwise the element is enabled. 
     50     *                            The function is sometimes called with a 0 or 1 
     51     *                            instead of true or false. 
     52     * 
     53     * @returns {void} 
     54     */ 
    1855    setDisabled : function( el, s ) { 
    1956        /* 
     
    3067    }, 
    3168 
     69    /** 
     70     * @summary Initializes the image editor. 
     71     * 
     72     * @memberof imageEdit 
     73     * @since    2.9 
     74     * 
     75     * @param {number} postid The post id. 
     76     * 
     77     * @returns {void} 
     78     */ 
    3279    init : function(postid) { 
    3380        var t = this, old = $('#image-editor-' + t.postid), 
     
    4996            var k = e.keyCode; 
    5097 
     98            // Key codes 37 thru 40 are the arrow keys. 
    5199            if ( 36 < k && k < 41 ) { 
    52100                $(this).blur(); 
    53101            } 
    54102 
     103            // The key code 13 is the enter key. 
    55104            if ( 13 === k ) { 
    56105                e.preventDefault(); 
     
    61110    }, 
    62111 
     112    /** 
     113     * @summary Toggles the wait/load icon in the editor. 
     114     * 
     115     * @memberof imageEdit 
     116     * @since    2.9 
     117     * 
     118     * @param {number} postid The post id. 
     119     * @param {number} toggle Is 0 or 1, fades the icon in then 1 and out when 0. 
     120     * 
     121     * @returns {void} 
     122     */ 
    63123    toggleEditor : function(postid, toggle) { 
    64124        var wait = $('#imgedit-wait-' + postid); 
     
    71131    }, 
    72132 
     133    /** 
     134     * @summary Shows or hides the image edit help box. 
     135     * 
     136     * @memberof imageEdit 
     137     * @since    2.9 
     138     * 
     139     * @param {HTMLElement} el The element to create the help window in. 
     140     * 
     141     * @returns {boolean} Always returns false. 
     142     */ 
    73143    toggleHelp : function(el) { 
    74144        var $el = $( el ); 
     
    80150    }, 
    81151 
     152    /** 
     153     * @summary Gets the value from the image edit target. 
     154     * 
     155     * The image edit target contains the image sizes where the (possible) changes 
     156     * have to be applied to. 
     157     * 
     158     * @memberof imageEdit 
     159     * @since    2.9 
     160     * 
     161     * @param {number} postid The post id. 
     162     * 
     163     * @returns {string} The value from the imagedit-save-target input field when available, 
     164     *                   or 'full' when not available. 
     165     */ 
    82166    getTarget : function(postid) { 
    83167        return $('input[name="imgedit-target-' + postid + '"]:checked', '#imgedit-save-target-' + postid).val() || 'full'; 
    84168    }, 
    85169 
     170    /** 
     171     * @summary Recalculates the height or width and keeps the original aspect ratio. 
     172     * 
     173     * If the original image size is exceeded a red exclamation mark is shown. 
     174     * 
     175     * @memberof imageEdit 
     176     * @since    2.9 
     177     * 
     178     * @param {number}         postid The current post id. 
     179     * @param {number}         x      Is 0 when it applies the y-axis 
     180     *                                and 1 when applicable for the x-axis. 
     181     * @param {jQuery}         el     Element. 
     182     * 
     183     * @returns {void} 
     184     */ 
    86185    scaleChanged : function( postid, x, el ) { 
    87186        var w = $('#imgedit-scale-width-' + postid), h = $('#imgedit-scale-height-' + postid), 
     
    107206    }, 
    108207 
     208    /** 
     209     * @summary Gets the selected aspect ratio. 
     210     * 
     211     * @memberof imageEdit 
     212     * @since    2.9 
     213     * 
     214     * @param {number} postid The post id. 
     215     * 
     216     * @returns {string} The aspect ratio. 
     217     */ 
    109218    getSelRatio : function(postid) { 
    110219        var x = this.hold.w, y = this.hold.h, 
     
    123232    }, 
    124233 
     234    /** 
     235     * @summary Removes the last action from the image edit history 
     236     * The history consist of (edit) actions performed on the image. 
     237     * 
     238     * @memberof imageEdit 
     239     * @since    2.9 
     240     * 
     241     * @param {number} postid  The post id. 
     242     * @param {number} setSize 0 or 1, when 1 the image resets to its original size. 
     243     * 
     244     * @returns {string} JSON string containing the history or an empty string if no history exists. 
     245     */ 
    125246    filterHistory : function(postid, setSize) { 
    126         // apply undo state to history 
     247        // Apply undo state to history. 
    127248        var history = $('#imgedit-history-' + postid).val(), pop, n, o, i, op = []; 
    128249 
    129250        if ( history !== '' ) { 
     251            // Read the JSON string with the image edit history. 
    130252            history = JSON.parse(history); 
    131253            pop = this.intval( $('#imgedit-undone-' + postid).val() ); 
     
    137259            } 
    138260 
     261            // Reset size to it's original state. 
    139262            if ( setSize ) { 
    140263                if ( !history.length ) { 
     
    144267                } 
    145268 
    146                 // restore 
     269                // Restore original 'o'. 
    147270                o = history[history.length - 1]; 
     271 
     272                // c = 'crop', r = 'rotate', f = 'flip' 
    148273                o = o.c || o.r || o.f || false; 
    149274 
    150275                if ( o ) { 
     276                    // fw = Full image width 
    151277                    this.hold.w = o.fw; 
     278                    // fh = Full image height 
    152279                    this.hold.h = o.fh; 
    153280                } 
    154281            } 
    155282 
    156             // filter the values 
     283            // Filter the last step/action from the history. 
    157284            for ( n in history ) { 
    158285                i = history[n]; 
     
    169296        return ''; 
    170297    }, 
    171  
     298    /** 
     299     * @summary Binds the necessary events to the image. 
     300     * 
     301     * When the image source is reloaded the image will be reloaded. 
     302     * 
     303     * @memberof imageEdit 
     304     * @since    2.9 
     305     * 
     306     * @param {number}   postid   The post id. 
     307     * @param {string}   nonce    The nonce to verify the request. 
     308     * @param {function} callback Function to execute when the image is loaded. 
     309     * 
     310     * @returns {void} 
     311     */ 
    172312    refreshEditor : function(postid, nonce, callback) { 
    173313        var t = this, data, img; 
     
    189329                    historyObj; 
    190330 
     331                // Checks if there already is some image-edit history. 
    191332                if ( '' !== event.data.history ) { 
    192333                    historyObj = JSON.parse( event.data.history ); 
     
    231372            .attr('src', ajaxurl + '?' + $.param(data)); 
    232373    }, 
    233  
     374    /** 
     375     * @summary Performs an image edit action. 
     376     * 
     377     * @memberof imageEdit 
     378     * @since    2.9 
     379     * 
     380     * @param  {number}  postid The post id. 
     381     * @param  {string}  nonce  The nonce to verify the request. 
     382     * @param  {string}  action The action to perform on the image. 
     383     *                          The possible actions are: "scale" and "restore". 
     384     * 
     385     * @returns {boolean|void} Executes a post request that refreshes the page 
     386     *                         when the action is performed. 
     387     *                         Returns false if a invalid action is given, 
     388     *                         or when the action cannot be performed. 
     389     */ 
    234390    action : function(postid, nonce, action) { 
    235391        var t = this, data, w, h, fw, fh; 
     
    283439    }, 
    284440 
     441    /** 
     442     * @summary Stores the changes that are made to the image. 
     443     * 
     444     * @memberof imageEdit 
     445     * @since    2.9 
     446     * 
     447     * @param {number}  postid   The post id to get the image from the database. 
     448     * @param {string}  nonce    The nonce to verify the request. 
     449     * 
     450     * @returns {boolean|void}  If the actions are successfully saved a response message is shown. 
     451     *                          Returns false if there is no image editing history, 
     452     *                          thus there are not edit-actions performed on the image. 
     453     */ 
    285454    save : function(postid, nonce) { 
    286455        var data, 
     
    303472            'do': 'save' 
    304473        }; 
    305  
     474        // Post the image edit data to the backend. 
    306475        $.post(ajaxurl, data, function(r) { 
     476            // Read the response. 
    307477            var ret = JSON.parse(r); 
    308478 
     479            // If a response is returned, close the editor and show an error. 
    309480            if ( ret.error ) { 
    310481                $('#imgedit-response-' + postid).html('<div class="error"><p>' + ret.error + '</p></div>'); 
     
    333504    }, 
    334505 
     506    /** 
     507     * @summary Creates the image edit window. 
     508     * 
     509     * @memberof imageEdit 
     510     * @since    2.9 
     511     * 
     512     * @param {number} postid   The post id for the image. 
     513     * @param {string} nonce    The nonce to verify the request. 
     514     * @param {object} view     The image editor view to be used for the editing. 
     515     * 
     516     * @returns {void|promise} Either returns void if the button was already activated 
     517     *                         or returns an instance of the image editor, wrapped in a promise. 
     518     */ 
    335519    open : function( postid, nonce, view ) { 
    336520        this._view = view; 
     
    377561    }, 
    378562 
     563    /** 
     564     * @summary Initializes the cropping tool and sets a default cropping selection. 
     565     * 
     566     * @memberof imageEdit 
     567     * @since    2.9 
     568     * 
     569     * @param {number} postid The post id. 
     570     * 
     571     * @returns {void} 
     572     */ 
    379573    imgLoaded : function(postid) { 
    380574        var img = $('#image-preview-' + postid), parent = $('#imgedit-crop-' + postid); 
     
    387581    }, 
    388582 
     583    /** 
     584     * @summary Initializes the cropping tool. 
     585     * 
     586     * @memberof imageEdit 
     587     * @since    2.9 
     588     * 
     589     * @param {number}      postid The post id. 
     590     * @param {HTMLElement} image  The preview image. 
     591     * @param {HTMLElement} parent The preview image container. 
     592     * 
     593     * @returns {void} 
     594     */ 
    389595    initCrop : function(postid, image, parent) { 
    390596        var t = this, 
     
    401607            minHeight: 3, 
    402608 
     609            /** 
     610             * @summary Sets the CSS styles and binds events for locking the aspect ratio. 
     611             * 
     612             * @param {jQuery} img The preview image. 
     613             */ 
    403614            onInit: function( img ) { 
    404                 // Ensure that the imgareaselect wrapper elements are position:absolute 
     615                // Ensure that the imgAreaSelect wrapper elements are position:absolute. 
    405616                // (even if we're in a position:fixed modal) 
    406617                $img = $( img ); 
    407618                $img.next().css( 'position', 'absolute' ) 
    408619                    .nextAll( '.imgareaselect-outer' ).css( 'position', 'absolute' ); 
    409  
     620                /** 
     621                 * @summary Binds mouse down event to the cropping container. 
     622                 * 
     623                 * @returns {void} 
     624                 */ 
    410625                parent.children().mousedown(function(e){ 
    411626                    var ratio = false, sel, defRatio; 
     
    423638            }, 
    424639 
     640            /** 
     641             * @summary Event triggered when starting a selection. 
     642             * 
     643             * @returns {void} 
     644             */ 
    425645            onSelectStart: function() { 
    426646                imageEdit.setDisabled($('#imgedit-crop-sel-' + postid), 1); 
    427647            }, 
    428  
     648            /** 
     649             * @summary Event triggered when the selection is ended. 
     650             * 
     651             * @param {object} img jQuery object representing the image. 
     652             * @param {object} c   The selection. 
     653             * 
     654             * @returns {object} 
     655             */ 
    429656            onSelectEnd: function(img, c) { 
    430657                imageEdit.setCropSelection(postid, c); 
    431658            }, 
    432659 
     660            /** 
     661             * @summary Event triggered when the selection changes. 
     662             * 
     663             * @param {object} img jQuery object representing the image. 
     664             * @param {object} c   The selection. 
     665             * 
     666             * @returns {void} 
     667             */ 
    433668            onSelectChange: function(img, c) { 
    434669                var sizer = imageEdit.hold.sizer; 
     
    439674    }, 
    440675 
     676    /** 
     677     * @summary Stores the current crop selection. 
     678     * 
     679     * @memberof imageEdit 
     680     * @since    2.9 
     681     * 
     682     * @param {number} postid The post id. 
     683     * @param {object} c      The selection. 
     684     * 
     685     * @returns {boolean} 
     686     */ 
    441687    setCropSelection : function(postid, c) { 
    442688        var sel; 
     
    458704    }, 
    459705 
     706 
     707    /** 
     708     * @summary Closes the image editor. 
     709     * 
     710     * @memberof imageEdit 
     711     * @since    2.9 
     712     * 
     713     * @param {number}  postid The post id. 
     714     * @param {bool}    warn   Warning message. 
     715     * 
     716     * @returns {void|bool} Returns false if there is a warning. 
     717     */ 
    460718    close : function(postid, warn) { 
    461719        warn = warn || false; 
     
    488746    }, 
    489747 
     748    /** 
     749     * @summary Checks if the image edit history is saved. 
     750     * 
     751     * @memberof imageEdit 
     752     * @since    2.9 
     753     * 
     754     * @param {number} postid The post id. 
     755     * 
     756     * @returns {boolean} Returns true if the history is not saved. 
     757     */ 
    490758    notsaved : function(postid) { 
    491759        var h = $('#imgedit-history-' + postid).val(), 
     
    502770    }, 
    503771 
     772    /** 
     773     * @summary Adds an image edit action to the history. 
     774     * 
     775     * @memberof imageEdit 
     776     * @since    2.9 
     777     * 
     778     * @param {object} op     The original position. 
     779     * @param {number} postid The post id. 
     780     * @param {string} nonce  The nonce. 
     781     * 
     782     * @returns {void} 
     783     */ 
    504784    addStep : function(op, postid, nonce) { 
    505785        var t = this, elem = $('#imgedit-history-' + postid), 
     
    523803    }, 
    524804 
     805    /** 
     806     * @summary Rotates the image. 
     807     * 
     808     * @memberof imageEdit 
     809     * @since    2.9 
     810     * 
     811     * @param {string} angle  The angle the image is rotated with. 
     812     * @param {number} postid The post id. 
     813     * @param {string} nonce  The nonce. 
     814     * @param {object} t      The target element. 
     815     * 
     816     * @returns {boolean} 
     817     */ 
    525818    rotate : function(angle, postid, nonce, t) { 
    526819        if ( $(t).hasClass('disabled') ) { 
     
    531824    }, 
    532825 
     826    /** 
     827     * @summary Flips the image. 
     828     * 
     829     * @memberof imageEdit 
     830     * @since    2.9 
     831     * 
     832     * @param {number} axis   The axle the image is flipped on. 
     833     * @param {number} postid The post id. 
     834     * @param {string} nonce  The nonce. 
     835     * @param {object} t      The target element. 
     836     * 
     837     * @returns {boolean} 
     838     */ 
    533839    flip : function (axis, postid, nonce, t) { 
    534840        if ( $(t).hasClass('disabled') ) { 
     
    539845    }, 
    540846 
     847    /** 
     848     * @summary Crops the image. 
     849     * 
     850     * @memberof imageEdit 
     851     * @since    2.9 
     852     * 
     853     * @param {number} postid The post id. 
     854     * @param {string} nonce  The nonce. 
     855     * @param {object} t      The target object. 
     856     * 
     857     * @returns {void|boolean} Returns false if the crop button is disabled. 
     858     */ 
    541859    crop : function (postid, nonce, t) { 
    542860        var sel = $('#imgedit-selection-' + postid).val(), 
     
    556874    }, 
    557875 
     876    /** 
     877     * @summary Undoes an image edit action. 
     878     * 
     879     * @memberof imageEdit 
     880     * @since    2.9 
     881     * 
     882     * @param {number} postid   The post id. 
     883     * @param {string} nonce    The nonce. 
     884     * 
     885     * @returns {void|false} Returns false if the undo button is disabled. 
     886     */ 
    558887    undo : function (postid, nonce) { 
    559888        var t = this, button = $('#image-undo-' + postid), elem = $('#imgedit-undone-' + postid), 
     
    578907    }, 
    579908 
     909    /** 
     910     * Reverts a undo action. 
     911     * 
     912     * @memberof imageEdit 
     913     * @since    2.9 
     914     * 
     915     * @param {number} postid The post id. 
     916     * @param {string} nonce  The nonce. 
     917     * 
     918     * @returns {void} 
     919     */ 
    580920    redo : function(postid, nonce) { 
    581921        var t = this, button = $('#image-redo-' + postid), elem = $('#imgedit-undone-' + postid), 
     
    597937    }, 
    598938 
     939    /** 
     940     * @summary Sets the selection for the height and width in pixels. 
     941     * 
     942     * @memberof imageEdit 
     943     * @since    2.9 
     944     * 
     945     * @param {number} postid The post id. 
     946     * @param {jQuery} el     The element containing the values. 
     947     * 
     948     * @returns {void|boolean} Returns false when the x or y value is lower than 1, 
     949     *                         void when the value is not numeric or when the operation 
     950     *                         is successful. 
     951     */ 
    599952    setNumSelection : function( postid, el ) { 
    600953        var sel, elX = $('#imgedit-sel-width-' + postid), elY = $('#imgedit-sel-height-' + postid), 
     
    641994    }, 
    642995 
     996    /** 
     997     * Rounds a number to a whole. 
     998     * 
     999     * @memberof imageEdit 
     1000     * @since    2.9 
     1001     * 
     1002     * @param {number} num The number. 
     1003     * 
     1004     * @returns {number} The number rounded to a whole number. 
     1005     */ 
    6431006    round : function(num) { 
    6441007        var s; 
     
    6601023    }, 
    6611024 
     1025    /** 
     1026     * Sets a locked aspect ratio for the selection. 
     1027     * 
     1028     * @memberof imageEdit 
     1029     * @since    2.9 
     1030     * 
     1031     * @param {number} postid     The post id. 
     1032     * @param {number} n          The ratio to set. 
     1033     * @param {jQuery} el         The element containing the values. 
     1034     * 
     1035     * @returns {void} 
     1036     */ 
    6621037    setRatioSelection : function(postid, n, el) { 
    6631038        var sel, r, x = this.intval( $('#imgedit-crop-width-' + postid).val() ), 
     
    6921067    }, 
    6931068 
     1069    /** 
     1070     * Validates if a value in a jQuery.HTMLElement is numeric. 
     1071     * 
     1072     * @memberof imageEdit 
     1073     * @since    4.6 
     1074     * 
     1075     * @param {jQuery} el The html element. 
     1076     * 
     1077     * @returns {void|boolean} Returns false if the value is not numeric, 
     1078     *                         void when it is. 
     1079     */ 
    6941080    validateNumeric: function( el ) { 
    6951081        if ( ! this.intval( $( el ).val() ) ) { 
Note: See TracChangeset for help on using the changeset viewer.