WordPress.org
Get WordPress

Make WordPress Core

Changeset 39493


Ignore:
Timestamp:
12/04/2016 09:34:11 PM (8 years 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.