WordPress.org
Get WordPress

Make WordPress Core

Changeset 26984


Ignore:
Timestamp:
01/20/2014 11:34:57 PM (11 years ago)
Author:
wonderboymusic
Message:

Add initial JSDoc blocks to media-editor.js. The initial blocks are a baseline to work from and invite future iterations. Initial commit is to avoid commits this large in the future.

See #26870.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/js/media-editor.js

    r26945 r26984  
    44// -----------------------------
    55(function($){
    6     // Stores the editors' `wp.media.controller.Frame` instances.
     6    /**
     7     * Stores the editors' `wp.media.controller.Frame` instances.
     8     *
     9     * @static
     10     */
    711    var workflows = {};
    812
     13    /**
     14     * wp.media.string
     15     */
    916    wp.media.string = {
    10         // Joins the `props` and `attachment` objects,
    11         // outputting the proper object format based on the
    12         // attachment's type.
     17        /**
     18         * Joins the `props` and `attachment` objects,
     19         * outputting the proper object format based on the
     20         * attachment's type.
     21         *
     22         * @global wp.media.view.settings.defaultProps
     23         *
     24         * @param {Object} props
     25         * @param {Object} attachment
     26         * @returns {Object} Joined props
     27         */
    1328        props: function( props, attachment ) {
    1429            var link, linkUrl, size, sizes, fallbacks,
    … …  
    2944            props = props ? _.clone( props ) : {};
    3045
    31             if ( attachment && attachment.type )
     46            if ( attachment && attachment.type ) {
    3247                props.type = attachment.type;
     48            }
    3349
    3450            if ( 'image' === props.type ) {
    … …  
    4258
    4359            // All attachment-specific settings follow.
    44             if ( ! attachment )
     60            if ( ! attachment ) {
    4561                return fallbacks( props );
     62            }
    4663
    4764            props.title = props.title || attachment.title;
    4865
    4966            link = props.link || defaultProps.link || getUserSetting( 'urlbutton', 'file' );
    50             if ( 'file' === link || 'embed' === link )
     67            if ( 'file' === link || 'embed' === link ) {
    5168                linkUrl = attachment.url;
    52             else if ( 'post' === link )
     69            } else if ( 'post' === link ) {
    5370                linkUrl = attachment.link;
    54             else if ( 'custom' === link )
     71            } else if ( 'custom' === link ) {
    5572                linkUrl = props.linkUrl;
     73            }
    5674            props.linkUrl = linkUrl || '';
    5775
    … …  
    8098        },
    8199
     100        /**
     101         * Create the markup for a link
     102         *
     103         * @global wp.html.string
     104         *
     105         * @param {Object} props
     106         * @param {Object} attachment
     107         * @returns {string} The link markup
     108         */
    82109        link: function( props, attachment ) {
    83110            var options;
    … …  
    93120            };
    94121
    95             if ( props.rel )
     122            if ( props.rel ) {
    96123                options.attrs.rel = props.rel;
     124            }
    97125
    98126            return wp.html.string( options );
    99127        },
    100 
     128        /**
     129         * Create an Audio shortcode
     130         *
     131         * @param {Object} props
     132         * @param {Object} attachment
     133         * @returns {string} The audio shortcode
     134         */
    101135        audio: function( props, attachment ) {
    102136            return wp.media.string._audioVideo( 'audio', props, attachment );
    103137        },
    104 
     138        /**
     139         * Create a Video shortcode
     140         *
     141         * @param {Object} props
     142         * @param {Object} attachment
     143         * @returns {string} The video shortcode
     144         */
    105145        video: function( props, attachment ) {
    106146            return wp.media.string._audioVideo( 'video', props, attachment );
    107147        },
    108 
     148        /**
     149         * Helper function to create a media shortcode
     150         *
     151         * @access private
     152         *
     153         * @global wp.shortcode
     154         * @global wp.media.view.settings
     155         *
     156         * @param {string} type The shortcode tag name: 'audio' or 'video'.
     157         * @param {Object} props
     158         * @param {Object} attachment
     159         * @returns {string} The media shortcode
     160         */
    109161        _audioVideo: function( type, props, attachment ) {
    110162            var shortcode, html, extension;
    … …  
    117169
    118170            if ( 'video' === type ) {
    119                 if ( attachment.width )
     171                if ( attachment.width ) {
    120172                    shortcode.width = attachment.width;
    121 
    122                 if ( attachment.height )
     173                }
     174
     175                if ( attachment.height ) {
    123176                    shortcode.height = attachment.height;
     177                }
    124178            }
    125179
    … …  
    140194            return html;
    141195        },
    142 
     196        /**
     197         * Create image markup, optionally with a link and/or wrapped in a caption shortcode
     198         *
     199         * @global wp.html
     200         * @global wp.shortcode
     201         *
     202         * @param {Object} props
     203         * @param {Object} attachment
     204         * @returns {string}
     205         */
    143206        image: function( props, attachment ) {
    144207            var img = {},
    … …  
    153216            // Only assign the align class to the image if we're not printing
    154217            // a caption, since the alignment is sent to the shortcode.
    155             if ( props.align && ! props.caption )
     218            if ( props.align && ! props.caption ) {
    156219                classes.push( 'align' + props.align );
    157 
    158             if ( props.size )
     220            }
     221
     222            if ( props.size ) {
    159223                classes.push( 'size-' + props.size );
     224            }
    160225
    161226            img['class'] = _.compact( classes ).join(' ');
    … …  
    185250                shortcode = {};
    186251
    187                 if ( img.width )
     252                if ( img.width ) {
    188253                    shortcode.width = img.width;
    189 
    190                 if ( props.captionId )
     254                }
     255
     256                if ( props.captionId ) {
    191257                    shortcode.id = props.captionId;
    192 
    193                 if ( props.align )
     258                }
     259
     260                if ( props.align ) {
    194261                    shortcode.align = 'align' + props.align;
     262                }
    195263
    196264                html = wp.shortcode.string({
    … …  
    205273    };
    206274
     275    /**
     276     * wp.media.gallery
     277     *
     278     * @type {Object}
     279     */
    207280    wp.media.gallery = (function() {
     281        /**
     282         *
     283         * @static
     284         * @type object
     285         */
    208286        var galleries = {};
    209287
    210288        return {
     289            /**
     290             * @global wp.media.view.settings
     291             */
    211292            defaults: {
    212293                order:      'ASC',
    … …  
    221302            },
    222303
     304            /**
     305             * @global wp.media.query
     306             *
     307             * @param {Object} shortcode
     308             * @returns {Object}
     309             */
    223310            attachments: function( shortcode ) {
    224311                var shortcodeString = shortcode.string(),
    … …  
    228315                delete galleries[ shortcodeString ];
    229316
    230                 if ( result )
     317                if ( result ) {
    231318                    return result;
     319                }
    232320
    233321                // Fill the default shortcode attributes.
    … …  
    239327
    240328                // Mark the `orderby` override attribute.
    241                 if( undefined !== attrs.orderby )
     329                if( undefined !== attrs.orderby ) {
    242330                    attrs._orderByField = attrs.orderby;
    243 
    244                 if ( 'rand' === attrs.orderby )
     331                }
     332                if ( 'rand' === attrs.orderby ) {
    245333                    attrs._orderbyRandom = true;
     334                }
    246335
    247336                // Map the `orderby` attribute to the corresponding model property.
    248                 if ( ! attrs.orderby || /^menu_order(?: ID)?$/i.test( attrs.orderby ) )
     337                if ( ! attrs.orderby || /^menu_order(?: ID)?$/i.test( attrs.orderby ) ) {
    249338                    args.orderby = 'menuOrder';
     339                }
    250340
    251341                // Map the `ids` param to the correct query args.
    … …  
    257347                }
    258348
    259                 if ( attrs.exclude )
     349                if ( attrs.exclude ) {
    260350                    args.post__not_in = attrs.exclude.split(',');
    261 
    262                 if ( ! args.post__in )
     351                }
     352
     353                if ( ! args.post__in ) {
    263354                    args.uploadedTo = attrs.id;
     355                }
    264356
    265357                // Collect the attributes that were not included in `args`.
    … …  
    271363            },
    272364
     365            /**
     366             * @global wp.shortcode
     367             * @global wp.media.model.Attachments
     368             *
     369             * @param {Object} attachments
     370             * @returns {wp.shortcode}
     371             */
    273372            shortcode: function( attachments ) {
    274373                var props = attachments.props.toJSON(),
    … …  
    276375                    shortcode, clone;
    277376
    278                 if ( attachments.gallery )
     377                if ( attachments.gallery ) {
    279378                    _.extend( attrs, attachments.gallery.toJSON() );
     379                }
    280380
    281381                // Convert all gallery shortcodes to use the `ids` property.
    … …  
    285385
    286386                // Copy the `uploadedTo` post ID.
    287                 if ( props.uploadedTo )
     387                if ( props.uploadedTo ) {
    288388                    attrs.id = props.uploadedTo;
     389                }
    289390
    290391                // Check if the gallery is randomly ordered.
    291392                delete attrs.orderby;
    292393
    293                 if ( attrs._orderbyRandom )
     394                if ( attrs._orderbyRandom ) {
    294395                    attrs.orderby = 'rand';
    295                 else if ( attrs._orderByField && attrs._orderByField != 'rand' )
     396                } else if ( attrs._orderByField && attrs._orderByField != 'rand' ) {
    296397                    attrs.orderby = attrs._orderByField;
     398                }
    297399
    298400                delete attrs._orderbyRandom;
    … …  
    301403                // If the `ids` attribute is set and `orderby` attribute
    302404                // is the default value, clear it for cleaner output.
    303                 if ( attrs.ids && 'post__in' === attrs.orderby )
     405                if ( attrs.ids && 'post__in' === attrs.orderby ) {
    304406                    delete attrs.orderby;
     407                }
    305408
    306409                // Remove default attributes from the shortcode.
    … …  
    325428                return shortcode;
    326429            },
    327 
     430            /**
     431             * @global wp.shortcode
     432             * @global wp.media.model.Selection
     433             * @global wp.media.view.l10n
     434             *
     435             * @param {string} content
     436             * @returns {wp.media.view.MediaFrame} A media workflow.
     437             */
    328438            edit: function( content ) {
    329439                var shortcode = wp.shortcode.next( 'gallery', content ),
    … …  
    332442
    333443                // Bail if we didn't match the shortcode or all of the content.
    334                 if ( ! shortcode || shortcode.content !== content )
     444                if ( ! shortcode || shortcode.content !== content ) {
    335445                    return;
     446                }
    336447
    337448                // Ignore the rest of the match object.
    338449                shortcode = shortcode.shortcode;
    339450
    340                 if ( _.isUndefined( shortcode.get('id') ) && ! _.isUndefined( defaultPostId ) )
     451                if ( _.isUndefined( shortcode.get('id') ) && ! _.isUndefined( defaultPostId ) ) {
    341452                    shortcode.set( 'id', defaultPostId );
     453                }
    342454
    343455                attachments = wp.media.gallery.attachments( shortcode );
    … …  
    360472
    361473                // Destroy the previous gallery frame.
    362                 if ( this.frame )
     474                if ( this.frame ) {
    363475                    this.frame.dispose();
     476                }
    364477
    365478                // Store the current gallery frame.
    … …  
    378491    }());
    379492
     493    /**
     494     * wp.media.featuredImage
     495     */
    380496    wp.media.featuredImage = {
     497        /**
     498         * Get the featured image post ID
     499         *
     500         * @global wp.media.view.settings
     501         *
     502         * @returns {wp.media.view.settings.post.featuredImageId|Number}
     503         */
    381504        get: function() {
    382505            return wp.media.view.settings.post.featuredImageId;
    383506        },
    384507
     508        /**
     509         * Set the featured image id, save the post thumbnail data and
     510         * set the HTML in the post meta box to the new featured image.
     511         *
     512         * @global wp.media.view.settings
     513         * @global wp.media.post
     514         *
     515         * @param {number} id
     516         */
    385517        set: function( id ) {
    386518            var settings = wp.media.view.settings;
    … …  
    397529            });
    398530        },
    399 
     531        /**
     532         * The Featured Image workflow
     533         *
     534         * @global wp.media.controller.FeaturedImage
     535         * @global wp.media.view.l10n
     536         *
     537         * @returns {wp.media.view.MediaFrame} A media workflow.
     538         */
    400539        frame: function() {
    401             if ( this._frame )
     540            if ( this._frame ) {
    402541                return this._frame;
     542            }
    403543
    404544            this._frame = wp.media({
    … …  
    416556            return this._frame;
    417557        },
    418 
     558        /**
     559         * @global wp.media.view.settings
     560         */
    419561        select: function() {
    420562            var settings = wp.media.view.settings,
    421563                selection = this.get('selection').single();
    422564
    423             if ( ! settings.post.featuredImageId )
     565            if ( ! settings.post.featuredImageId ) {
    424566                return;
     567            }
    425568
    426569            wp.media.featuredImage.set( selection ? selection.id : -1 );
    427570        },
    428571
     572        /**
     573         * Open the content media manager to the 'featured image' tab when
     574         * the post thumbnail is clicked.
     575         *
     576         * Update the featured image id when the 'remove' link is clicked.
     577         *
     578         * @global wp.media.view.settings
     579         */
    429580        init: function() {
    430             // Open the content media manager to the 'featured image' tab when
    431             // the post thumbnail is clicked.
    432581            $('#postimagediv').on( 'click', '#set-post-thumbnail', function( event ) {
    433582                event.preventDefault();
    … …  
    436585
    437586                wp.media.featuredImage.frame().open();
    438 
    439             // Update the featured image id when the 'remove' link is clicked.
    440587            }).on( 'click', '#remove-post-thumbnail', function() {
    441588                wp.media.view.settings.post.featuredImageId = -1;
    … …  
    446593    $( wp.media.featuredImage.init );
    447594
     595    /**
     596     * wp.media.editor
     597     */
    448598    wp.media.editor = {
     599        /**
     600         * @global tinymce
     601         * @global QTags
     602         *
     603         * @param {string} html
     604         */
    449605        insert: function( html ) {
    450606            var editor,
    … …  
    486642        },
    487643
     644        /**
     645         * @global wp.media.view.l10n
     646         *
     647         * @param {string} id A slug used to identify the workflow.
     648         * @param {Object} [options={}]
     649         *
     650         * @returns {wp.media.view.MediaFrame} A media workflow.
     651         */
    488652        add: function( id, options ) {
    489653            var workflow = this.get( id );
    490654
    491             if ( workflow ) // only add once: if exists return existing
     655            // only add once: if exists return existing
     656            if ( workflow ) {
    492657                return workflow;
     658            }
    493659
    494660            workflow = workflows[ id ] = wp.media( _.defaults( options || {}, {
    … …  
    544710                    });
    545711
    546                     if ( 'none' === embed.link )
     712                    if ( 'none' === embed.link ) {
    547713                        embed.linkUrl = '';
    548                     else if ( 'file' === embed.link )
     714                    } else if ( 'file' === embed.link ) {
    549715                        embed.linkUrl = embed.url;
     716                    }
    550717
    551718                    this.insert( wp.media.string.image( embed ) );
    … …  
    558725        },
    559726
     727        /**
     728         * Determines the proper current workflow id
     729         *
     730         * @global wpActiveEditor
     731         * @global tinymce
     732         *
     733         * @param {string} id
     734         * @returns {wpActiveEditor|String|tinymce.activeEditor.id}
     735         */
    560736        id: function( id ) {
    561             if ( id )
     737            if ( id ) {
    562738                return id;
     739            }
    563740
    564741            // If an empty `id` is provided, default to `wpActiveEditor`.
    … …  
    566743
    567744            // If that doesn't work, fall back to `tinymce.activeEditor.id`.
    568             if ( ! id && typeof tinymce !== 'undefined' && tinymce.activeEditor )
     745            if ( ! id && typeof tinymce !== 'undefined' && tinymce.activeEditor ) {
    569746                id = tinymce.activeEditor.id;
     747            }
    570748
    571749            // Last but not least, fall back to the empty string.
    … …  
    573751            return id;
    574752        },
    575 
     753        /**
     754         * Return the workflow specified by id
     755         *
     756         * @param {string} id
     757         * @returns {wp.media.view.MediaFrame} A media workflow.
     758         */
    576759        get: function( id ) {
    577760            id = this.id( id );
    578761            return workflows[ id ];
    579762        },
    580 
     763        /**
     764         * Remove the workflow represented by id from the workflow cache
     765         *
     766         * @param {string} id
     767         */
    581768        remove: function( id ) {
    582769            id = this.id( id );
    … …  
    585772
    586773        send: {
     774            /**
     775             * @global wp.media.view.settings
     776             * @global wp.media.post
     777             *
     778             * @param {Object} props
     779             * @param {Object} attachment
     780             * @returns {Promise}
     781             */
    587782            attachment: function( props, attachment ) {
    588783                var caption = attachment.caption,
    … …  
    590785
    591786                // If captions are disabled, clear the caption.
    592                 if ( ! wp.media.view.settings.captions )
     787                if ( ! wp.media.view.settings.captions ) {
    593788                    delete attachment.caption;
     789                }
    594790
    595791                props = wp.media.string.props( props, attachment );
    … …  
    601797                };
    602798
    603                 if ( props.linkUrl )
     799                if ( props.linkUrl ) {
    604800                    options.url = props.linkUrl;
     801                }
    605802
    606803                if ( 'image' === attachment.type ) {
    … …  
    631828                });
    632829            },
    633 
     830            /**
     831             * @global wp.media.view.settings
     832             *
     833             * @param {Object} embed
     834             * @returns {Promise}
     835             */
    634836            link: function( embed ) {
    635837                return wp.media.post( 'send-link-to-editor', {
    … …  
    642844            }
    643845        },
    644 
     846        /**
     847         * @param {string} id
     848         * @param {Object} options
     849         * @returns {wp.media.view.MediaFrame}
     850         */
    645851        open: function( id, options ) {
    646852            var workflow, editor;
    … …  
    663869
    664870            // Redo workflow if state has changed
    665             if ( ! workflow || ( workflow.options && options.state !== workflow.options.state ) )
     871            if ( ! workflow || ( workflow.options && options.state !== workflow.options.state ) ) {
    666872                workflow = this.add( id, options );
     873            }
    667874
    668875            return workflow.open();
    669876        },
    670877
     878        /**
     879         * Bind click event for .insert-media using event delegation
     880         *
     881         * @global wp.media.view.l10n
     882         */
    671883        init: function() {
    672884            $(document.body).on( 'click', '.insert-media', function( event ) {
Note: See TracChangeset for help on using the changeset viewer.