MediumEditor Object API

MediumEditor Object API

• Initialization Functions
  • MediumEditor(elements, options)
  • destroy()
  • setup()
• Event Functions
  • on(target, event, listener, useCapture)
  • off(target, event, listener, useCapture)
  • subscribe(name, listener)
  • unsubscribe(name, listener)
  • trigger(name, data, editable)
• Selection Functions
  • checkSelection()
  • exportSelection()
  • importSelection(selectionState)
  • getFocusedElement()
  • getSelectionParentElement(range)
  • restoreSelection()
  • saveSelection()
  • selectAllContents()
  • selectElement(element)
  • stopSelectionUpdates()
  • startSelectionUpdates()
• Editor Action Functions
  • createLink(opts)
  • cleanPaste(text)
  • execAction(action, opts)
  • pasteHTML(html, options)
  • queryCommandState(action)
• Helper Functions
  • delay(fn)
  • getExtensionByName(name)
  • serialize()

Initialization Functions

MediumEditor(elements, options)

Creating an instance of MediumEditor will:

• Convert all passed in elements into contenteditable elements.
• For any <textarea> elements, hide the <textarea>, create a new <div contenteditable=true> element, and ensure the 2 elements remain sync'd.
• Initialize any custom extensions or buttons passed in.
• Create any additional elements needed.
• Setup all event handling needed to monitor the editable elements.

Arguments

elements (String | HTMLElement | Array):

1. 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.

2. HTMLElement: If passed as a single element, this will be the only element in the internal list of elements.

3. 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()

tears down the editor if already setup, removing all DOM elements and event handlers

---

setup()

rebuilds the editor if it has already been destroyed, recreating DOM elements and attaching event handlers

Event Functions

on(target, event, listener, useCapture)

attach a listener to a DOM event which will be detached when MediumEditor is deactivated

---

off(target, event, listener, useCapture)

detach a listener to a DOM event that was attached via on()

---

subscribe(name, listener)

Attaches a listener for the specified custom event name.

Arguments

1. name (String):

• Name of the event to listen to. See the list of built-in Custom Events below.

2. listener(data, editable) (function):

• Listener method that will be called whenever the custom event is triggered.

Arguments to listener

1. data (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)
2. editable (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

1. name (String):

• Name of the event to detach the listener for.

2. listener (function):

• A reference to the listener to detach. This must be a match by-reference and not a copy.

NOTE

• Calling destroy() on the MediumEditor object will automatically remove all custom event listeners.

---

trigger(name, data, editable)

Manually triggers a custom event.

1. name (String):

• Name of the custom event to trigger.

2. data (Event | object):

• Native Event object or custom data object to pass to all the listeners to this custom event.

3. editable (HTMLElement):

• The <div contenteditable=true></div> element to pass to all of the listeners to this custom event.

Selection Functions

checkSelection()

manually trigger an update of the toolbar and extensions based on the current selection

---

exportSelection()

return a data representation of the selected text, which can be applied via importSelection()

---

importSelection(selectionState)

restore the selection using a data representation of previously selected text (ie value returned by exportSelection())

---

getFocusedElement()

returns an element if any contenteditable element monitored by MediumEditor currently has focused

---

getSelectionParentElement(range)

get the parent contenteditable element that contains the current selection

---

restoreSelection()

restore the selection to what was selected the last time saveSelection() was called

---

saveSelection()

internally store the set of selected text

---

selectAllContents()

expands the selection to contain all text within the focused contenteditable

---

selectElement(element)

change selection to be a specific element and update the toolbar to reflect the selection

---

stopSelectionUpdates()

stop the toolbar from updating to reflect the state of the selected text

---

startSelectionUpdates()

put the toolbar back into its normal updating state

Editor Action Functions

cleanPaste(text)

convert text to plaintext and replace current selection with result

---

createLink(opts)

creates a link via the native document.execCommand('createLink') command

---

execAction(action, opts)

executes an built-in action via document.execCommand

---

pasteHTML(html, options)

replace the current selection with html

---

queryCommandState(action)

wrapper around the browser's built in document.queryCommandState(action) for checking whether a specific action has already been applied to the selection.

Helper Functions

delay(fn)

delay any function from being executed by the amount of time passed as the delay option

---

getExtensionByName(name)

get a reference to an extension with the specified name

---

serialize()

returns a JSON object with elements contents