Class: Editor

Editor

The Editor is a core component of mobiledoc-kit. After instantiating an editor, use Editor#render to display the editor on the web page.

An editor uses a Post internally to represent the displayed document. The post can be serialized as mobiledoc using Editor#serialize. Mobiledoc is the transportable "over-the-wire" format (JSON) that is suited for persisting and sharing between editors and renderers (for display, e.g.), whereas the Post model is better suited for programmatic editing.

The editor will call registered callbacks for certain state changes. These are:

Constructor

new Editor(optionsopt)

Parameters:
Name Type Attributes Description
options Object <optional>
Properties
Name Type Attributes Default Description
mobiledoc Object <optional>

The mobiledoc to load into the editor. Supersedes options.html.

html String | DOM <optional>

The html (as a string or DOM fragment) to parse and load into the editor. Will be ignored if options.mobiledoc is also passed.

parserPlugins Array <optional>
[]
cards Array <optional>
[]

The cards that the editor may render.

atoms Array <optional>
[]

The atoms that the editor may render.

unknownCardHandler function <optional>

Invoked by the editor's renderer whenever it encounters an unknown card.

unknownAtomHandler function <optional>

Invoked by the editor's renderer whenever it encounters an unknown atom.

placeholder String <optional>

Default text to show before user starts typing.

spellcheck Boolean <optional>
true

Whether to enable spellcheck

autofocus Boolean <optional>
true

Whether to focus the editor when it is first rendered.

undoDepth number <optional>
5

How many undo levels will be available. Set to 0 to disable undo/redo functionality.

Source:

Members

activeMarkups :Array.<Markup>

Type:
  • Array.<Markup>
Source:

activeSections :Array.<Section>

The sections from the cursor's selection start to the selection end

Type:
  • Array.<Section>
Source:

builder :PostNodeBuilder

The editor's instance of a post node builder.

Type:
Source:

range

Return the current range for the editor (may be cached).

Source:

Methods

_hasFocus() → {Boolean}

Whether the editor's element is focused It's possible to be focused but have no selection

Source:
See:
Returns:
Type
Boolean

_hasSelection() → {Boolean}

Whether there is a selection inside the editor's element. It's possible to have a selection but not have focus.

Source:
See:
Returns:
Type
Boolean

cursorDidChange(callback)

Parameters:
Name Type Description
callback function

This callback will be called every time the cursor position (or selection) changes.

Source:

deleteAtPosition()

Convenience for PostEditor#deleteAtPosition. Deletes and puts the cursor in the new position.

Source:

deleteRange(range)

Convenience for PostEditor#deleteRange. Deletes and puts the cursor in the new position.

Parameters:
Name Type Description
range Range
Source:

destroy()

Tears down the editor's attached event listeners and views.

Source:

didDelete(callback)

Parameters:
Name Type Description
callback function

This callback will be called after deleting.

Source:

didRender(callback)

Parameters:
Name Type Description
callback function

This callback will be called after the editor is rendered.

Source:

didUpdatePost(callback)

Parameters:
Name Type Description
callback function

Called with postEditor as its argument.

Source:

disableEditing()

Keep the user from directly editing the post using the keyboard and mouse. Modification via the programmatic API is still permitted.

Source:
See:

disableLogging()

Disable all logging

Source:

displayCard(cardSection)

Change a cardSection into display mode If called before the card has been rendered, it will be marked so that it is rendered in display mode when it gets rendered.

Parameters:
Name Type Description
cardSection CardSection
Source:
Returns:

undefined

editCard(cardSection)

Change a cardSection into edit mode If called before the card has been rendered, it will be marked so that it is rendered in edit mode when it gets rendered.

Parameters:
Name Type Description
cardSection CardSection
Source:

enableEditing()

Allow the user to directly interact with editing a post via keyboard and mouse input. Editor instances are editable by default. Use this method to re-enable editing after disabling it.

Source:
See:

enableLogging(logTypesopt)

Turns on verbose logging for the editor.

Parameters:
Name Type Attributes Default Description
logTypes Array <optional>
[]

If present, only the given log types will be logged.

Source:

hasActiveMarkup(markup) → {boolean}

Parameters:
Name Type Description
markup Markup | String

A markup instance, or a string (e.g. "b")

Source:
Returns:
Type
boolean

hasCursor() → {boolean}

Whether the editor has a cursor (or a selected range). It is possible for the editor to be focused but not have a selection. In this case, key events will fire but the editor will not be able to determine a cursor position, so they will be ignored.

Source:
Returns:
Type
boolean

inputModeDidChange(callback)

Parameters:
Name Type Description
callback function

Called when the editor's state (active markups or active sections) has changed, either via user input or programmatically

Source:

insertAtom(atomName, atomTextopt, atomPayloadopt) → {Atom}

Inserts an atom at the current cursor position. If the editor has no current cursor position, nothing will be inserted. If the editor's range is not collapsed, it will be deleted before insertion.

