WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

See #26870.


Built from https://develop.svn.wordpress.org/trunk@26984


git-svn-id: http://core.svn.wordpress.org/trunk@26861 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Scott Taylor 2014-01-20 23:35:15 +00:00
parent 910ec9c462
commit 8457a40032
1 changed files with 269 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

326
wp-includes/js/media-editor.js
View File

@ -3,13 +3,28 @@
// WordPress, TinyMCE, and Media // WordPress, TinyMCE, and Media
// ----------------------------- // -----------------------------
(function($){ (function($){
// Stores the editors' `wp.media.controller.Frame` instances. /**
* Stores the editors' `wp.media.controller.Frame` instances.
*
* @static
*/
var workflows = {}; var workflows = {};
/**
* wp.media.string
*/
wp.media.string = { wp.media.string = {
// Joins the `props` and `attachment` objects, /**
// outputting the proper object format based on the * Joins the `props` and `attachment` objects,
// attachment's type. * outputting the proper object format based on the
* attachment's type.
*
* @global wp.media.view.settings.defaultProps
*
* @param {Object} props
* @param {Object} attachment
* @returns {Object} Joined props
*/
props: function( props, attachment ) { props: function( props, attachment ) {
var link, linkUrl, size, sizes, fallbacks, var link, linkUrl, size, sizes, fallbacks,
defaultProps = wp.media.view.settings.defaultProps; defaultProps = wp.media.view.settings.defaultProps;
@ -28,8 +43,9 @@
props = props ? _.clone( props ) : {}; props = props ? _.clone( props ) : {};
if ( attachment && attachment.type ) if ( attachment && attachment.type ) {
props.type = attachment.type; props.type = attachment.type;
}
if ( 'image' === props.type ) { if ( 'image' === props.type ) {
props = _.defaults( props || {}, { props = _.defaults( props || {}, {
@ -41,18 +57,20 @@
} }
// All attachment-specific settings follow. // All attachment-specific settings follow.
if ( ! attachment ) if ( ! attachment ) {
return fallbacks( props ); return fallbacks( props );
}
props.title = props.title || attachment.title; props.title = props.title || attachment.title;
link = props.link || defaultProps.link || getUserSetting( 'urlbutton', 'file' ); link = props.link || defaultProps.link || getUserSetting( 'urlbutton', 'file' );
if ( 'file' === link || 'embed' === link ) if ( 'file' === link || 'embed' === link ) {
linkUrl = attachment.url; linkUrl = attachment.url;
else if ( 'post' === link ) } else if ( 'post' === link ) {
linkUrl = attachment.link; linkUrl = attachment.link;
else if ( 'custom' === link ) } else if ( 'custom' === link ) {
linkUrl = props.linkUrl; linkUrl = props.linkUrl;
}
props.linkUrl = linkUrl || ''; props.linkUrl = linkUrl || '';
// Format properties for images. // Format properties for images.
@ -79,6 +97,15 @@
return fallbacks( props ); return fallbacks( props );
}, },
/**
* Create the markup for a link
*
* @global wp.html.string
*
* @param {Object} props
* @param {Object} attachment
* @returns {string} The link markup
*/
link: function( props, attachment ) { link: function( props, attachment ) {
var options; var options;
@ -92,20 +119,45 @@
} }
}; };
if ( props.rel ) if ( props.rel ) {
options.attrs.rel = props.rel; options.attrs.rel = props.rel;
}
return wp.html.string( options ); return wp.html.string( options );
}, },
/**
* Create an Audio shortcode
*
* @param {Object} props
* @param {Object} attachment
* @returns {string} The audio shortcode
*/
audio: function( props, attachment ) { audio: function( props, attachment ) {
return wp.media.string._audioVideo( 'audio', props, attachment ); return wp.media.string._audioVideo( 'audio', props, attachment );
}, },
/**
* Create a Video shortcode
*
* @param {Object} props
* @param {Object} attachment
* @returns {string} The video shortcode
*/
video: function( props, attachment ) { video: function( props, attachment ) {
return wp.media.string._audioVideo( 'video', props, attachment ); return wp.media.string._audioVideo( 'video', props, attachment );
}, },
/**
* Helper function to create a media shortcode
*
* @access private
*
* @global wp.shortcode
* @global wp.media.view.settings
*
* @param {string} type The shortcode tag name: 'audio' or 'video'.
* @param {Object} props
* @param {Object} attachment
* @returns {string} The media shortcode
*/
_audioVideo: function( type, props, attachment ) { _audioVideo: function( type, props, attachment ) {
var shortcode, html, extension; var shortcode, html, extension;
@ -116,11 +168,13 @@
shortcode = {}; shortcode = {};
if ( 'video' === type ) { if ( 'video' === type ) {
if ( attachment.width ) if ( attachment.width ) {
shortcode.width = attachment.width; shortcode.width = attachment.width;
}
if ( attachment.height ) if ( attachment.height ) {
shortcode.height = attachment.height; shortcode.height = attachment.height;
}
} }
extension = attachment.filename.split('.').pop(); extension = attachment.filename.split('.').pop();
@ -139,7 +193,16 @@
return html; return html;
}, },
/**
* Create image markup, optionally with a link and/or wrapped in a caption shortcode
*
* @global wp.html
* @global wp.shortcode
*
* @param {Object} props
* @param {Object} attachment
* @returns {string}
*/
image: function( props, attachment ) { image: function( props, attachment ) {
var img = {}, var img = {},
options, classes, shortcode, html; options, classes, shortcode, html;
@ -152,11 +215,13 @@
// Only assign the align class to the image if we're not printing // Only assign the align class to the image if we're not printing
// a caption, since the alignment is sent to the shortcode. // a caption, since the alignment is sent to the shortcode.
if ( props.align && ! props.caption ) if ( props.align && ! props.caption ) {
classes.push( 'align' + props.align ); classes.push( 'align' + props.align );
}
if ( props.size ) if ( props.size ) {
classes.push( 'size-' + props.size ); classes.push( 'size-' + props.size );
}
img['class'] = _.compact( classes ).join(' '); img['class'] = _.compact( classes ).join(' ');
@ -184,14 +249,17 @@
if ( props.caption ) { if ( props.caption ) {
shortcode = {}; shortcode = {};
if ( img.width ) if ( img.width ) {
shortcode.width = img.width; shortcode.width = img.width;
}
if ( props.captionId ) if ( props.captionId ) {
shortcode.id = props.captionId; shortcode.id = props.captionId;
}
if ( props.align ) if ( props.align ) {
shortcode.align = 'align' + props.align; shortcode.align = 'align' + props.align;
}
html = wp.shortcode.string({ html = wp.shortcode.string({
tag: 'caption', tag: 'caption',
@ -204,10 +272,23 @@
} }
}; };
/**
* wp.media.gallery
*
* @type {Object}
*/
wp.media.gallery = (function() { wp.media.gallery = (function() {
/**
*
* @static
* @type object
*/
var galleries = {}; var galleries = {};
return { return {
/**
* @global wp.media.view.settings
*/
defaults: { defaults: {
order: 'ASC', order: 'ASC',
id: wp.media.view.settings.post.id, id: wp.media.view.settings.post.id,
@ -220,6 +301,12 @@
orderby: 'menu_order ID' orderby: 'menu_order ID'
}, },
/**
* @global wp.media.query
*
* @param {Object} shortcode
* @returns {Object}
*/
attachments: function( shortcode ) { attachments: function( shortcode ) {
var shortcodeString = shortcode.string(), var shortcodeString = shortcode.string(),
result = galleries[ shortcodeString ], result = galleries[ shortcodeString ],
@ -227,8 +314,9 @@
delete galleries[ shortcodeString ]; delete galleries[ shortcodeString ];
if ( result ) if ( result ) {
return result; return result;
}
// Fill the default shortcode attributes. // Fill the default shortcode attributes.
attrs = _.defaults( shortcode.attrs.named, wp.media.gallery.defaults ); attrs = _.defaults( shortcode.attrs.named, wp.media.gallery.defaults );
@ -238,15 +326,17 @@
args.perPage = -1; args.perPage = -1;
// Mark the `orderby` override attribute. // Mark the `orderby` override attribute.
if( undefined !== attrs.orderby ) if( undefined !== attrs.orderby ) {
attrs._orderByField = attrs.orderby; attrs._orderByField = attrs.orderby;
}
if ( 'rand' === attrs.orderby ) if ( 'rand' === attrs.orderby ) {
attrs._orderbyRandom = true; attrs._orderbyRandom = true;
}
// Map the `orderby` attribute to the corresponding model property. // Map the `orderby` attribute to the corresponding model property.
if ( ! attrs.orderby || /^menu_order(?: ID)?$/i.test( attrs.orderby ) ) if ( ! attrs.orderby || /^menu_order(?: ID)?$/i.test( attrs.orderby ) ) {
args.orderby = 'menuOrder'; args.orderby = 'menuOrder';
}
// Map the `ids` param to the correct query args. // Map the `ids` param to the correct query args.
if ( attrs.ids ) { if ( attrs.ids ) {
@ -256,11 +346,13 @@
args.post__in = attrs.include.split(','); args.post__in = attrs.include.split(',');
} }
if ( attrs.exclude ) if ( attrs.exclude ) {
args.post__not_in = attrs.exclude.split(','); args.post__not_in = attrs.exclude.split(',');
}
if ( ! args.post__in ) if ( ! args.post__in ) {
args.uploadedTo = attrs.id; args.uploadedTo = attrs.id;
}
// Collect the attributes that were not included in `args`. // Collect the attributes that were not included in `args`.
others = _.omit( attrs, 'id', 'ids', 'include', 'exclude', 'orderby', 'order' ); others = _.omit( attrs, 'id', 'ids', 'include', 'exclude', 'orderby', 'order' );
@ -270,13 +362,21 @@
return query; return query;
}, },
/**
* @global wp.shortcode
* @global wp.media.model.Attachments
*
* @param {Object} attachments
* @returns {wp.shortcode}
*/
shortcode: function( attachments ) { shortcode: function( attachments ) {
var props = attachments.props.toJSON(), var props = attachments.props.toJSON(),
attrs = _.pick( props, 'orderby', 'order' ), attrs = _.pick( props, 'orderby', 'order' ),
shortcode, clone; shortcode, clone;
if ( attachments.gallery ) if ( attachments.gallery ) {
_.extend( attrs, attachments.gallery.toJSON() ); _.extend( attrs, attachments.gallery.toJSON() );
}
// Convert all gallery shortcodes to use the `ids` property. // Convert all gallery shortcodes to use the `ids` property.
// Ignore `post__in` and `post__not_in`; the attachments in // Ignore `post__in` and `post__not_in`; the attachments in
@ -284,24 +384,27 @@
attrs.ids = attachments.pluck('id'); attrs.ids = attachments.pluck('id');
// Copy the `uploadedTo` post ID. // Copy the `uploadedTo` post ID.
if ( props.uploadedTo ) if ( props.uploadedTo ) {
attrs.id = props.uploadedTo; attrs.id = props.uploadedTo;
}
// Check if the gallery is randomly ordered. // Check if the gallery is randomly ordered.
delete attrs.orderby; delete attrs.orderby;
if ( attrs._orderbyRandom ) if ( attrs._orderbyRandom ) {
attrs.orderby = 'rand'; attrs.orderby = 'rand';
else if ( attrs._orderByField && attrs._orderByField != 'rand' ) } else if ( attrs._orderByField && attrs._orderByField != 'rand' ) {
attrs.orderby = attrs._orderByField; attrs.orderby = attrs._orderByField;
}
delete attrs._orderbyRandom; delete attrs._orderbyRandom;
delete attrs._orderByField; delete attrs._orderByField;
// If the `ids` attribute is set and `orderby` attribute // If the `ids` attribute is set and `orderby` attribute
// is the default value, clear it for cleaner output. // is the default value, clear it for cleaner output.
if ( attrs.ids && 'post__in' === attrs.orderby ) if ( attrs.ids && 'post__in' === attrs.orderby ) {
delete attrs.orderby; delete attrs.orderby;
}
// Remove default attributes from the shortcode. // Remove default attributes from the shortcode.
_.each( wp.media.gallery.defaults, function( value, key ) { _.each( wp.media.gallery.defaults, function( value, key ) {
@ -324,21 +427,30 @@
return shortcode; return shortcode;
}, },
/**
* @global wp.shortcode
* @global wp.media.model.Selection
* @global wp.media.view.l10n
*
* @param {string} content
* @returns {wp.media.view.MediaFrame} A media workflow.
*/
edit: function( content ) { edit: function( content ) {
var shortcode = wp.shortcode.next( 'gallery', content ), var shortcode = wp.shortcode.next( 'gallery', content ),
defaultPostId = wp.media.gallery.defaults.id, defaultPostId = wp.media.gallery.defaults.id,
attachments, selection; attachments, selection;
// Bail if we didn't match the shortcode or all of the content. // Bail if we didn't match the shortcode or all of the content.
if ( ! shortcode || shortcode.content !== content ) if ( ! shortcode || shortcode.content !== content ) {
return; return;
}
// Ignore the rest of the match object. // Ignore the rest of the match object.
shortcode = shortcode.shortcode; shortcode = shortcode.shortcode;
if ( _.isUndefined( shortcode.get('id') ) && ! _.isUndefined( defaultPostId ) ) if ( _.isUndefined( shortcode.get('id') ) && ! _.isUndefined( defaultPostId ) ) {
shortcode.set( 'id', defaultPostId ); shortcode.set( 'id', defaultPostId );
}
attachments = wp.media.gallery.attachments( shortcode ); attachments = wp.media.gallery.attachments( shortcode );
@ -359,8 +471,9 @@
}); });
// Destroy the previous gallery frame. // Destroy the previous gallery frame.
if ( this.frame ) if ( this.frame ) {
this.frame.dispose(); this.frame.dispose();
}
// Store the current gallery frame. // Store the current gallery frame.
this.frame = wp.media({ this.frame = wp.media({
@ -377,11 +490,30 @@
}; };
}()); }());
/**
* wp.media.featuredImage
*/
wp.media.featuredImage = { wp.media.featuredImage = {
/**
* Get the featured image post ID
*
* @global wp.media.view.settings
*
* @returns {wp.media.view.settings.post.featuredImageId|Number}
*/
get: function() { get: function() {
return wp.media.view.settings.post.featuredImageId; return wp.media.view.settings.post.featuredImageId;
}, },
/**
* Set the featured image id, save the post thumbnail data and
* set the HTML in the post meta box to the new featured image.
*
* @global wp.media.view.settings
* @global wp.media.post
*
* @param {number} id
*/
set: function( id ) { set: function( id ) {
var settings = wp.media.view.settings; var settings = wp.media.view.settings;
@ -396,10 +528,18 @@
$( '.inside', '#postimagediv' ).html( html ); $( '.inside', '#postimagediv' ).html( html );
}); });
}, },
/**
* The Featured Image workflow
*
* @global wp.media.controller.FeaturedImage
* @global wp.media.view.l10n
*
* @returns {wp.media.view.MediaFrame} A media workflow.
*/
frame: function() { frame: function() {
if ( this._frame ) if ( this._frame ) {
return this._frame; return this._frame;
}
this._frame = wp.media({ this._frame = wp.media({
state: 'featured-image', state: 'featured-image',
@ -415,28 +555,35 @@
this._frame.state('featured-image').on( 'select', this.select ); this._frame.state('featured-image').on( 'select', this.select );
return this._frame; return this._frame;
}, },
/**
* @global wp.media.view.settings
*/
select: function() { select: function() {
var settings = wp.media.view.settings, var settings = wp.media.view.settings,
selection = this.get('selection').single(); selection = this.get('selection').single();
if ( ! settings.post.featuredImageId ) if ( ! settings.post.featuredImageId ) {
return; return;
}
wp.media.featuredImage.set( selection ? selection.id : -1 ); wp.media.featuredImage.set( selection ? selection.id : -1 );
}, },
/**
* Open the content media manager to the 'featured image' tab when
* the post thumbnail is clicked.
*
* Update the featured image id when the 'remove' link is clicked.
*
* @global wp.media.view.settings
*/
init: function() { init: function() {
// Open the content media manager to the 'featured image' tab when
// the post thumbnail is clicked.
$('#postimagediv').on( 'click', '#set-post-thumbnail', function( event ) { $('#postimagediv').on( 'click', '#set-post-thumbnail', function( event ) {
event.preventDefault(); event.preventDefault();
// Stop propagation to prevent thickbox from activating. // Stop propagation to prevent thickbox from activating.
event.stopPropagation(); event.stopPropagation();
wp.media.featuredImage.frame().open(); wp.media.featuredImage.frame().open();
// Update the featured image id when the 'remove' link is clicked.
}).on( 'click', '#remove-post-thumbnail', function() { }).on( 'click', '#remove-post-thumbnail', function() {
wp.media.view.settings.post.featuredImageId = -1; wp.media.view.settings.post.featuredImageId = -1;
}); });
@ -445,7 +592,16 @@
$( wp.media.featuredImage.init ); $( wp.media.featuredImage.init );
/**
* wp.media.editor
*/
wp.media.editor = { wp.media.editor = {
/**
* @global tinymce
* @global QTags
*
* @param {string} html
*/
insert: function( html ) { insert: function( html ) {
var editor, var editor,
hasTinymce = typeof tinymce !== 'undefined', hasTinymce = typeof tinymce !== 'undefined',
@ -485,11 +641,21 @@
} }
}, },
/**
* @global wp.media.view.l10n
*
* @param {string} id A slug used to identify the workflow.
* @param {Object} [options={}]
*
* @returns {wp.media.view.MediaFrame} A media workflow.
*/
add: function( id, options ) { add: function( id, options ) {
var workflow = this.get( id ); var workflow = this.get( id );
if ( workflow ) // only add once: if exists return existing // only add once: if exists return existing
if ( workflow ) {
return workflow; return workflow;
}
workflow = workflows[ id ] = wp.media( _.defaults( options || {}, { workflow = workflows[ id ] = wp.media( _.defaults( options || {}, {
frame: 'post', frame: 'post',
@ -543,10 +709,11 @@
link: 'none' link: 'none'
}); });
if ( 'none' === embed.link ) if ( 'none' === embed.link ) {
embed.linkUrl = ''; embed.linkUrl = '';
else if ( 'file' === embed.link ) } else if ( 'file' === embed.link ) {
embed.linkUrl = embed.url; embed.linkUrl = embed.url;
}
this.insert( wp.media.string.image( embed ) ); this.insert( wp.media.string.image( embed ) );
} }
@ -557,40 +724,69 @@
return workflow; return workflow;
}, },
/**
* Determines the proper current workflow id
*
* @global wpActiveEditor
* @global tinymce
*
* @param {string} id
* @returns {wpActiveEditor|String|tinymce.activeEditor.id}
*/
id: function( id ) { id: function( id ) {
if ( id ) if ( id ) {
return id; return id;
}
// If an empty `id` is provided, default to `wpActiveEditor`. // If an empty `id` is provided, default to `wpActiveEditor`.
id = wpActiveEditor; id = wpActiveEditor;
// If that doesn't work, fall back to `tinymce.activeEditor.id`. // If that doesn't work, fall back to `tinymce.activeEditor.id`.
if ( ! id && typeof tinymce !== 'undefined' && tinymce.activeEditor ) if ( ! id && typeof tinymce !== 'undefined' && tinymce.activeEditor ) {
id = tinymce.activeEditor.id; id = tinymce.activeEditor.id;
}
// Last but not least, fall back to the empty string. // Last but not least, fall back to the empty string.
id = id || ''; id = id || '';
return id; return id;
}, },
/**
* Return the workflow specified by id
*
* @param {string} id
* @returns {wp.media.view.MediaFrame} A media workflow.
*/
get: function( id ) { get: function( id ) {
id = this.id( id ); id = this.id( id );
return workflows[ id ]; return workflows[ id ];
}, },
/**
* Remove the workflow represented by id from the workflow cache
*
* @param {string} id
*/
remove: function( id ) { remove: function( id ) {
id = this.id( id ); id = this.id( id );
delete workflows[ id ]; delete workflows[ id ];
}, },
send: { send: {
/**
* @global wp.media.view.settings
* @global wp.media.post
*
* @param {Object} props
* @param {Object} attachment
* @returns {Promise}
*/
attachment: function( props, attachment ) { attachment: function( props, attachment ) {
var caption = attachment.caption, var caption = attachment.caption,
options, html; options, html;
// If captions are disabled, clear the caption. // If captions are disabled, clear the caption.
if ( ! wp.media.view.settings.captions ) if ( ! wp.media.view.settings.captions ) {
delete attachment.caption; delete attachment.caption;
}
props = wp.media.string.props( props, attachment ); props = wp.media.string.props( props, attachment );
@ -600,8 +796,9 @@
post_excerpt: caption post_excerpt: caption
}; };
if ( props.linkUrl ) if ( props.linkUrl ) {
options.url = props.linkUrl; options.url = props.linkUrl;
}
if ( 'image' === attachment.type ) { if ( 'image' === attachment.type ) {
html = wp.media.string.image( props ); html = wp.media.string.image( props );
@ -630,7 +827,12 @@
post_id: wp.media.view.settings.post.id post_id: wp.media.view.settings.post.id
}); });
}, },
/**
* @global wp.media.view.settings
*
* @param {Object} embed
* @returns {Promise}
*/
link: function( embed ) { link: function( embed ) {
return wp.media.post( 'send-link-to-editor', { return wp.media.post( 'send-link-to-editor', {
nonce: wp.media.view.settings.nonce.sendToEditor, nonce: wp.media.view.settings.nonce.sendToEditor,
@ -641,7 +843,11 @@
}); });
} }
}, },
/**
* @param {string} id
* @param {Object} options
* @returns {wp.media.view.MediaFrame}
*/
open: function( id, options ) { open: function( id, options ) {
var workflow, editor; var workflow, editor;
@ -662,12 +868,18 @@
workflow = this.get( id ); workflow = this.get( id );
// Redo workflow if state has changed // Redo workflow if state has changed
if ( ! workflow || ( workflow.options && options.state !== workflow.options.state ) ) if ( ! workflow || ( workflow.options && options.state !== workflow.options.state ) ) {
workflow = this.add( id, options ); workflow = this.add( id, options );
}
return workflow.open(); return workflow.open();
}, },
/**
* Bind click event for .insert-media using event delegation
*
* @global wp.media.view.l10n
*/
init: function() { init: function() {
$(document.body).on( 'click', '.insert-media', function( event ) { $(document.body).on( 'click', '.insert-media', function( event ) {
var $this = $(this), var $this = $(this),