WordPress.org
Get WordPress

Make WordPress Core

Ticket #28459: 28459.8.diff

File 28459.8.diff, 16.6 KB (added by ericlewis, 12 years ago)

  • src/wp-includes/js/media-models.js 

    diff --git src/wp-includes/js/media-models.js src/wp-includes/js/media-models.js
index cba928d..c8b9b3f 100644
    window.wp = window.wp || {};  
    6565         */
    6666
    6767        /**
    68          * A basic comparator.
     68         * A basic equality comparator for Backbone models.
     69         *
     70         * Used to order models within a collection - @see wp.media.model.Attachments.comparator().
    6971         *
    7072         * @param  {mixed}  a  The primary parameter to compare.
    7173         * @param  {mixed}  b  The primary parameter to compare.
    … … window.wp = window.wp || {};  
    8789                /**
    8890                 * media.template( id )
    8991                 *
    90                  * Fetches a template by id.
     92                 * Fetch a JavaScript template for an id, and return a templating function for it.
     93                 *
    9194                 * See wp.template() in `wp-includes/js/wp-util.js`.
    9295                 *
    9396                 * @borrows wp.template as template
    … … window.wp = window.wp || {};  
    197200        /**
    198201         * wp.media.model.Attachment
    199202         *
    200          * @constructor
     203         * @class
    201204         * @augments Backbone.Model
    202205         */
    203206        Attachment = media.model.Attachment = Backbone.Model.extend({
    … … window.wp = window.wp || {};  
    329332                }
    330333        }, {
    331334                /**
    332                  * Add a model to the end of the static 'all' collection and return it.
     335                 * Create a new model on the static 'all' attachments collection and return it.
    333336                 *
    334337                 * @static
    335338                 * @param {Object} attrs
    … … window.wp = window.wp || {};  
    339342                        return Attachments.all.push( attrs );
    340343                },
    341344                /**
    342                  * Retrieve a model, or add it to the end of the static 'all' collection before returning it.
     345                 * Create a new model on the static 'all' attachments collection and return it.
     346                 *
     347                 * If this function has already been called for the id,
     348                 * it returns the specified attachment.
    343349                 *
    344350                 * @static
    345351                 * @param {string} id A string used to identify a model.
    … … window.wp = window.wp || {};  
    354360        /**
    355361         * wp.media.model.PostImage
    356362         *
    357          * @constructor
     363         * An instance of an image that's been embedded into a post.
     364         *
     365         * Used in the embedded image attachment display settings modal - @see wp.media.view.MediaFrame.ImageDetails.
     366         *
     367         * @class
    358368         * @augments Backbone.Model
     369         *
     370         * @param {int} [attributes]               Initial model attributes.
     371         * @param {int} [attributes.attachment_id] ID of the attachment.
    359372         **/
    360373        PostImage = media.model.PostImage = Backbone.Model.extend({
    361374
    … … window.wp = window.wp || {};  
    497510        /**
    498511         * wp.media.model.Attachments
    499512         *
    500          * @constructor
     513         * A collection of attachments.
     514         *
     515         * This collection has no persistence with the server without supplying
     516         * 'options.props.query = true', which will mirror the collection
     517         * to an Attachments Query collection - @see wp.media.model.Attachments.mirror().
     518         *
     519         * @class
    501520         * @augments Backbone.Collection
     521         *
     522         * @param {array}  [models]                Models to initialize with the collection.
     523         * @param {object} [options]               Options hash for the collection.
     524         * @param {string} [options.props]         Options hash for the initial query properties.
     525         * @param {string} [options.props.order]   Initial order (ASC or DESC) for the collection.
     526         * @param {string} [options.props.orderby] Initial attribute key to order the collection by.
     527         * @param {string} [options.props.query]   Whether the collection is linked to an attachments query.
     528         * @param {string} [options.observe]
     529         * @param {string} [options.filters]
     530         *
    502531         */
    503532        Attachments = media.model.Attachments = Backbone.Collection.extend({
    504533                /**
    … … window.wp = window.wp || {};  
    522551                        this.props.on( 'change:orderby', this._changeOrderby, this );
    523552                        this.props.on( 'change:query',   this._changeQuery,   this );
    524553
    525                         // Set the `props` model and fill the default property values.
    526554                        this.props.set( _.defaults( options.props || {} ) );
    527555
    528                         // Observe another `Attachments` collection if one is provided.
    529556                        if ( options.observe ) {
    530557                                this.observe( options.observe );
    531558                        }
    532559                },
    533560                /**
    534                  * Automatically sort the collection when the order changes.
     561                 * Sort the collection when the order attribute changes.
    535562                 *
    536563                 * @access private
    537564                 */
    … … window.wp = window.wp || {};  
    625652
    626653                validateDestroyed: false,
    627654                /**
     655                 * Checks whether an attachment is valid.
     656                 *
    628657                 * @param {wp.media.model.Attachment} attachment
    629658                 * @returns {Boolean}
    630659                 */
    … … window.wp = window.wp || {};  
    637666                        }, this );
    638667                },
    639668                /**
     669                 * Add or remove an attachment to the collection depending on its validity.
     670                 *
    640671                 * @param {wp.media.model.Attachment} attachment
    641672                 * @param {Object} options
    642673                 * @returns {wp.media.model.Attachments} Returns itself to allow chaining
    … … window.wp = window.wp || {};  
    655686                },
    656687
    657688                /**
     689                 * Add or remove all attachments from another collection depending on each one's validity.
     690                 *
    658691                 * @param {wp.media.model.Attachments} attachments
    659692                 * @param {object} [options={}]
    660693                 *
    … … window.wp = window.wp || {};  
    675708                        return this;
    676709                },
    677710                /**
    678                  * @param {wp.media.model.Attachments} attachments
    679                  * @returns {wp.media.model.Attachments} Returns itself to allow chaining
     711                 * Start observing another attachments collection change events
     712                 * and replicate them on this collection.
     713                 *
     714                 * @param {wp.media.model.Attachments} The attachments collection to observe.
     715                 * @returns {wp.media.model.Attachments} Returns itself to allow chaining.
    680716                 */
    681717                observe: function( attachments ) {
    682718                        this.observers = this.observers || [];
    … … window.wp = window.wp || {};  
    688724                        return this;
    689725                },
    690726                /**
    691                  * @param {wp.media.model.Attachments} attachments
     727                 * Stop replicating collection change events from another attachments collection.
     728                 *
     729                 * @param {wp.media.model.Attachments} The attachments collection to stop observing.
    692730                 * @returns {wp.media.model.Attachments} Returns itself to allow chaining
    693731                 */
    694732                unobserve: function( attachments ) {
    … … window.wp = window.wp || {};  
    734772                        return this.validateAll( attachments, options );
    735773                },
    736774                /**
    737                  * @param {wp.media.model.Attachments} attachments
     775                 * Start mirroring another attachments collection, clearing out any models already
     776                 * in the collection.
     777                 *
     778                 * @param {wp.media.model.Attachments} The attachments collection to mirror.
    738779                 * @returns {wp.media.model.Attachments} Returns itself to allow chaining
    739780                 */
    740781                mirror: function( attachments ) {
    … … window.wp = window.wp || {};  
    752793
    753794                        return this;
    754795                },
     796                /**
     797                 * Stop mirroring another attachments collection.
     798                 */
    755799                unmirror: function() {
    756800                        if ( ! this.mirroring ) {
    757801                                return;
    … … window.wp = window.wp || {};  
    761805                        delete this.mirroring;
    762806                },
    763807                /**
    764                  * @param {Object} options
     808                 * Retrive more attachments from the server for the collection.
     809                 *
     810                 * Only works if the collection is mirroring a Query Attachments collection,
     811                 * and forwards to its `more` method. This collection class doesn't have
     812                 * server persistence by itself.
     813                 *
     814                 * @param {object} options
    765815                 * @returns {Promise}
    766816                 */
    767817                more: function( options ) {
    … … window.wp = window.wp || {};  
    784834                        return deferred.promise();
    785835                },
    786836                /**
    787                  * @returns {Boolean}
     837                 * Whether there are more attachments that haven't been sync'd from the server
     838                 * that match the collection's query.
     839                 *
     840                 * Only works if the collection is mirroring a Query Attachments collection,
     841                 * and forwards to its `hasMore` method. This collection class doesn't have
     842                 * server persistence by itself.
     843                 *
     844                 * @returns {boolean}
    788845                 */
    789846                hasMore: function() {
    790847                        return this.mirroring ? this.mirroring.hasMore() : false;
    791848                },
    792849                /**
    793                  * Overrides Backbone.Collection.parse
     850                 * A custom AJAX-response parser.
     851                 *
     852                 * See trac ticket #24753
    794853                 *
    795854                 * @param {Object|Array} resp The raw response Object/Array.
    796855                 * @param {Object} xhr
    … … window.wp = window.wp || {};  
    822881                        });
    823882                },
    824883                /**
     884                 * If the collection is a query, create and mirror an Attachments Query collection.
     885                 *
    825886                 * @access private
    826887                 */
    827888                _requery: function( refresh ) {
    … … window.wp = window.wp || {};  
    867928                }
    868929        }, {
    869930                /**
     931                 * A function to compare two attachment models in an attachments collection.
     932                 *
     933                 * Used as the default comparator for instances of wp.media.model.Attachments
     934                 * and its subclasses. @see wp.media.model.Attachments._changeOrderby().
     935                 *
    870936                 * @static
    871                  * Overrides Backbone.Collection.comparator
    872937                 *
    873938                 * @param {Backbone.Model} a
    874939                 * @param {Backbone.Model} b
    … … window.wp = window.wp || {};  
    9711036        });
    9721037
    9731038        /**
     1039         * A collection of all attachments that have been fetched from the server.
     1040         *
    9741041         * @static
    9751042         * @member {wp.media.model.Attachments}
    9761043         */
    … … window.wp = window.wp || {};  
    9791046        /**
    9801047         * wp.media.query
    9811048         *
    982          * @static
     1049         * Shorthand for creating a new Attachments Query.
     1050         *
     1051         * @param {object} [props]
    9831052         * @returns {wp.media.model.Attachments}
    9841053         */
    9851054        media.query = function( props ) {
    … … window.wp = window.wp || {};  
    9911060        /**
    9921061         * wp.media.model.Query
    9931062         *
    994          * A set of attachments that corresponds to a set of consecutively paged
    995          * queries on the server.
     1063         * A collection of attachments that match the supplied query arguments.
    9961064         *
    9971065         * Note: Do NOT change this.args after the query has been initialized.
    9981066         *       Things will break.
    9991067         *
    1000          * @constructor
     1068         * @class
    10011069         * @augments wp.media.model.Attachments
    10021070         * @augments Backbone.Collection
     1071         *
     1072         * @param {array}  [models]                      Models to initialize with the collection.
     1073         * @param {object} [options]                     Options hash.
     1074         * @param {object} [options.args]                Attachments query arguments.
     1075         * @param {object} [options.args.posts_per_page]
    10031076         */
    10041077        Query = media.model.Query = Attachments.extend({
    10051078                /**
    10061079                 * @global wp.Uploader
    10071080                 *
    1008                  * @param {Array} [models=[]] Array of models used to populate the collection.
    1009                  * @param {Object} [options={}]
     1081                 * @param {array}  [models=[]]  Array of initial models to populate the collection.
     1082                 * @param {object} [options={}]
    10101083                 */
    10111084                initialize: function( models, options ) {
    10121085                        var allowed;
    … … window.wp = window.wp || {};  
    10601133                        }
    10611134                },
    10621135                /**
    1063                  * @returns {Boolean}
     1136                 * Whether there are more attachments that haven't been sync'd from the server
     1137                 * that match the collection's query.
     1138                 *
     1139                 * @returns {boolean}
    10641140                 */
    10651141                hasMore: function() {
    10661142                        return this._hasMore;
    10671143                },
    10681144                /**
    1069                  * @param {Object} [options={}]
     1145                 * Fetch more attachments from the server for the collection.
     1146                 *
     1147                 * @param   {object}  [options={}]
    10701148                 * @returns {Promise}
    10711149                 */
    10721150                more: function( options ) {
    10731151                        var query = this;
    10741152
     1153                        // If there is already a request pending, return early with the Deferred object.
    10751154                        if ( this._more && 'pending' === this._more.state() ) {
    10761155                                return this._more;
    10771156                        }
    … … window.wp = window.wp || {};  
    11491228                 */
    11501229                orderby: {
    11511230                        allowed:  [ 'name', 'author', 'date', 'title', 'modified', 'uploadedTo', 'id', 'post__in', 'menuOrder' ],
     1231                        /**
     1232                         * A map of JavaScript orderby values to their WP_Query equivalents.
     1233                         * @type {Object}
     1234                         */
    11521235                        valuemap: {
    11531236                                'id':         'ID',
    11541237                                'uploadedTo': 'parent',
    … … window.wp = window.wp || {};  
    11561239                        }
    11571240                },
    11581241                /**
     1242                 * A map of JavaScript query properties to their WP_Query equivalents.
     1243                 *
    11591244                 * @readonly
    11601245                 */
    11611246                propmap: {
    … … window.wp = window.wp || {};  
    11691254                        'exclude':    'post__not_in'
    11701255                },
    11711256                /**
     1257                 * Creates and returns an Attachments Query collection given the properties.
     1258                 *
     1259                 * Caches query objects and reuses where possible.
     1260                 *
    11721261                 * @static
    11731262                 * @method
    11741263                 *
    1175                  * @returns {wp.media.model.Query} A new query.
     1264                 * @param {object} [props]
     1265                 * @param {Object} [props.cache=true]   Whether to use the query cache or not.
     1266                 * @param {Object} [props.order]
     1267                 * @param {Object} [props.orderby]
     1268                 * @param {Object} [props.include]
     1269                 * @param {Object} [props.exclude]
     1270                 * @param {Object} [props.s]
     1271                 * @param {Object} [props.post_mime_type]
     1272                 * @param {Object} [props.posts_per_page]
     1273                 * @param {Object} [props.menu_order]
     1274                 * @param {Object} [props.post_parent]
     1275                 * @param {Object} [props.post_status]
     1276                 * @param {Object} [options]
     1277                 *
     1278                 * @returns {wp.media.model.Query} A new Attachments Query collection.
    11761279                 */
    1177                 // Caches query objects so queries can be easily reused.
    11781280                get: (function(){
    11791281                        /**
    11801282                         * @static
    … … window.wp = window.wp || {};  
    11831285                        var queries = [];
    11841286
    11851287                        /**
    1186                          * @param {Object} props
    1187                          * @param {Object} options
    11881288                         * @returns {Query}
    11891289                         */
    11901290                        return function( props, options ) {
    … … window.wp = window.wp || {};  
    12361336                                // Substitute exceptions specified in orderby.keymap.
    12371337                                args.orderby = orderby.valuemap[ props.orderby ] || props.orderby;
    12381338
    1239                                 // Search the query cache for matches.
     1339                                // Search the query cache for a matching query.
    12401340                                if ( cache ) {
    12411341                                        query = _.find( queries, function( query ) {
    12421342                                                return _.isEqual( query.args, args );
    … … window.wp = window.wp || {};  
    12621362        /**
    12631363         * wp.media.model.Selection
    12641364         *
    1265          * Used to manage a selection of attachments in the views.
     1365         * A selection of attachments.
    12661366         *
    1267          * @constructor
     1367         * @class
    12681368         * @augments wp.media.model.Attachments
    12691369         * @augments Backbone.Collection
    12701370         */
    … … window.wp = window.wp || {};  
    12881388                },
    12891389
    12901390                /**
    1291                  * Override the selection's add method.
    1292                  * If the workflow does not support multiple
    1293                  * selected attachments, reset the selection.
    1294                  *
    1295                  * Overrides Backbone.Collection.add
    1296                  * Overrides wp.media.model.Attachments.add
     1391                 * If the workflow does not support multi-select, clear out the selection
     1392                 * before adding a new attachment to it.
    12971393                 *
    12981394                 * @param {Array} models
    12991395                 * @param {Object} options
    … … window.wp = window.wp || {};  
    13101406                },
    13111407
    13121408                /**
    1313                  * Triggered when toggling (clicking on) an attachment in the modal
     1409                 * Fired when toggling (clicking on) an attachment in the modal.
    13141410                 *
    13151411                 * @param {undefined|boolean|wp.media.model.Attachment} model
    13161412                 *

  • src/wp-includes/js/media-views.js 

    diff --git src/wp-includes/js/media-views.js src/wp-includes/js/media-views.js
index cc02f43..96bd33f 100644
     
    26642664                                state:    'insert',
    26652665                                metadata:  {}
    26662666                        });
    2667                         /**
    2668                          * call 'initialize' directly on the parent class
    2669                          */
     2667
     2668                        // Call 'initialize' directly on the parent class.
    26702669                        media.view.MediaFrame.Select.prototype.initialize.apply( this, arguments );
    26712670                        this.createIframeStates();
    26722671
    … …  
    60136012                },
    60146013
    60156014                /**
    6016                  * When the selection changes, set the Query properties
    6017                  * accordingly for the selected filter.
     6015                 * When the selected filter changes, update the Attachment Query properties to match.
    60186016                 */
    60196017                change: function() {
    60206018                        var filter = this.filters[ this.el.value ];
    … …  
    62216219         * @augments wp.media.View
    62226220         * @augments wp.Backbone.View
    62236221         * @augments Backbone.View
     6222         *
     6223         * @param {object}      options
     6224         * @param {object}      [options.filters=false] Which filters to show in the browser's toolbar.
     6225         *                                              Accepts 'uploaded' and 'all'.
     6226         * @param {object}      [options.search=true]   Whether to show the search interface in the
     6227         *                                              browser's toolbar.
     6228         * @param {object}      [options.display=false] Whether to show the attachments display settings
     6229         *                                              view in the sidebar.
     6230         * @param {bool|string} [options.sidebar=true]  Whether to create a sidebar for the browser.
     6231         *                                              Accepts true, false, and 'errors'.
    62246232         */
    62256233        media.view.AttachmentsBrowser = media.View.extend({
    62266234                tagName:   'div',

  • src/wp-includes/js/wp-util.js 

    diff --git src/wp-includes/js/wp-util.js src/wp-includes/js/wp-util.js
index 867d3a0..1985b35 100644
    window.wp = window.wp || {};  
    88        /**
    99         * wp.template( id )
    1010         *
    11          * Fetches a template by id.
     11         * Fetch a JavaScript template for an id, and return a templating function for it.
    1212         *
    1313         * @param  {string} id   A string that corresponds to a DOM element with an id prefixed with "tmpl-".
    1414         *                       For example, "attachment" maps to "tmpl-attachment".
    … … window.wp = window.wp || {};  
    1616         */
    1717        wp.template = _.memoize(function ( id ) {
    1818                var compiled,
     19                        /*
     20                         * Underscore's default ERB-style templates are incompatible with PHP
     21                         * when asp_tags is enabled, so WordPress uses Mustache-inspired templating syntax.
     22                         *
     23                         * @see trac ticket #22344.
     24                         */
    1925                        options = {
    2026                                evaluate:    /<#([\s\S]+?)#>/g,
    2127                                interpolate: /\{\{\{([\s\S]+?)\}\}\}/g,