Parameters:
Name Type Attributes Default Description
atomName String
atomText String <optional>
''
atomPayload Object <optional>
{}
Source:
Returns:

The inserted atom.

Type
Atom

insertCard(cardName, cardPayloadopt, inEditModeopt) → {Card}

Inserts a card at the section after the current cursor position. If the editor has no current cursor position, nothing will be inserted. If the editor's range is not collapsed, it will be deleted before insertion. If the cursor is in a blank section, it will be replaced with a card section. The editor's cursor will be placed at the end of the inserted card.

Parameters:
Name Type Attributes Default Description
cardName String
cardPayload Object <optional>
{}
inEditMode Boolean <optional>
false

Whether the card should be inserted in edit mode.

Source:
Returns:

The inserted Card section.

Type
Card

insertText(text)

Inserts the text at the current cursor position. If the editor has no current cursor position, nothing will be inserted. If the editor's range is not collapsed, it will be deleted before insertion.

Parameters:
Name Type Description
text String
Source:

onTextInput(inputHandler)

Register a handler that will be invoked by the editor after the user enters matching text.

Parameters:
Name Type Description
inputHandler Object
Properties
Name Type Attributes Description
name String

Required. Used by identifying handlers.

text String <optional>

Required if match is not provided

match RegExp <optional>

Required if text is not provided

run function

This callback is invoked with the Editor instance and an array of matches. If text was provided, the matches array will equal [text], and if a match regex was provided the matches array will be the result of match.exec on the matching text. The callback is called after the matching text has been inserted.

Source:

positionAtPoint(x, y) → {Position|null}

Parameters:
Name Type Description
x integer

x-position in viewport

y integer

y-position in viewport

Source:
Returns:
Type
Position | null

postDidChange(callback)

Parameters:
Name Type Description
callback function

Called when the post has changed, either via user input or programmatically. Use with Editor#serialize to retrieve the post in portable mobiledoc format.

Source:

registerKeyCommand(keyCommand)

Parameters:
Name Type Description
keyCommand Object

The key command to register. It must specify a modifier key (meta, ctrl, etc), a string representing the ascii key, and a run method that will be passed the editor instance when the key command is invoked

Source:

render(element)

Parameters:
Name Type Description
element Element

The DOM element to render into. Its contents will be replaced by the editor's rendered post.

Source:

run(callback) → {Mixed}

Run a new post editing session. Yields a block with a new PostEditor instance. This instance can be used to interact with the post abstract. Rendering will be deferred until after the callback is completed.

Usage:

  let markerRange = this.range;
  editor.run((postEditor) => {
    postEditor.deleteRange(markerRange);
    // editing surface not updated yet
    postEditor.schedule(() => {
      console.log('logs during rerender flush');
    });
    // logging not yet flushed
  });
  // editing surface now updated.
  // logging now flushed
Parameters:
Name Type Description
callback function

Called with an instance of PostEditor as its argument.

Source:
Returns:

The return value of callback.

Type
Mixed

selectRange(range)

Selects the given range or position. If given a collapsed range or a position, this positions the cursor at the range's position. Otherwise a selection is created in the editor surface encompassing the range.

Parameters:
Name Type Description
range Range | Position
Source:

serialize(version) → {Mobiledoc}

Parameters:
Name Type Description
version String

The mobiledoc version to serialize to.

Source:
Returns:

Serialized mobiledoc

Type
Mobiledoc

serializeTo(format) → {Object|String}

Serialize the editor's post to the requested format. Note that only mobiledoc format is lossless. If cards or atoms are present in the post, the html and text formats will omit them in output because the editor does not have access to the html and text versions of the cards/atoms.

Parameters:
Name Type Description
format string

The format to serialize ('mobiledoc', 'text', 'html')

Source:
Returns:

The editor's post, serialized to {format}

Type
Object | String

toggleMarkup(markup)

Toggles the given markup at the editor's current Range. If the range is collapsed this changes the editor's state so that the next characters typed will be affected. If there is text selected (aka a non-collapsed range), the selections' markup will be toggled. If the editor is not focused and has no active range, nothing happens.

Parameters:
Name Type Description
markup String

E.g. "b", "em", "a"

Source:
See:

toggleSection(tagName)

Toggles the tagName for the current active section(s). This will skip non-markerable sections. E.g. if the editor's range includes a "P" MarkupSection and a CardSection, only the MarkupSection will be toggled.

Parameters:
Name Type Description
tagName String

The new tagname to change to.

Source:
See:

unregisterAllTextInputHandlers()

Unregister all text input handlers

Source:

unregisterTextInputHandler(name)

Unregister text input handler by name

Parameters:
Name Type Description
name String

The name of handler to be removed

Source:

willDelete(callback)

Parameters:
Name Type Description
callback function

This callback will be called before deleting.

Source:

willHandleNewline(callback)

Parameters:
Name Type Description
callback function

This callback will be called before handling new line.

Source:

willRender(callback)

Parameters:
Name Type Description
callback function

This callback will be called before the editor is rendered.

Source: