Make WordPress Core

Changeset 30120


Ignore:
Timestamp:
10/31/2014 03:19:58 PM (10 years ago)
Author:
wonderboymusic
Message:

Add verbose docs to media-views.js.

Props ericlewis.
See #30193.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/js/media-views.js

    r29917 r30120  
    7373
    7474    /**
    75      * ========================================================================
    76      * CONTROLLERS
    77      * ========================================================================
    78      */
    79 
    80     /**
    8175     * wp.media.controller.Region
    8276     *
    83      * @constructor
    84      * @augments Backbone.Model
    85      *
    86      * @param {Object} [options={}]
     77     * A region is a persistent application layout area.
     78     *
     79     * A region assumes one mode at any time, and can be switched to another.
     80     *
     81     * When mode changes, events are triggered on the region's parent view.
     82     * The parent view will listen to specific events and fill the region with an
     83     * appropriate view depending on mode. For example, a frame listens for the
     84     * 'browse' mode t be activated on the 'content' view and then fills the region
     85     * with an AttachmentsBrowser view.
     86     *
     87     * @class
     88     *
     89     * @param {object}        options          Options hash for the region.
     90     * @param {string}        options.id       Unique identifier for the region.
     91     * @param {Backbone.View} options.view     A parent view the region exists within.
     92     * @param {string}        options.selector jQuery selector for the region within the parent view.
    8793     */
    8894    media.controller.Region = function( options ) {
     
    245251     * wp.media.controller.StateMachine
    246252     *
     253     * A state machine keeps track of state. It is in one state at a time,
     254     * and can change from one state to another.
     255     *
     256     * States are stored as models in a Backbone collection.
     257     *
    247258     * @since 3.5.0
    248259     *
    249      * @constructor
     260     * @class
    250261     * @augments Backbone.Model
    251262     * @mixin
     
    255266     */
    256267    media.controller.StateMachine = function( states ) {
     268        // @todo This is dead code. The states collection gets created in media.view.Frame._createStates.
    257269        this.states = new Backbone.Collection( states );
    258270    };
     
    361373     *
    362374     * A state is a step in a workflow that when set will trigger the controllers
    363      * for the regions to be updated as specified in the frame. This is the base
    364      * class that the various states used in wp.media extend.
    365      *
    366      * @constructor
     375     * for the regions to be updated as specified in the frame.
     376     *
     377     * A state has an event-driven lifecycle:
     378     *
     379     *     'ready'      triggers when a state is added to a state machine's collection.
     380     *     'activate'   triggers when a state is activated by a state machine.
     381     *     'deactivate' triggers when a state is deactivated by a state machine.
     382     *     'reset'      is not triggered automatically. It should be invoked by the
     383     *                  proper controller to reset the state to its default.
     384     *
     385     * @class
    367386     * @augments Backbone.Model
    368387     */
     
    389408        },
    390409        /**
     410         * Ready event callback.
     411         *
    391412         * @abstract
    392413         * @since 3.5.0
     
    395416
    396417        /**
     418         * Activate event callback.
     419         *
    397420         * @abstract
    398421         * @since 3.5.0
     
    401424
    402425        /**
     426         * Deactivate event callback.
     427         *
    403428         * @abstract
    404429         * @since 3.5.0
     
    407432
    408433        /**
     434         * Reset event callback.
     435         *
    409436         * @abstract
    410437         * @since 3.5.0
     
    540567
    541568        /**
     569         * Create a view in the media menu for the state.
     570         *
    542571         * @access private
    543572         * @since 3.5.0
     573         *
     574         * @param {media.view.Menu} view The menu view.
    544575         */
    545576        _renderMenu: function( view ) {
     
    576607    });
    577608
     609    /**
     610     * wp.media.selectionSync
     611     *
     612     * Sync an attachments selection in a state with another state.
     613     *
     614     * Allows for selecting multiple images in the Insert Media workflow, and then
     615     * switching to the Insert Gallery workflow while preserving the attachments selection.
     616     *
     617     * @mixin
     618     */
    578619    media.selectionSync = {
    579620        /**
     
    630671
    631672    /**
    632      * A state for choosing an attachment from the media library.
    633      *
    634      * @constructor
     673     * wp.media.controller.Library
     674     *
     675     * A state for choosing an attachment or group of attachments from the media library.
     676     *
     677     * @class
    635678     * @augments wp.media.controller.State
    636679     * @augments Backbone.Model
     680     * @mixes media.selectionSync
     681     *
     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.
    637701     */
    638702    media.controller.Library = media.controller.State.extend({
     
    640704            id:                 'library',
    641705            title:              l10n.mediaLibraryTitle,
    642             // Selection defaults. @see media.model.Selection
    643706            multiple:           false,
    644             // Initial region modes.
    645707            content:            'upload',
    646708            menu:               'default',
    647709            router:             'browse',
    648710            toolbar:            'select',
    649             // Attachments browser defaults. @see media.view.AttachmentsBrowser
    650711            searchable:         true,
    651712            filterable:         false,
    652713            sortable:           true,
    653 
    654714            autoSelect:         true,
    655715            describe:           false,
    656             // Uses a user setting to override the content mode.
    657716            contentUserSetting: true,
    658             // Sync the selection from the last state when 'multiple' matches.
    659717            syncSelection:      true
    660718        },
     
    727785
    728786        /**
     787         * Reset the library to its initial state.
     788         *
    729789         * @since 3.5.0
    730790         */
     
    736796
    737797        /**
     798         * Reset the attachment display settings defaults to the site options.
     799         *
     800         * If site options don't define them, fall back to a persistent user setting.
     801         *
    738802         * @since 3.5.0
    739803         */
     
    749813
    750814        /**
     815         * Create a model to represent display settings (alignment, etc.) for an attachment.
     816         *
    751817         * @since 3.5.0
    752818         *
     
    764830
    765831        /**
     832         * Given an attachment, create attachment display settings properties.
     833         *
    766834         * @since 3.6.0
    767835         *
     
    778846
    779847        /**
     848         * Whether an attachment can be embedded (audio or video).
     849         *
    780850         * @since 3.6.0
    781851         *
     
    815885
    816886        /**
    817          * If the uploader was selected, navigate to the browser.
    818          *
    819          * Automatically select any uploading attachments.
    820          *
    821          * Selections that don't support multiple attachments automatically
    822          * limit themselves to one attachment (in this case, the last
    823          * attachment in the upload queue).
     887         * Callback handler when an attachment is uploaded.
     888         *
     889         * Switch to the Media Library if uploaded from the 'Upload Files' tab.
     890         *
     891         * Adds any uploading attachments to the selection.
     892         *
     893         * If the state only supports one attachment to be selected and multiple
     894         * attachments are uploaded, the last attachment in the upload queue will
     895         * be selected.
    824896         *
    825897         * @since 3.5.0
     
    841913
    842914        /**
    843          * Only track the browse router on library states.
     915         * Persist the mode of the content region as a user setting.
    844916         *
    845917         * @since 3.5.0
     
    859931    });
    860932
     933    // Make selectionSync available on any Media Library state.
    861934    _.extend( media.controller.Library.prototype, media.selectionSync );
    862935
    863936    /**
    864      * A state for editing the settings of an image within a content editor.
    865      *
    866      * @constructor
     937     * wp.media.controller.ImageDetails
     938     *
     939     * A state for editing the attachment display settings of an image that's been
     940     * inserted into the editor.
     941     *
     942     * @class
    867943     * @augments wp.media.controller.State
    868944     * @augments Backbone.Model
     945     *
     946     * @param {object}                    [attributes]                       The attributes hash passed to the state.
     947     * @param {string}                    [attributes.id=image-details]      Unique identifier.
     948     * @param {string}                    [attributes.title=Image Details]   Title for the state. Displays in the frame's title region.
     949     * @param {wp.media.model.Attachment} attributes.image                   The image's model.
     950     * @param {string|false}              [attributes.content=image-details] Initial mode for the content region.
     951     * @param {string|false}              [attributes.menu=false]            Initial mode for the menu region.
     952     * @param {string|false}              [attributes.router=false]          Initial mode for the router region.
     953     * @param {string|false}              [attributes.toolbar=image-details] Initial mode for the toolbar region.
     954     * @param {boolean}                   [attributes.editing=false]         Unused.
     955     * @param {int}                       [attributes.priority=60]           Unused.
     956     *
     957     * @todo This state inherits some defaults from media.controller.Library.prototype.defaults,
     958     *       however this may not do anything.
    869959     */
    870960    media.controller.ImageDetails = media.controller.State.extend({
     
    872962            id:       'image-details',
    873963            title:    l10n.imageDetailsTitle,
    874             // Initial region modes.
    875964            content:  'image-details',
    876965            menu:     false,
    877966            router:   false,
    878967            toolbar:  'image-details',
    879 
    880968            editing:  false,
    881969            priority: 60
     
    901989
    902990    /**
     991     * wp.media.controller.GalleryEdit
     992     *
    903993     * A state for editing a gallery's images and settings.
    904994     *
    905      * @constructor
     995     * @class
    906996     * @augments wp.media.controller.Library
    907997     * @augments wp.media.controller.State
    908998     * @augments Backbone.Model
     999     *
     1000     * @param {object}                     [attributes]                       The attributes hash passed to the state.
     1001     * @param {string}                     [attributes.id=gallery-edit]       Unique identifier.
     1002     * @param {string}                     [attributes.title=Edit Gallery]    Title for the state. Displays in the frame's title region.
     1003     * @param {wp.media.model.Attachments} [attributes.library]               The collection of attachments in the gallery.
     1004     *                                                                        If one is not supplied, an empty media.model.Selection collection is created.
     1005     * @param {boolean}                    [attributes.multiple=false]        Whether multi-select is enabled.
     1006     * @param {boolean}                    [attributes.searchable=false]      Whether the library is searchable.
     1007     * @param {boolean}                    [attributes.sortable=true]         Whether the Attachments should be sortable. Depends on the orderby property being set to menuOrder on the attachments collection.
     1008     * @param {string|false}               [attributes.content=browse]        Initial mode for the content region.
     1009     * @param {string|false}               [attributes.toolbar=image-details] Initial mode for the toolbar region.
     1010     * @param {boolean}                    [attributes.describe=true]         Whether to offer UI to describe attachments - e.g. captioning images in a gallery.
     1011     * @param {boolean}                    [attributes.displaySettings=true]  Whether to show the attachment display settings interface.
     1012     * @param {boolean}                    [attributes.dragInfo=true]         Whether to show instructional text about the attachments being sortable.
     1013     * @param {int}                        [attributes.idealColumnWidth=170]  The ideal column width in pixels for attachments.
     1014     * @param {boolean}                    [attributes.editing=false]         Whether the gallery is being created, or editing an existing instance.
     1015     * @param {int}                        [attributes.priority=60]           The priority for the state link in the media menu.
     1016     * @param {boolean}                    [attributes.syncSelection=false]   Whether the Attachments selection should be persisted from the last state.
     1017     *                                                                        Defaults to false for this state, because the library passed in  *is* the selection.
     1018     * @param {view}                       [attributes.AttachmentView]        The single `Attachment` view to be used in the `Attachments`.
     1019     *                                                                        If none supplied, defaults to wp.media.view.Attachment.EditLibrary.
    9091020     */
    9101021    media.controller.GalleryEdit = media.controller.Library.extend({
    9111022        defaults: {
    912             id:              'gallery-edit',
    913             title:           l10n.editGalleryTitle,
    914             // Selection defaults. @see media.model.Selection
    915             multiple:        false,
    916             // Attachments browser defaults. @see media.view.AttachmentsBrowser
    917             searchable:      false,
    918             sortable:        true,
    919             display:         false,
    920             // Initial region modes.
    921             content:         'browse',
    922             toolbar:         'gallery-edit',
    923 
     1023            id:               'gallery-edit',
     1024            title:            l10n.editGalleryTitle,
     1025            multiple:         false,
     1026            searchable:       false,
     1027            sortable:         true,
     1028            display:          false,
     1029            content:          'browse',
     1030            toolbar:          'gallery-edit',
    9241031            describe:         true,
    9251032            displaySettings:  true,
     
    9281035            editing:          false,
    9291036            priority:         60,
    930 
    931             // Don't sync the selection, as the Edit Gallery library
    932             // *is* the selection.
    933             syncSelection: false
     1037            syncSelection:    false
    9341038        },
    9351039
     
    10151119
    10161120    /**
    1017      * A state for adding an image to a gallery.
    1018      *
    1019      * @constructor
     1121     * A state for selecting more images to add to a gallery.
     1122     *
     1123     * @class
    10201124     * @augments wp.media.controller.Library
    10211125     * @augments wp.media.controller.State
    10221126     * @augments Backbone.Model
     1127     *
     1128     * @param {object}                     [attributes]                         The attributes hash passed to the state.
     1129     * @param {string}                     [attributes.id=gallery-library]      Unique identifier.
     1130     * @param {string}                     [attributes.title=Add to Gallery]    Title for the state. Displays in the frame's title region.
     1131     * @param {boolean}                    [attributes.multiple=add]            Whether multi-select is enabled. @todo 'add' doesn't seem do anything special, and gets used as a boolean.
     1132     * @param {wp.media.model.Attachments} [attributes.library]                 The attachments collection to browse.
     1133     *                                                                          If one is not supplied, a collection of all images will be created.
     1134     * @param {boolean|string}             [attributes.filterable=uploaded]     Whether the library is filterable, and if so what filters should be shown.
     1135     *                                                                          Accepts 'all', 'uploaded', or 'unattached'.
     1136     * @param {string}                     [attributes.menu=gallery]            Initial mode for the menu region.
     1137     * @param {string}                     [attributes.content=upload]          Initial mode for the content region.
     1138     *                                                                          Overridden by persistent user setting if 'contentUserSetting' is true.
     1139     * @param {string}                     [attributes.router=browse]           Initial mode for the router region.
     1140     * @param {string}                     [attributes.toolbar=gallery-add]     Initial mode for the toolbar region.
     1141     * @param {boolean}                    [attributes.searchable=true]         Whether the library is searchable.
     1142     * @param {boolean}                    [attributes.sortable=true]           Whether the Attachments should be sortable. Depends on the orderby property being set to menuOrder on the attachments collection.
     1143     * @param {boolean}                    [attributes.autoSelect=true]         Whether an uploaded attachment should be automatically added to the selection.
     1144     * @param {boolean}                    [attributes.contentUserSetting=true] Whether the content region's mode should be set and persisted per user.
     1145     * @param {int}                        [attributes.priority=100]            The priority for the state link in the media menu.
     1146     * @param {boolean}                    [attributes.syncSelection=false]     Whether the Attachments selection should be persisted from the last state.
     1147     *                                                                          Defaults to false because for this state, because the library of the Edit Gallery state is the selection.
    10231148     */
    10241149    media.controller.GalleryAdd = media.controller.Library.extend({
     
    10261151            id:            'gallery-library',
    10271152            title:         l10n.addToGalleryTitle,
    1028             // Selection defaults. @see media.model.Selection
    10291153            multiple:      'add',
    1030             // Attachments browser defaults. @see media.view.AttachmentsBrowser
    10311154            filterable:    'uploaded',
    1032             // Initial region modes.
    10331155            menu:          'gallery',
    10341156            toolbar:       'gallery-add',
    1035 
    10361157            priority:      100,
    1037             // Don't sync the selection, as the Edit Gallery library
    1038             // *is* the selection.
    10391158            syncSelection: false
    10401159        }, media.controller.Library.prototype.defaults ),
     
    10441163         */
    10451164        initialize: function() {
    1046             // If we haven't been provided a `library`, create a `Selection`.
     1165            // If a library wasn't supplied, create a library of images.
    10471166            if ( ! this.get('library') )
    10481167                this.set( 'library', media.query({ type: 'image' }) );
     
    10811200     * wp.media.controller.CollectionEdit
    10821201     *
    1083      * @constructor
     1202     * A state for editing a collection, which is used by audio and video playlists,
     1203     * and can be used for other collections.
     1204     *
     1205     * @class
    10841206     * @augments wp.media.controller.Library
    10851207     * @augments wp.media.controller.State
    10861208     * @augments Backbone.Model
     1209     *
     1210     * @param {object}                     [attributes]                      The attributes hash passed to the state.
     1211     * @param {string}                     attributes.title                  Title for the state. Displays in the media menu and the frame's title region.
     1212     * @param {wp.media.model.Attachments} [attributes.library]              The attachments collection to edit.
     1213     *                                                                       If one is not supplied, an empty media.model.Selection collection is created.
     1214     * @param {boolean}                    [attributes.multiple=false]       Whether multi-select is enabled.
     1215     * @param {string}                     [attributes.content=browse]       Initial mode for the content region.
     1216     * @param {string}                     attributes.menu                   Initial mode for the menu region. @todo this needs a better explanation.
     1217     * @param {boolean}                    [attributes.searchable=false]     Whether the library is searchable.
     1218     * @param {boolean}                    [attributes.sortable=true]        Whether the Attachments should be sortable. Depends on the orderby property being set to menuOrder on the attachments collection.
     1219     * @param {boolean}                    [attributes.describe=true]        Whether to offer UI to describe the attachments - e.g. captioning images in a gallery.
     1220     * @param {boolean}                    [attributes.dragInfo=true]        Whether to show instructional text about the attachments being sortable.
     1221     * @param {boolean}                    [attributes.dragInfoText]         Instructional text about the attachments being sortable.
     1222     * @param {int}                        [attributes.idealColumnWidth=170] The ideal column width in pixels for attachments.
     1223     * @param {boolean}                    [attributes.editing=false]        Whether the gallery is being created, or editing an existing instance.
     1224     * @param {int}                        [attributes.priority=60]          The priority for the state link in the media menu.
     1225     * @param {boolean}                    [attributes.syncSelection=false]  Whether the Attachments selection should be persisted from the last state.
     1226     *                                                                       Defaults to false for this state, because the library passed in  *is* the selection.
     1227     * @param {view}                       [attributes.SettingsView]         The view to edit the collection instance settings (e.g. Playlist settings with "Show tracklist" checkbox).
     1228     * @param {view}                       [attributes.AttachmentView]       The single `Attachment` view to be used in the `Attachments`.
     1229     *                                                                       If none supplied, defaults to wp.media.view.Attachment.EditLibrary.
     1230     * @param {string}                     attributes.type                   The collection's media type. (e.g. 'video').
     1231     * @param {string}                     attributes.collectionType         The collection type. (e.g. 'playlist').
    10871232     */
    10881233    media.controller.CollectionEdit = media.controller.Library.extend({
    10891234        defaults: {
    1090             // Selection defaults. @see media.model.Selection
    1091             multiple:     false,
    1092             // Attachments browser defaults. @see media.view.AttachmentsBrowser
    1093             sortable:     true,
    1094             searchable:   false,
    1095             // Region mode defaults.
    1096             content:      'browse',
    1097 
     1235            multiple:         false,
     1236            sortable:         true,
     1237            searchable:       false,
     1238            content:          'browse',
    10981239            describe:         true,
    10991240            dragInfo:         true,
     
    11021243            priority:         60,
    11031244            SettingsView:     false,
    1104 
    1105             // Don't sync the selection, as the Edit {Collection} library
    1106             // *is* the selection.
    1107             syncSelection: false
     1245            syncSelection:    false
    11081246        },
    11091247
     
    11621300
    11631301        /**
     1302         * Render the collection embed settings view in the browser sidebar.
     1303         *
     1304         * @todo This is against the pattern elsewhere in media. Typically the frame
     1305         *       is responsible for adding region mode callbacks. Explain.
     1306         *
    11641307         * @since 3.9.0
    11651308         *
    1166          * @param browser
    1167          */
    1168         renderSettings: function( browser ) {
     1309         * @param {wp.media.view.attachmentsBrowser} The attachments browser view.
     1310         */
     1311        renderSettings: function( attachmentsBrowserView ) {
    11691312            var library = this.get('library'),
    11701313                collectionType = this.get('collectionType'),
     
    11941337            }
    11951338
     1339            // Add the 'Reverse order' button to the toolbar.
    11961340            browser.toolbar.set( 'reverse', {
    11971341                text:     l10n.reverseOrder,
     
    12081352     * wp.media.controller.CollectionAdd
    12091353     *
    1210      * @constructor
     1354     * A state for adding attachments to a collection (e.g. video playlist).
     1355     *
     1356     * @class
    12111357     * @augments wp.media.controller.Library
    12121358     * @augments wp.media.controller.State
    12131359     * @augments Backbone.Model
     1360     *
     1361     * @param {object}                     [attributes]                         The attributes hash passed to the state.
     1362     * @param {string}                     [attributes.id=library]      Unique identifier.
     1363     * @param {string}                     attributes.title                    Title for the state. Displays in the frame's title region.
     1364     * @param {boolean}                    [attributes.multiple=add]            Whether multi-select is enabled. @todo 'add' doesn't seem do anything special, and gets used as a boolean.
     1365     * @param {wp.media.model.Attachments} [attributes.library]                 The attachments collection to browse.
     1366     *                                                                          If one is not supplied, a collection of attachments of the specified type will be created.
     1367     * @param {boolean|string}             [attributes.filterable=uploaded]     Whether the library is filterable, and if so what filters should be shown.
     1368     *                                                                          Accepts 'all', 'uploaded', or 'unattached'.
     1369     * @param {string}                     [attributes.menu=gallery]            Initial mode for the menu region.
     1370     * @param {string}                     [attributes.content=upload]          Initial mode for the content region.
     1371     *                                                                          Overridden by persistent user setting if 'contentUserSetting' is true.
     1372     * @param {string}                     [attributes.router=browse]           Initial mode for the router region.
     1373     * @param {string}                     [attributes.toolbar=gallery-add]     Initial mode for the toolbar region.
     1374     * @param {boolean}                    [attributes.searchable=true]         Whether the library is searchable.
     1375     * @param {boolean}                    [attributes.sortable=true]           Whether the Attachments should be sortable. Depends on the orderby property being set to menuOrder on the attachments collection.
     1376     * @param {boolean}                    [attributes.autoSelect=true]         Whether an uploaded attachment should be automatically added to the selection.
     1377     * @param {boolean}                    [attributes.contentUserSetting=true] Whether the content region's mode should be set and persisted per user.
     1378     * @param {int}                        [attributes.priority=100]            The priority for the state link in the media menu.
     1379     * @param {boolean}                    [attributes.syncSelection=false]     Whether the Attachments selection should be persisted from the last state.
     1380     *                                                                          Defaults to false because for this state, because the library of the Edit Gallery state is the selection.
     1381     * @param {string}                     attributes.type                   The collection's media type. (e.g. 'video').
     1382     * @param {string}                     attributes.collectionType         The collection type. (e.g. 'playlist').
    12141383     */
    12151384    media.controller.CollectionAdd = media.controller.Library.extend({
     
    12751444
    12761445    /**
     1446     * wp.media.controller.FeaturedImage
     1447     *
    12771448     * A state for selecting a featured image for a post.
    12781449     *
    1279      * @constructor
     1450     * @class
    12801451     * @augments wp.media.controller.Library
    12811452     * @augments wp.media.controller.State
    12821453     * @augments Backbone.Model
     1454     *
     1455     * @param {object}                     [attributes]                          The attributes hash passed to the state.
     1456     * @param {string}                     [attributes.id=featured-image]        Unique identifier.
     1457     * @param {string}                     [attributes.title=Set Featured Image] Title for the state. Displays in the media menu and the frame's title region.
     1458     * @param {wp.media.model.Attachments} [attributes.library]                  The attachments collection to browse.
     1459     *                                                                           If one is not supplied, a collection of all images will be created.
     1460     * @param {boolean}                    [attributes.multiple=false]           Whether multi-select is enabled.
     1461     * @param {string}                     [attributes.content=upload]           Initial mode for the content region.
     1462     *                                                                           Overridden by persistent user setting if 'contentUserSetting' is true.
     1463     * @param {string}                     [attributes.menu=default]             Initial mode for the menu region.
     1464     * @param {string}                     [attributes.router=browse]            Initial mode for the router region.
     1465     * @param {string}                     [attributes.toolbar=featured-image]   Initial mode for the toolbar region.
     1466     * @param {int}                        [attributes.priority=60]              The priority for the state link in the media menu.
     1467     * @param {boolean}                    [attributes.searchable=true]          Whether the library is searchable.
     1468     * @param {boolean|string}             [attributes.filterable=false]         Whether the library is filterable, and if so what filters should be shown.
     1469     *                                                                           Accepts 'all', 'uploaded', or 'unattached'.
     1470     * @param {boolean}                    [attributes.sortable=true]            Whether the Attachments should be sortable. Depends on the orderby property being set to menuOrder on the attachments collection.
     1471     * @param {boolean}                    [attributes.autoSelect=true]          Whether an uploaded attachment should be automatically added to the selection.
     1472     * @param {boolean}                    [attributes.describe=false]           Whether to offer UI to describe attachments - e.g. captioning images in a gallery.
     1473     * @param {boolean}                    [attributes.contentUserSetting=true]  Whether the content region's mode should be set and persisted per user.
     1474     * @param {boolean}                    [attributes.syncSelection=true]       Whether the Attachments selection should be persisted from the last state.
    12831475     */
    12841476    media.controller.FeaturedImage = media.controller.Library.extend({
     
    12861478            id:            'featured-image',
    12871479            title:         l10n.setFeaturedImageTitle,
    1288             // Selection defaults. @see media.model.Selection
    12891480            multiple:      false,
    1290             // Attachments browser defaults. @see media.view.AttachmentsBrowser
    12911481            filterable:    'uploaded',
    1292             // Region mode defaults.
    12931482            toolbar:       'featured-image',
    1294 
    12951483            priority:      60,
    12961484            syncSelection: true
     
    13701558
    13711559    /**
     1560     * wp.media.controller.ReplaceImage
     1561     *
    13721562     * A state for replacing an image.
    13731563     *
    1374      * @constructor
     1564     * @class
    13751565     * @augments wp.media.controller.Library
    13761566     * @augments wp.media.controller.State
    13771567     * @augments Backbone.Model
     1568     *
     1569     * @param {object}                     [attributes]                         The attributes hash passed to the state.
     1570     * @param {string}                     [attributes.id=replace-image]        Unique identifier.
     1571     * @param {string}                     [attributes.title=Replace Image]     Title for the state. Displays in the media menu and the frame's title region.
     1572     * @param {wp.media.model.Attachments} [attributes.library]                 The attachments collection to browse.
     1573     *                                                                          If one is not supplied, a collection of all images will be created.
     1574     * @param {boolean}                    [attributes.multiple=false]          Whether multi-select is enabled.
     1575     * @param {string}                     [attributes.content=upload]          Initial mode for the content region.
     1576     *                                                                          Overridden by persistent user setting if 'contentUserSetting' is true.
     1577     * @param {string}                     [attributes.menu=default]            Initial mode for the menu region.
     1578     * @param {string}                     [attributes.router=browse]           Initial mode for the router region.
     1579     * @param {string}                     [attributes.toolbar=replace]         Initial mode for the toolbar region.
     1580     * @param {int}                        [attributes.priority=60]             The priority for the state link in the media menu.
     1581     * @param {boolean}                    [attributes.searchable=true]         Whether the library is searchable.
     1582     * @param {boolean|string}             [attributes.filterable=uploaded]     Whether the library is filterable, and if so what filters should be shown.
     1583     *                                                                          Accepts 'all', 'uploaded', or 'unattached'.
     1584     * @param {boolean}                    [attributes.sortable=true]           Whether the Attachments should be sortable. Depends on the orderby property being set to menuOrder on the attachments collection.
     1585     * @param {boolean}                    [attributes.autoSelect=true]         Whether an uploaded attachment should be automatically added to the selection.
     1586     * @param {boolean}                    [attributes.describe=false]          Whether to offer UI to describe attachments - e.g. captioning images in a gallery.
     1587     * @param {boolean}                    [attributes.contentUserSetting=true] Whether the content region's mode should be set and persisted per user.
     1588     * @param {boolean}                    [attributes.syncSelection=true]      Whether the Attachments selection should be persisted from the last state.
    13781589     */
    13791590    media.controller.ReplaceImage = media.controller.Library.extend({
     
    13811592            id:            'replace-image',
    13821593            title:         l10n.replaceImageTitle,
    1383             // Selection defaults. @see media.model.Selection
    13841594            multiple:      false,
    1385             // Attachments browser defaults. @see media.view.AttachmentsBrowser
    13861595            filterable:    'uploaded',
    1387             // Region mode defaults.
    13881596            toolbar:       'replace',
    13891597            menu:          false,
    1390 
    13911598            priority:      60,
    13921599            syncSelection: true
     
    14521659
    14531660    /**
     1661     * wp.media.controller.EditImage
     1662     *
    14541663     * A state for editing (cropping, etc.) an image.
    14551664     *
    1456      * @constructor
     1665     * @class
    14571666     * @augments wp.media.controller.State
    14581667     * @augments Backbone.Model
     1668     *
     1669     * @param {object}                    attributes                      The attributes hash passed to the state.
     1670     * @param {wp.media.model.Attachment} attributes.model                The attachment.
     1671     * @param {string}                    [attributes.id=edit-image]      Unique identifier.
     1672     * @param {string}                    [attributes.title=Edit Image]   Title for the state. Displays in the media menu and the frame's title region.
     1673     * @param {string}                    [attributes.content=edit-image] Initial mode for the content region.
     1674     * @param {string}                    [attributes.toolbar=edit-image] Initial mode for the toolbar region.
     1675     * @param {string}                    [attributes.menu=false]         Initial mode for the menu region.
     1676     * @param {string}                    [attributes.url]                Unused. @todo Consider removal.
    14591677     */
    14601678    media.controller.EditImage = media.controller.State.extend({
     
    14621680            id:      'edit-image',
    14631681            title:   l10n.editImage,
    1464             // Region mode defaults.
    14651682            menu:    false,
    14661683            toolbar: 'edit-image',
    14671684            content: 'edit-image',
    1468 
    14691685            url:     ''
    14701686        },
     
    15151731     * wp.media.controller.MediaLibrary
    15161732     *
    1517      * @constructor
     1733     * @class
    15181734     * @augments wp.media.controller.Library
    15191735     * @augments wp.media.controller.State
     
    15471763         */
    15481764        activate: function() {
     1765            // @todo this should use this.frame.
    15491766            if ( media.frame.lastMime ) {
    15501767                this.set( 'library', media.query({ type: media.frame.lastMime }) );
     
    15581775     * wp.media.controller.Embed
    15591776     *
    1560      * @constructor
     1777     * A state for embedding media from a URL.
     1778     *
     1779     * @class
    15611780     * @augments wp.media.controller.State
    15621781     * @augments Backbone.Model
     1782     *
     1783     * @param {object} attributes                         The attributes hash passed to the state.
     1784     * @param {string} [attributes.id=embed]              Unique identifier.
     1785     * @param {string} [attributes.title=Insert From URL] Title for the state. Displays in the media menu and the frame's title region.
     1786     * @param {string} [attributes.content=embed]         Initial mode for the content region.
     1787     * @param {string} [attributes.menu=default]          Initial mode for the menu region.
     1788     * @param {string} [attributes.toolbar=main-embed]    Initial mode for the toolbar region.
     1789     * @param {string} [attributes.menu=false]            Initial mode for the menu region.
     1790     * @param {int}    [attributes.priority=120]          The priority for the state link in the media menu.
     1791     * @param {string} [attributes.type=link]             The type of embed. Currently only link is supported.
     1792     * @param {string} [attributes.url]                   The embed URL.
     1793     * @param {object} [attributes.metadata={}]           Properties of the embed, which will override attributes.url if set.
    15631794     */
    15641795    media.controller.Embed = media.controller.State.extend({
     
    15661797            id:       'embed',
    15671798            title:    l10n.insertFromUrlTitle,
    1568             // Region mode defaults.
    15691799            content:  'embed',
    15701800            menu:     'default',
    15711801            toolbar:  'main-embed',
    1572 
    15731802            priority: 120,
    15741803            type:     'link',
     
    15901819
    15911820        /**
     1821         * Trigger a scan of the embedded URL's content for metadata required to embed.
     1822         *
    15921823         * @fires wp.media.controller.Embed#scan
    15931824         */
     
    16221853        },
    16231854        /**
     1855         * Try scanning the embed as an image to discover its dimensions.
     1856         *
    16241857         * @param {Object} attributes
    16251858         */
     
    16711904     * wp.media.controller.Cropper
    16721905     *
    1673      * Allows for a cropping step.
    1674      *
    1675      * @constructor
     1906     * A state for cropping an image.
     1907     *
     1908     * @class
    16761909     * @augments wp.media.controller.State
    16771910     * @augments Backbone.Model
     
    17752008
    17762009    /**
    1777      * ========================================================================
    1778      * VIEWS
    1779      * ========================================================================
    1780      */
    1781 
    1782     /**
    17832010     * wp.media.View
    1784      * -------------
    1785      *
    1786      * The base view class.
     2011     *
     2012     * The base view class for media.
    17872013     *
    17882014     * Undelegating events, removing events from the model, and
     
    17932019     * outside of the media manager.
    17942020     *
    1795      * @constructor
     2021     * @class
    17962022     * @augments wp.Backbone.View
    17972023     * @augments Backbone.View
     
    18052031        },
    18062032        /**
     2033         * @todo The internal comment mentions this might have been a stop-gap
     2034         *       before Backbone 0.9.8 came out. Figure out if Backbone core takes
     2035         *       care of this in Backbone.View now.
     2036         *
    18072037         * @returns {wp.media.View} Returns itself to allow chaining
    18082038         */
     
    18442074     *
    18452075     * A frame is a composite view consisting of one or more regions and one or more
    1846      * states. Only one state can be active at any given moment.
    1847      *
    1848      * @constructor
     2076     * states.
     2077     *
     2078     * @see wp.media.controller.State
     2079     * @see wp.media.controller.Region
     2080     *
     2081     * @class
    18492082     * @augments wp.media.View
    18502083     * @augments wp.Backbone.View
     
    18762109        },
    18772110        /**
     2111         * Create the frame's states.
     2112         *
     2113         * @see wp.media.controller.State
     2114         * @see wp.media.controller.StateMachine
     2115         *
    18782116         * @fires wp.media.controller.State#ready
    18792117         */
     
    18942132            }
    18952133        },
     2134
     2135        /**
     2136         * A frame can be in a mode or multiple modes at one time.
     2137         *
     2138         * For example, the manage media frame can be in the `Bulk Select` or `Edit` mode.
     2139         */
    18962140        _createModes: function() {
    18972141            // Store active "modes" that the frame is in. Unrelated to region modes.
     
    19042148        },
    19052149        /**
     2150         * Reset all states on the frame to their defaults.
     2151         *
    19062152         * @returns {wp.media.view.Frame} Returns itself to allow chaining
    19072153         */
     
    19902236     * wp.media.view.MediaFrame
    19912237     *
    1992      * Type of frame used to create the media modal.
    1993      *
    1994      * @constructor
     2238     * The frame used to create the media modal.
     2239     *
     2240     * @class
    19952241     * @augments wp.media.view.Frame
    19962242     * @augments wp.media.View
     
    22252471     * wp.media.view.MediaFrame.Select
    22262472     *
    2227      * Type of media frame that is used to select an item or items from the media library
    2228      *
    2229      * @constructor
     2473     * A frame for selecting an item or items from the media library.
     2474     *
     2475     * @class
    22302476     * @augments wp.media.view.MediaFrame
    22312477     * @augments wp.media.view.Frame
     
    23892635     * wp.media.view.MediaFrame.Post
    23902636     *
    2391      * @constructor
     2637     * The frame for manipulating media on the Edit Post page.
     2638     *
     2639     * @class
    23922640     * @augments wp.media.view.MediaFrame.Select
    23932641     * @augments wp.media.view.MediaFrame
     
    24252673        },
    24262674
     2675        /**
     2676         * Create the default states.
     2677         */
    24272678        createStates: function() {
    24282679            var options = this.options;
    24292680
    2430             // Add the default states.
    24312681            this.states.add([
    24322682                // Main states.
     
    31093359     * wp.media.view.MediaFrame.ImageDetails
    31103360     *
    3111      * @constructor
     3361     * A media frame for manipulating an image that's already been inserted
     3362     * into a post.
     3363     *
     3364     * @class
    31123365     * @augments wp.media.view.MediaFrame.Select
    31133366     * @augments wp.media.view.MediaFrame
     
    31313384
    31323385        initialize: function( options ) {
     3386            debugger;
    31333387            this.image = new media.model.PostImage( options.metadata );
    31343388            this.options.selection = new media.model.Selection( this.image.attachment, { multiple: false } );
     
    32763530     * wp.media.view.Modal
    32773531     *
    3278      * @constructor
     3532     * A modal view, which the media modal uses as its default container.
     3533     *
     3534     * @class
    32793535     * @augments wp.media.View
    32803536     * @augments wp.Backbone.View
     
    34813737     * wp.media.view.FocusManager
    34823738     *
    3483      * @constructor
     3739     * @class
    34843740     * @augments wp.media.View
    34853741     * @augments wp.Backbone.View
     
    35233779     * wp.media.view.UploaderWindow
    35243780     *
    3525      * @constructor
     3781     * An uploader window that allows for dragging and dropping media.
     3782     *
     3783     * @class
    35263784     * @augments wp.media.View
    35273785     * @augments wp.Backbone.View
    35283786     * @augments Backbone.View
     3787     *
     3788     * @param {object} [options]                   Options hash passed to the view.
     3789     * @param {object} [options.uploader]          Uploader properties.
     3790     * @param {jQuery} [options.uploader.browser]
     3791     * @param {jQuery} [options.uploader.dropzone] jQuery collection of the dropzone.
     3792     * @param {object} [options.uploader.params]
    35293793     */
    35303794    media.view.UploaderWindow = media.View.extend({
     
    36203884     * wp.media.view.EditorUploader
    36213885     *
    3622      * @constructor
     3886     * @class
    36233887     * @augments wp.media.View
    36243888     * @augments wp.Backbone.View
     
    37243988        },
    37253989
     3990        /**
     3991         * When a file is dropped on the editor uploader, open up an editor media workflow
     3992         * and upload the file immediately.
     3993         *
     3994         * @param  {jQuery.Event} event The 'drop' event.
     3995         */
    37263996        drop: function( event ) {
    37273997            var $wrap = null, uploadView;
     
    37634033        },
    37644034
     4035        /**
     4036         * Add the files to the uploader.
     4037         */
    37654038        addFiles: function() {
    37664039            if ( this.files.length ) {
     
    38134086     * wp.media.view.UploaderInline
    38144087     *
    3815      * @constructor
     4088     * The inline uploader that shows up in the 'Upload Files' tab.
     4089     *
     4090     * @class
    38164091     * @augments wp.media.View
    38174092     * @augments wp.Backbone.View
     
    39364211     * wp.media.view.UploaderStatus
    39374212     *
    3938      * @constructor
     4213     * An uploader status for on-going uploads.
     4214     *
     4215     * @class
    39394216     * @augments wp.media.View
    39404217     * @augments wp.Backbone.View
     
    40664343     * wp.media.view.UploaderStatusError
    40674344     *
    4068      * @constructor
     4345     * @class
    40694346     * @augments wp.media.View
    40704347     * @augments wp.Backbone.View
     
    40794356     * wp.media.view.Toolbar
    40804357     *
    4081      * @constructor
     4358     * A toolbar which consists of a primary and a secondary section. Each sections
     4359     * can be filled with views.
     4360     *
     4361     * @class
    40824362     * @augments wp.media.View
    40834363     * @augments wp.Backbone.View
     
    42304510     * wp.media.view.Toolbar.Select
    42314511     *
    4232      * @constructor
     4512     * @class
    42334513     * @augments wp.media.view.Toolbar
    42344514     * @augments wp.media.View
     
    42954575     * wp.media.view.Toolbar.Embed
    42964576     *
    4297      * @constructor
     4577     * @class
    42984578     * @augments wp.media.view.Toolbar.Select
    42994579     * @augments wp.media.view.Toolbar
     
    43274607     * wp.media.view.Button
    43284608     *
    4329      * @constructor
     4609     * @class
    43304610     * @augments wp.media.View
    43314611     * @augments wp.Backbone.View
     
    44104690     * wp.media.view.ButtonGroup
    44114691     *
    4412      * @constructor
     4692     * @class
    44134693     * @augments wp.media.View
    44144694     * @augments wp.Backbone.View
     
    44504730     * wp.media.view.PriorityList
    44514731     *
    4452      * @constructor
     4732     * @class
    44534733     * @augments wp.media.View
    44544734     * @augments wp.Backbone.View
     
    45444824     * wp.media.view.MenuItem
    45454825     *
    4546      * @constructor
     4826     * @class
    45474827     * @augments wp.media.View
    45484828     * @augments wp.Backbone.View
     
    46104890     * wp.media.view.Menu
    46114891     *
    4612      * @constructor
     4892     * @class
    46134893     * @augments wp.media.view.PriorityList
    46144894     * @augments wp.media.View
     
    47205000     * wp.media.view.RouterItem
    47215001     *
    4722      * @constructor
     5002     * @class
    47235003     * @augments wp.media.view.MenuItem
    47245004     * @augments wp.media.View
     
    47415021     * wp.media.view.Router
    47425022     *
    4743      * @constructor
     5023     * @class
    47445024     * @augments wp.media.view.Menu
    47455025     * @augments wp.media.view.PriorityList
     
    47745054     * wp.media.view.Sidebar
    47755055     *
    4776      * @constructor
     5056     * @class
    47775057     * @augments wp.media.view.PriorityList
    47785058     * @augments wp.media.View
     
    47875067     * wp.media.view.Attachment
    47885068     *
    4789      * @constructor
     5069     * @class
    47905070     * @augments wp.media.View
    47915071     * @augments wp.Backbone.View
     
    53205600     * wp.media.view.Attachment.Library
    53215601     *
    5322      * @constructor
     5602     * @class
    53235603     * @augments wp.media.view.Attachment
    53245604     * @augments wp.media.View
     
    53355615     * wp.media.view.Attachment.EditLibrary
    53365616     *
    5337      * @constructor
     5617     * @class
    53385618     * @augments wp.media.view.Attachment
    53395619     * @augments wp.media.View
     
    53505630     * wp.media.view.Attachments
    53515631     *
    5352      * @constructor
     5632     * @class
    53535633     * @augments wp.media.View
    53545634     * @augments wp.Backbone.View
     
    56425922     * wp.media.view.Search
    56435923     *
    5644      * @constructor
     5924     * @class
    56455925     * @augments wp.media.View
    56465926     * @augments wp.Backbone.View
     
    56845964     * wp.media.view.AttachmentFilters
    56855965     *
    5686      * @constructor
     5966     * @class
    56875967     * @augments wp.media.View
    56885968     * @augments wp.Backbone.View
     
    57566036     * A filter dropdown for month/dates.
    57576037     *
    5758      * @constructor
     6038     * @class
    57596039     * @augments wp.media.view.AttachmentFilters
    57606040     * @augments wp.media.View
     
    57916071     * wp.media.view.AttachmentFilters.Uploaded
    57926072     *
    5793      * @constructor
     6073     * @class
    57946074     * @augments wp.media.view.AttachmentFilters
    57956075     * @augments wp.media.View
     
    58446124     * wp.media.view.AttachmentFilters.All
    58456125     *
    5846      * @constructor
     6126     * @class
    58476127     * @augments wp.media.view.AttachmentFilters
    58486128     * @augments wp.media.View
     
    59286208     * wp.media.view.AttachmentsBrowser
    59296209     *
    5930      * @constructor
     6210     * @class
    59316211     * @augments wp.media.View
    59326212     * @augments wp.Backbone.View
     
    63456625     * wp.media.view.Selection
    63466626     *
    6347      * @constructor
     6627     * @class
    63486628     * @augments wp.media.View
    63496629     * @augments wp.Backbone.View
     
    64236703     * wp.media.view.Attachment.Selection
    64246704     *
    6425      * @constructor
     6705     * @class
    64266706     * @augments wp.media.view.Attachment
    64276707     * @augments wp.media.View
     
    64426722     * wp.media.view.Attachments.Selection
    64436723     *
    6444      * @constructor
     6724     * @class
    64456725     * @augments wp.media.view.Attachments
    64466726     * @augments wp.media.View
     
    64686748     * wp.media.view.Attachments.EditSelection
    64696749     *
    6470      * @constructor
     6750     * @class
    64716751     * @augments wp.media.view.Attachment.Selection
    64726752     * @augments wp.media.view.Attachment
     
    64856765     * wp.media.view.Settings
    64866766     *
    6487      * @constructor
     6767     * @class
    64886768     * @augments wp.media.View
    64896769     * @augments wp.Backbone.View
     
    65996879     * wp.media.view.Settings.AttachmentDisplay
    66006880     *
    6601      * @constructor
     6881     * @class
    66026882     * @augments wp.media.view.Settings
    66036883     * @augments wp.media.View
     
    66896969     * wp.media.view.Settings.Gallery
    66906970     *
    6691      * @constructor
     6971     * @class
    66926972     * @augments wp.media.view.Settings
    66936973     * @augments wp.media.View
     
    67036983     * wp.media.view.Settings.Playlist
    67046984     *
    6705      * @constructor
     6985     * @class
    67066986     * @augments wp.media.view.Settings
    67076987     * @augments wp.media.View
     
    67176997     * wp.media.view.Attachment.Details
    67186998     *
    6719      * @constructor
     6999     * @class
    67207000     * @augments wp.media.view.Attachment
    67217001     * @augments wp.media.View
     
    68477127     * A view to display fields added via the `attachment_fields_to_edit` filter.
    68487128     *
    6849      * @constructor
     7129     * @class
    68507130     * @augments wp.media.View
    68517131     * @augments wp.Backbone.View
     
    69247204     * wp.media.view.Iframe
    69257205     *
    6926      * @constructor
     7206     * @class
    69277207     * @augments wp.media.View
    69287208     * @augments wp.Backbone.View
     
    69457225     * wp.media.view.Embed
    69467226     *
    6947      * @constructor
     7227     * @class
    69487228     * @augments wp.media.View
    69497229     * @augments wp.Backbone.View
     
    70047284
    70057285    /**
    7006      * @constructor
     7286     * @class
    70077287     * @augments wp.media.View
    70087288     * @augments wp.Backbone.View
     
    70277307     * wp.media.view.EmbedUrl
    70287308     *
    7029      * @constructor
     7309     * @class
    70307310     * @augments wp.media.View
    70317311     * @augments wp.Backbone.View
     
    71017381     * wp.media.view.EmbedLink
    71027382     *
    7103      * @constructor
     7383     * @class
    71047384     * @augments wp.media.view.Settings
    71057385     * @augments wp.media.View
     
    71617441     * wp.media.view.EmbedImage
    71627442     *
    7163      * @constructor
     7443     * @class
    71647444     * @augments wp.media.view.Settings.AttachmentDisplay
    71657445     * @augments wp.media.view.Settings
     
    71887468     * wp.media.view.ImageDetails
    71897469     *
    7190      * @constructor
     7470     * @class
    71917471     * @augments wp.media.view.Settings.AttachmentDisplay
    71927472     * @augments wp.media.view.Settings
     
    73547634     * wp.customize.HeaderControl.openMM.
    73557635     *
    7356      * @constructor
     7636     * @class
    73577637     * @augments wp.media.View
    73587638     * @augments wp.Backbone.View
     
    74557735     * wp.media.view.Spinner
    74567736     *
    7457      * @constructor
     7737     * @class
    74587738     * @augments wp.media.View
    74597739     * @augments wp.Backbone.View
Note: See TracChangeset for help on using the changeset viewer.