Options, methods and events
Every option, property, method and event the editor has, in one place.
Everything the editor's script exports, and everything an editor has. The guides explain each one with examples.
Making an editor
| Export | Does |
|---|---|
appendDefaultEditor(target, options) | Puts an editor in target, an element or a selector, and returns it |
appendDefaultEditors(selector, options) | One editor in each element that matches; returns them all |
openDefaultEditor(options) | Opens an editor in a modal over the page. It also has show() and hide() |
defineDefaultCustomElements(options) | Registers <mastershot-editor>, with options for each one. Resolves once it's registered |
processImage(src, options) | Edits a file without showing an editor and resolves with the result |
getEditorDefaults(options) | The default options with yours over them |
createDefaultImageWriter(options) | A writer with saving options |
appendEditor, appendEditors, openEditor and defineCustomElements do the same without the defaults, so an editor with no file shows no file chooser. Use the Default ones unless you're setting everything yourself.
Options
Pass options when you make an editor. Every one is also a property you can read and set later, as in editor.utils = ["crop"].
| Option | Is |
|---|---|
src | The file to open: a File, a Blob, or a URL |
licenseKey | Your license key, on a live site |
utils | The tools to show: crop, trim, redact, filter, resize |
util | The tool it opens on |
theme | "light", "dark" or "auto" |
imageState | Edits to open the file with |
imageWriter | How the file is saved |
imageCropAspectRatio | Holds the crop to one shape, as width Ă· height |
imageMaxDuration | The most seconds of a video that can be kept |
imageMinDuration | Refuses a video shorter than this, in seconds |
cropSelectPresetOptions | The crop shapes and sizes to choose from |
cropEnableSelectPreset, cropEnableButtonRotateLeft, cropEnableButtonRotateRight, cropEnableRotationInput, cropEnableButtonFlipHorizontal, cropEnableButtonFlipVertical | Parts of the crop tool, all shown by default |
cropRotationRange | How far the straighten slider goes each way, in radians |
trimEnableSplit | Lets your visitor keep several parts of a video |
enableToolbar, enableButtonExport, enableButtonClose, enableButtonRevert, enableNavigateHistory | The buttons |
enableUtils | The tool switcher |
enableBrowseImage, enableDropImage | Choosing or dropping a file when the editor has none |
accept | The files the chooser offers |
muteAudio | Plays videos silent while editing (the default). false plays their sound |
locale | The button labels |
willProcessImage | Runs on Done with the edits; return false to stop the save |
willClose | Runs on Cancel; return false to keep the editor open |
willRevert | Runs on Revert; return false to keep the edits |
disabled | Stops your visitor from making changes |
status | A message shown over the editor, such as "Uploading…" |
id, class | Set on the editor's box |
enableAutoHide, enableAutoDestroy | The modal hides once the file is saved, and is removed once it's hidden. Both true by default |
Properties
Each part of the edits is a property with image in front, such as imageCrop, imageRotation, imageFlipX, imageFlipY, imageRedaction, imageColorMatrix, imageTargetSize, imageTrim and imageVolume. imageState is all of them at once.
Read-only: imageFile, imageSize, imageAspectRatio, imageCropSize, imageDuration, imageLoadState, imageProcessState, and element, the editor's box.
Methods
| Method | Does |
|---|---|
on(event, handler) | Listens for an event. Returns a function that stops listening |
loadImage(src, imageState?) | Opens a file, with edits if you give them |
processImage() | Saves the file as if Done were pressed, and resolves with the result |
abortLoadImage(), abortProcessImage() | Stops opening or saving a file |
removeImage() | Closes the file |
close() | Sends close, as Cancel does |
destroy() | Takes the editor off the page |
history.undo(), history.redo(), history.revert() | Undo, redo and revert |
play(), pause(), togglePlayPause(), isPaused() | Plays a video |
mute(), unmute(), toggleMute() | A video's sound while editing |
getDuration(), getCurrentTime(), setCurrentTime(seconds) | Where a video is |
show(), hide() | The modal, from openDefaultEditor |
Events
Listen with editor.on("process", handler). The <mastershot-editor> element sends each one as a DOM event named mastershot:<event>, with what the handler would get in event.detail.
| Event | Sent |
|---|---|
load | A file is open: { src, dest, size } |
loadstart, loadprogress, loaderror, loadabort | While a file opens |
update | Any edit, with the new imageState |
process | The file is saved: { src, dest, imageState }, and store if it was uploaded |
processstart, processprogress, processerror, processabort | While a file is saved |
undo, redo, revert, writehistory | The history changed |
selectutil | Your visitor switched tools, with the util's name |
play, pause | A video started or stopped |
close | Cancel was pressed |
show, hide | The modal opened or closed |
ready, destroy | The editor is ready, or gone |
Helpers
isSupported() says whether the browser can run the editor: any current Chrome, Edge, Firefox or Safari can. blobToFile(blob, name) turns a Blob into a File. degToRad(degrees) turns degrees into the radians imageRotation takes.