WordPress.org
Get WordPress

Make WordPress Core

Changeset 30245


Ignore:
Timestamp:
11/05/2014 07:38:20 PM (9 years ago)
Author:
wonderboymusic
Message:

Improve wp.media documentation.

Props ericlewis.
See #28459.

Location:
trunk/src/wp-includes/js
Files:
3 edited

Legend:

Unmodified
Added
Removed

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

    r29759 r30245  
    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.
    … …  
    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         *
    … …  
    198201     * wp.media.model.Attachment
    199202     *
    200      * @constructor
     203     * @class
    201204     * @augments Backbone.Model
    202205     */
    … …  
    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
    … …  
    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
    … …  
    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({
    … …  
    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({
    … …  
    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 );
    … …  
    532559        },
    533560        /**
    534          * Automatically sort the collection when the order changes.
     561         * Sort the collection when the order attribute changes.
    535562         *
    536563         * @access private
    … …  
    626653        validateDestroyed: false,
    627654        /**
     655         * Checks whether an attachment is valid.
     656         *
    628657         * @param {wp.media.model.Attachment} attachment
    629658         * @returns {Boolean}
    … …  
    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
    … …  
    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={}]
    … …  
    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 ) {
    … …  
    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         */
    … …  
    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         */
    … …  
    753794            return this;
    754795        },
     796        /**
     797         * Stop mirroring another attachments collection.
     798         */
    755799        unmirror: function() {
    756800            if ( ! 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         */
    … …  
    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() {
    … …  
    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.
    … …  
    823882        },
    824883        /**
     884         * If the collection is a query, create and mirror an Attachments Query collection.
     885         *
    825886         * @access private
    826887         */
    … …  
    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
    … …  
    9721037
    9731038    /**
     1039     * A collection of all attachments that have been fetched from the server.
     1040     *
    9741041     * @static
    9751042     * @member {wp.media.model.Attachments}
    … …  
    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     */
    … …  
    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({
    … …  
    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 ) {
    … …  
    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() {
    … …  
    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         */
    … …  
    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;
    … …  
    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',
    … …  
    11571240        },
    11581241        /**
     1242         * A map of JavaScript query properties to their WP_Query equivalents.
     1243         *
    11591244         * @readonly
    11601245         */
    … …  
    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.
    1176          */
    1177         // Caches query objects so queries can be easily reused.
     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.
     1279         */
    11781280        get: (function(){
    11791281            /**
    … …  
    11841286
    11851287            /**
    1186              * @param {Object} props
    1187              * @param {Object} options
    11881288             * @returns {Query}
    11891289             */
    … …  
    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 ) {
    … …  
    12631363     * wp.media.model.Selection
    12641364     *
    1265      * Used to manage a selection of attachments in the views.
    1266      *
    1267      * @constructor
     1365     * A selection of attachments.
     1366     *
     1367     * @class
    12681368     * @augments wp.media.model.Attachments
    12691369     * @augments Backbone.Collection
    … …  
    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
    … …  
    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

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

    r30234 r30245  
    680680     * @mixes media.selectionSync
    681681     *
    682      * @param {object}                     [attributes]                         The attributes hash passed to the state.
    683      * @param {string}                     [attributes.id=library]              Unique identifier.
    684      * @param {string}                     [attributes.title=Media library]     Title for the state. Displays in the media menu and the frame's title region.
    685      * @param {wp.media.model.Attachments} [attributes.library]                 The attachments collection to browse.
    686      *                                                                          If one is not supplied, a collection of all attachments will be created.
    687      * @param {boolean}                    [attributes.multiple=false]          Whether multi-select is enabled.
    688      * @param {string}                     [attributes.content=upload]          Initial mode for the content region.
    689      *                                                                          Overridden by persistent user setting if 'contentUserSetting' is true.
    690      * @param {string}                     [attributes.menu=default]            Initial mode for the menu region.
    691      * @param {string}                     [attributes.router=browse]           Initial mode for the router region.
    692      * @param {string}                     [attributes.toolbar=select]          Initial mode for the toolbar region.
    693      * @param {boolean}                    [attributes.searchable=true]         Whether the library is searchable.
    694      * @param {boolean|string}             [attributes.filterable=false]        Whether the library is filterable, and if so what filters should be shown.
    695      *                                                                          Accepts 'all', 'uploaded', or 'unattached'.
    696      * @param {boolean}                    [attributes.sortable=true]           Whether the Attachments should be sortable. Depends on the orderby property being set to menuOrder on the attachments collection.
    697      * @param {boolean}                    [attributes.autoSelect=true]         Whether an uploaded attachment should be automatically added to the selection.
    698      * @param {boolean}                    [attributes.describe=false]          Whether to offer UI to describe attachments - e.g. captioning images in a gallery.
    699      * @param {boolean}                    [attributes.contentUserSetting=true] Whether the content region's mode should be set and persisted per user.
    700      * @param {boolean}                    [attributes.syncSelection=true]      Whether the Attachments selection should be persisted from the last state.
     682     * @param {object}                          [attributes]                         The attributes hash passed to the state.
     683     * @param {string}                          [attributes.id=library]              Unique identifier.
     684     * @param {string}                          [attributes.title=Media library]     Title for the state. Displays in the media menu and the frame's title region.
     685     * @param {wp.media.model.Attachments}      [attributes.library]                 The attachments collection to browse.
     686     *                                                                               If one is not supplied, a collection of all attachments will be created.
     687     * @param {wp.media.model.Selection|object} [attributes.selection]               A collection to contain attachment selections within the state.
     688     *                                                                               If the 'selection' attribute is a plain JS object,
     689     *                                                                               a Selection will be created using its values as the selection instance's `props` model.
     690     *                                                                               Otherwise, it will copy the library's `props` model.
     691     * @param {boolean}                         [attributes.multiple=false]          Whether multi-select is enabled.
     692     * @param {string}                          [attributes.content=upload]          Initial mode for the content region.
     693     *                                                                               Overridden by persistent user setting if 'contentUserSetting' is true.
     694     * @param {string}                          [attributes.menu=default]            Initial mode for the menu region.
     695     * @param {string}                          [attributes.router=browse]           Initial mode for the router region.
     696     * @param {string}                          [attributes.toolbar=select]          Initial mode for the toolbar region.
     697     * @param {boolean}                         [attributes.searchable=true]         Whether the library is searchable.
     698     * @param {boolean|string}                  [attributes.filterable=false]        Whether the library is filterable, and if so what filters should be shown.
     699     *                                                                               Accepts 'all', 'uploaded', or 'unattached'.
     700     * @param {boolean}                         [attributes.sortable=true]           Whether the Attachments should be sortable. Depends on the orderby property being set to menuOrder on the attachments collection.
     701     * @param {boolean}                         [attributes.autoSelect=true]         Whether an uploaded attachment should be automatically added to the selection.
     702     * @param {boolean}                         [attributes.describe=false]          Whether to offer UI to describe attachments - e.g. captioning images in a gallery.
     703     * @param {boolean}                         [attributes.contentUserSetting=true] Whether the content region's mode should be set and persisted per user.
     704     * @param {boolean}                         [attributes.syncSelection=true]      Whether the Attachments selection should be persisted from the last state.
    701705     */
    702706    media.controller.Library = media.controller.State.extend({
    … …  
    740744                }
    741745
    742                 // If the `selection` attribute is set to an object,
    743                 // it will use those values as the selection instance's
    744                 // `props` model. Otherwise, it will copy the library's
    745                 // `props` model.
    746746                this.set( 'selection', new media.model.Selection( null, {
    747747                    multiple: this.get('multiple'),
    … …  
    24832483    media.view.MediaFrame.Select = media.view.MediaFrame.extend({
    24842484        initialize: function() {
    2485             /**
    2486              * call 'initialize' directly on the parent class
    2487              */
     2485            // Call 'initialize' directly on the parent class.
    24882486            media.view.MediaFrame.prototype.initialize.apply( this, arguments );
    24892487
    … …  
    26652663                metadata:  {}
    26662664            });
    2667             /**
    2668              * call 'initialize' directly on the parent class
    2669              */
     2665
     2666            // Call 'initialize' directly on the parent class.
    26702667            media.view.MediaFrame.Select.prototype.initialize.apply( this, arguments );
    26712668            this.createIframeStates();
    … …  
    45544551                }
    45554552            });
    4556             /**
    4557              * call 'initialize' directly on the parent class
    4558              */
     4553            // Call 'initialize' directly on the parent class.
    45594554            media.view.Toolbar.prototype.initialize.apply( this, arguments );
    45604555        },
    … …  
    45984593                requires: false
    45994594            });
    4600             /**
    4601              * call 'initialize' directly on the parent class
    4602              */
     4595            // Call 'initialize' directly on the parent class.
    46034596            media.view.Toolbar.Select.prototype.initialize.apply( this, arguments );
    46044597        },
    … …  
    50475040        initialize: function() {
    50485041            this.controller.on( 'content:render', this.update, this );
    5049             /**
    5050              * call 'initialize' directly on the parent class
    5051              */
     5042            // Call 'initialize' directly on the parent class.
    50525043            media.view.Menu.prototype.initialize.apply( this, arguments );
    50535044        },
    … …  
    60146005
    60156006        /**
    6016          * When the selection changes, set the Query properties
    6017          * accordingly for the selected filter.
     6007         * When the selected filter changes, update the Attachment Query properties to match.
    60186008         */
    60196009        change: function() {
    … …  
    62226212     * @augments wp.Backbone.View
    62236213     * @augments Backbone.View
     6214     *
     6215     * @param {object}      options
     6216     * @param {object}      [options.filters=false] Which filters to show in the browser's toolbar.
     6217     *                                              Accepts 'uploaded' and 'all'.
     6218     * @param {object}      [options.search=true]   Whether to show the search interface in the
     6219     *                                              browser's toolbar.
     6220     * @param {object}      [options.display=false] Whether to show the attachments display settings
     6221     *                                              view in the sidebar.
     6222     * @param {bool|string} [options.sidebar=true]  Whether to create a sidebar for the browser.
     6223     *                                              Accepts true, false, and 'errors'.
    62246224     */
    62256225    media.view.AttachmentsBrowser = media.View.extend({
    … …  
    67486748                AttachmentView: media.view.Attachment.Selection
    67496749            });
    6750             /**
    6751              * call 'initialize' directly on the parent class
    6752              */
     6750            // Call 'initialize' directly on the parent class.
    67536751            return media.view.Attachments.prototype.initialize.apply( this, arguments );
    67546752        }
    … …  
    69056903                userSettings: false
    69066904            });
    6907             /**
    6908              * call 'initialize' directly on the parent class
    6909              */
     6905            // Call 'initialize' directly on the parent class.
    69106906            media.view.Settings.prototype.initialize.apply( this, arguments );
    69116907            this.model.on( 'change:link', this.updateLinkTo, this );
    … …  
    70377033
    70387034            this.on( 'ready', this.initialFocus );
    7039             /**
    7040              * call 'initialize' directly on the parent class
    7041              */
     7035            // Call 'initialize' directly on the parent class.
    70427036            media.view.Attachment.prototype.initialize.apply( this, arguments );
    70437037        },

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

    r26207 r30245  
    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-".
    … …  
    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,
Note: See TracChangeset for help on using the changeset viewer.