Docs: Improve JSDocs for cropper.js.

Props manuelaugustin, bramheijmink.
Fixes #42677.



git-svn-id: https://develop.svn.wordpress.org/trunk@42352 602fd350-edb4-49c9-b593-d223f7449a82
This commit is contained in:
Adam Silverstein 2017-12-03 18:46:29 +00:00
parent 4619b059b1
commit 5fbba272df
1 changed files with 51 additions and 1 deletions

View File

@ -4,7 +4,7 @@ var l10n = wp.media.view.l10n,
/**
* wp.media.controller.Cropper
*
* A state for cropping an image.
* A class for cropping an image when called from the header media customization panel.
*
* @memberOf wp.media.controller
*
@ -26,16 +26,43 @@ Cropper = wp.media.controller.State.extend(/** @lends wp.media.controller.Croppe
doCropArgs: {}
},
/**
* @summary Opens the crop image window.
*
* Shows the crop image window when called from the Add new image button.
*
* @since 4.2.0
*
* @returns {void}
*/
activate: function() {
this.frame.on( 'content:create:crop', this.createCropContent, this );
this.frame.on( 'close', this.removeCropper, this );
this.set('selection', new Backbone.Collection(this.frame._selection.single));
},
/**
* @summary Changes the state of the toolbar window to browse mode.
*
* @since 4.2.0
*
* @returns {void}
*/
deactivate: function() {
this.frame.toolbar.mode('browse');
},
/**
* @summary Creates the crop image window.
*
* Initialized when clicking on the Select and Crop button.
*
* @since 4.2.0
*
* @fires crop window
*
* @returns {void}
*/
createCropContent: function() {
this.cropperView = new wp.media.view.Cropper({
controller: this,
@ -45,12 +72,28 @@ Cropper = wp.media.controller.State.extend(/** @lends wp.media.controller.Croppe
this.frame.content.set(this.cropperView);
},
/**
* @summary Removes the image selection and closes the cropping window.
*
* @since 4.2.0
*
* @returns {void}
*/
removeCropper: function() {
this.imgSelect.cancelSelection();
this.imgSelect.setOptions({remove: true});
this.imgSelect.update();
this.cropperView.remove();
},
/**
* @summary Checks if cropping can be skipped and creates crop toolbar accordingly.
*
* @since 4.2.0
*
* @returns {void}
*/
createCropToolbar: function() {
var canSkipCrop, toolbarOptions;
@ -106,6 +149,13 @@ Cropper = wp.media.controller.State.extend(/** @lends wp.media.controller.Croppe
this.frame.toolbar.set( new wp.media.view.Toolbar(toolbarOptions) );
},
/**
* @summary Creates an object with the image attachment and crop properties.
*
* @since 4.2.0
*
* @returns {$.promise} A jQuery promise with the custom header crop details.
*/
doCrop: function( attachment ) {
return wp.ajax.post( 'custom-header-crop', _.extend(
{},