API.md
MediumEditor(elements, options)Creating an instance of MediumEditor will:
contenteditable elements.<textarea> elements:
<textarea><div contenteditable=true> element and add it to the elements array.Arguments
elements (String | HTMLElement | Array | NodeList | HTMLCollection):
String: If passed as a string, this is used as a selector in a call to document.querySelectorAll() to find elements on the page. All results are stored in the internal list of elements.
HTMLElement: If passed as a single element, this will be the only element in the internal list of elements.
Array: If passed as an Array of HTMLElements, this will be used as the internal list of elements.
options (Object):
Set of custom options used to initialize MediumEditor.
destroy()Tear down the editor if already setup by doing the following:
destroy() method on each extension within the editor. This should allow all extension to be torn down and cleaned up, including the toolbar and its elements.<textarea> elements and remove any created <div> elements created for <textarea> elements.setup()Initialize this instance of the editor if it has been destroyed. This will reuse the elements selector and options object passed in when the editor was instantiated.
addElements(elements)Dynamically add one or more elements to an already initialized instance of MediumEditor.
Passing an elements or array of elements to addElements(elements) will:
<textarea> elements:
<textarea><div contenteditable=true> element and add it to the editor elementsSo, every element you pass to addElements will turn into a fully supported contenteditable too - even earlier calls to editor.subscribe(..)
for custom events will work on the newly added element(s).
Arguments
elements (String | HTMLElement | Array | NodeList | HTMLCollection):
String: If passed as a string, this is used as a selector in a call to document.querySelectorAll() to find elements on the page.
HTMLElement: If passed as a single element, this will be the only element added to the editor elements.
Array | NodeList | HTMLCollection: If passed as an Array-like collection of HTMLElements, all of these elements will be added to the editor elements.
removeElements(elements)Remove one or more elements from an already initialized instance of MediumEditor.
Passing an elements or array of elements to removeElements(elements) will:
this.elements array.contenteditable).<textarea> elements and remove any created <div> elements created for <textarea> elements.Each element itself will remain a contenteditable - it will just remove all event handlers and all references to it so you can safely remove it from DOM.
Arguments
elements (String | HTMLElement | Array | NodeList | HTMLCollection):
String: If passed as a string, this is used as a selector in a call to document.querySelectorAll() to find elements on the page.
HTMLElement: If passed as a single element, this will be the only element removed from the editor elements.
Array | NodeList | HTMLCollection: If passed as an Array-like collection of HTMLElements, all of these elements will be removed from the editor elements.
on(targets, event, listener, useCapture)Attaches an event listener to a specific element or elements via the browser's built-in addEventListener(type, listener, useCapture) API. However, this helper method also ensures that when MediumEditor is destroyed, this event listener will be automatically be detached from the DOM.
Arguments
HTMLElement / NodeList):addEventListener(type, listener, useCapture)String):addEventListener(type, listener, useCapture)listener (function):
addEventListener(type, listener, useCapture)useCapture (boolean):
addEventListener(type, listener, useCapture)off(targets, event, listener, useCapture)Detach an event listener from a specific element or elements via the browser's built-in removeEventListener(type, listener, useCapture) API.
Arguments
HTMLElement / NodeList):removeEventListener(type, listener, useCapture)String):removeEventListener(type, listener, useCapture)listener (function):
removeEventListener(type, listener, useCapture)useCapture (boolean):
removeEventListener(type, listener, useCapture)subscribe(name, listener)Attaches a listener for the specified custom event name.
Arguments
String):function):Arguments to listener
Event | object)
* For most custom events, this will be the browser's native Event object for the event that triggered the custom event to fire.
* For some custom events, this will be an object containing information describing the event (depending on which custom event it is)HTMLElement)
* A reference to the contenteditable container element that this custom event corresponds to. This is especially useful for instances where one instance of MediumEditor contains multiple elements, or there are multiple instances of MediumEditor on the page.
* For example, when blur fires, this argument will be the <div contenteditable=true></div> element that is about to receive focus.unsubscribe(name, listener)Detaches a custom event listener for the specified custom event name.
Arguments
String):function):NOTE
trigger(name, data, editable)Manually triggers a custom event.
Arguments
String):Event | object):Event object or custom data object to pass to all the listeners to this custom event.HTMLElement):<div contenteditable=true></div> element to pass to all of the listeners to this custom event.checkSelection()If the toolbar is enabled, manually forces the toolbar to update based on the user's current selection. This includes hiding/showing the toolbar, positioning the toolbar, and updating the enabled/disable state of the toolbar buttons.
exportSelection()Returns a data representation of the selected text, which can be applied via importSelection(selectionState). This data will include the beginning and end of the selection, as well as which of the editor elements the selection was within.
importSelection(selectionState, favorLaterSelectionAnchor)Restores the selection using a data representation of previously selected text (ie value returned by exportSelection()).
Arguments
Object):boolean):true, import the cursor immediately subsequent to an anchor tag if it would otherwise be placed right at the trailing edge inside the anchor. THis cursor positioning, even though visually equivalent to the user, can affect behavior in Internet Explorer.getFocusedElement()Returns a reference to the editor element that currently has focus (if the editor has focus).
getSelectedParentElement(range)Returns a reference to the editor element that the user's selection is currently within.
Arguments
Range): OPTIONALRange to find the selection parent element withincontentWindowrestoreSelection()Restores the selection to what was selected the last time saveSelection() was called.
saveSelection()Internally stores the user's current selection. This can be restored by calling restoreSelection().
selectAllContents()Expands the selection to contain all text within the focused editor element.
selectElement(element)Change the user's selection to select the contents of the provided element and update the toolbar to reflect this change.
Arguments
HTMLElement):stopSelectionUpdates()Stop the toolbar from updating to reflect changes in the user's selection.
startSelectionUpdates()Enable the toolbar to start updating based on the user's selection, after a call to stopSelectionUpdates()
cleanPaste(text)convert text to plaintext and replace current selection with result
Arguments
String):createLink(opts)creates a link via the native document.execCommand('createLink') command
Arguments
Object):Properties of 'opts'
1. _**value** (`String`)_ _**REQUIRED**_
* The url to set as the `href` of the created link. A non-empty value must be provided for the link to be created.
2. _**target** (`String`)_
* Attribute to set as the `target` attribute of the created link. Passing 'self' or not passing this option at all are equivalent in that they will just ensure that `target="_blank"` will NOT be present on the created link.
* **NOTE** If the `targetBlank` option on the editor is set to true, the `target` property of opts will be ignored and `target="_blank"` will be added to all created links.
3. _**buttonClass** (`String`)_
* Class (or classes) to append to the `class` attribute of the created link.
editor.createLink({ value: 'https://github.com/yabwe/medium-editor', target: '_blank', buttonClass: 'medium-link' });
execAction(action, opts)executes an built-in action via document.execCommand
Arguments
String):document.execCommand(command, showDefaultUI, value)Object) OPTIONAL:Properties of 'opts'
1. _**value** (`String`)_
* The value to pass as the 'value' argument to `document.execCommand(command, showDefaultUI, value)`
2. For 'createLink', the `opts` are passed directly to [`.createLink(opts)`]((#createlinkopts)) so see that method for additional options for that command
pasteHTML(html, options)replace the current selection with html
Arguments
String):Object) OPTIONAL:cleanTags, unwrapTags, and/or cleanAttrs for removing/unwrapping specific element types (cleanTags/unwrapTags), or removing specific attributes (cleanAttrs) from the inserted HTML. See cleanTags, unwrapTags, and cleanAttrs in OPTIONS.md for more information.editor.pasteHTML('<p class="classy"><strong>Some Custom HTML</strong></p>', { cleanAttrs: ['class'], cleanTags: ['strong'], unwrapTags: ['em']});
queryCommandState(action)wrapper around the browser's built in document.queryCommandState(command) for checking whether a specific action has already been applied to the selection.
Arguments
String):document.queryCommandState(command)checkContentChanged(editable)Trigger the editor to check for updates to the html, and trigger the editableInput event if needed.
Arguments
HTMLElement): OPTIONAL<div contenteditable=true></div> element that contains the html that may have changed.delay(fn)Delay any function from being executed by the amount of time passed as the delay option.
Arguments
function):getContent(index)Returns the trimmed html content for the first editor element, or the element at index.
Arguments
integer): OPTIONALgetExtensionByName(name)Get a reference to an extension with the specified name.
Arguments
String):toolbar).resetContent(element)Reset the content of all editor elements to their value at the time they were added to the editor. If a specific editor element is provided, only the content of that element will be reset.
Arguments
DOMElement): OPTIONALserialize()Returns a JSON object including the content of each of the elements inside the editor.
setContent(html, index)Sets the html content for the first editor element, or the element at index. Ensures the the editableInput event is triggered.
Arguments
string):integer): OPTIONALgetEditorFromElement(element)Given an editor element, retrieves the instance of MediumEditor which created/is monitoring the element
Arguments
DOMElement):versionObject containing data about the version of the current MediumEditor library
Properties of 'version'
Number)3 in "3.2.1")Number)2 in "3.2.1")Number)1 in "3.2.1")String)"rc.1" in "5.0.0-rc.1")Function)"5.0.0-rc.1")