Upgrading to v5.0.0

Version 5.0.0 of MediumEditor introduces a significantly simpler system for building custom extensions as well as extending existing buttons and extensions. As part of moving towards this extendable model, there were significant changes to the way options are passed to MediumEditor, as well as the extensions and buttons themselves.

In addition to extension related changes, there were several other potential breaking changes related to API methods, as well as utility helper methods.

MediumEditor Options

For details on all the currently supported MediumEditor options, refer to the Medium Editor Options Wiki Page.

Toolbar Options

• Options controlling the toolbar are now passed as a 'toolbar' object inside the outer options object.
  • buttons -> toolbar.buttons
  • toolbarAlign -> toolbar.align
  • diffTop -> toolbar.diffTop
  • diffLeft -> toolbar.diffLeft
  • staticToolbar -> toolbar.static
  • stickyToolbar -> toolbar.sticky
  • firstButtonClass -> toolbar.firstButtonClass
  • lastButtonClass -> toolbar.lastButtonClass
  • updateOnEmptySelection -> toolbar.updateOnEmptySelection
  • standardizeSelectionStart -> toolbar.standardizeSelectionStart

Anchor Options

• Options controlling the anchor input extension are now passed as a 'anchor' object inside the outer options object.
  • anchorInputPlaceholder -> anchor.placeholderText
  • checkLinkFormat -> anchor.linkValidation
  • anchorButton & anchorButtonClass -> anchor.customClassOption
  • anchorTarget -> anchor.targetCheckbox
  • anchorInputCheckboxLabel -> anchor.targetCheckboxText

Anchor Preview Options

• Options controlling the anchor preview extension are now passed as a 'anchorPreview' object inside the outer options object.
  • anchorPreviewHideDelay -> anchorPreview.hideDelay

Paste Options

• Options controlling paste are now passed as a 'paste' object inside the outer options object.
  • forcePlainText -> paste.forcePlainText
  • cleanPastedHTML -> paste.cleanPastedHTML

Placeholder Options

• Options controlling the placeholder extension are now passed as a 'placeholder' object inside the outer options object.
  • placeholder -> placeholder.text

Other Options

disableToolbar

• Disabling the toolbar extension is now done by setting the toolbar option to false

disableAnchorPreview

• Disabling the anchor preview extension is now done by setting the anchorPreview option to false

disablePlaceholders

• Disabling the placeholder extension is now done by setting the placeholder option to false

onShowToolbar & onHideToolbar

• The onShowToolbar and onHideToolbar options are no longer supported. Instead, attach to the 'showToolbar' and 'hideToolbar' custom events via MediumEditor.subscribe()

firstHeader & secondHeader

• The firstHeader & secondHeader options have been removed. Instead, any number of the 6 header types can be passed as button names into the toolbar.buttons option array.
  • Example: Where before the code may have sent firstHeader: 'h2' and secondHeader: 'h3', it should now pass ['bold', 'italic', 'quote', 'h2', 'h3'] via the toolbar.buttons property of the MediumEditor options object.

buttonLabels

• The buttonLabels option no longer supports taking an object in that specifies custom labels for all buttons. Instead, pass an object into the toolbar.buttons option array that contains a .name property for the name of the button, a either a contentDefault or a contentFA property that should be in the innerHTML of the button (for default of fontawesome buttonLabels respectively)

MediumEditor Extensions

.parent

• Extension.parent is no longer supported. All extensions will have a reference to the MediumEditor instance via their .base property, unless the property already exists.

.init()

• Extension.init() will no longer be passed any arguments. Previously, .init(instance) received an instance of MediumEditor as an argument, but this is not needed now that .base will be populated before .init() is called.

.deactivate()

• Extension.deactivate() will no longer be called by MediumEditor. .destroy() will be called instead when MediumEditor is destroyed.

.options

• The .options property of any built-in extensions or buttons has been removed. All of the properties should be retrieved and set from the prototype of the object itself.
  • Example: Instead of buttons using this.options.action, they should now use this.action.
  • Not all extensions had options before, or saved them via the .options property.

MediumEditor API

.id

• The unique identifier used for MediumEditor elements will now remain unique and remain regardless of how many instances are created. After calling .destroy() and .setup(), the id will remain the same. This id was used to generate unique element ids for things like the id attribute of the toolbar element ('medium-editor-toolbar-[ID]')

.toolbar

• The MediumEditor toolbar is now an extension, so MediumEditor.toolbar is no longer a valid reference. Use MediumEditor.getExtensionByName('toolbar') instead.

.statics

• All of the .statics references have been removed as the new style of extensions and buttons has been introduced. The objects exposed via .statics have also been changed, so code which uses them may require additonal changes.
  • MediumEditor.statics.ButtonsData -> MediumEditor.extensions.button.prototype.defaults (ideally this reference should no longer be needed)
  • MediumEditor.statics.DefaultButton -> MediumEditor.extensions.button
  • MediumEditor.statics.AnchorExtension -> MediumEditor.extensions.anchor
  • MediumEditor.statics.FontSizeExtension -> MediumEditor.extensions.fontSize
  • MediumEditor.statics.Toolbar -> MediumEditor.extensions.toolbar
  • MediumEditor.statics.AnchorPreview -> MediumEditor.extensions.anchorPreview

.activate()

• MediumEditor.activate() has been replaced with MediumEditor.setup()

.deactivate()

• MediumEditor.deactivate() has been replaced with MediumEditor.destroy()

.createEvent()

• MediumEditor.createEvent() is no longer needed in order to fire custom events. It has been removed.

.hideToolbarDefaultActions()

• MediumEditor.hideToolbarDefaultActions() has been removed. Use the hideToolbarDefaultActions() method of the toolbar extension instead.

.setToolbarPosition()

• MediumEditor.setToolbarPosition() has been removed. Use the setToolbarPosition() method of the toolbar extension instead.

.callExtensions()

• MediumEditor.callExtensions() has been removed and is no longer supported.

MediumEditor Utility Methods

MediumEditor.util

• MediumEditor.util.getSelectionRange() has been moved to MediumEditor.selection.getSelectionRange()
• MediumEditor.util.getSelectionStart() has been moved to MediumEditor.selection.getSelectionStart()
• MediumEditor.util.unwrapElement() has been removed. Use MediumEditor.util.unwrap() instead
• MediumEditor.util.getSelectionData() has been removed
• MediumEditor.util.setObject() has been removed
• MediumEditor.util.getObject() has been removed
• MediumEditor.util.derives() has been removed. Objects that can be drived from (like extensions and buttons) will have a .extend() method for extending.
• MediumEditor.util.now() has been removed. Use Date.now() instead.
• MediumEditor.util.parentElements has been renamed MediumEditor.util.blockContainerElementNames

MediumEditor.selection

• MediumEditor.selection.getSelectionData() has been removed

MediumEditor CSS & Markup

• The .clearfix class has been removed, and .clearfix class is no longer added to the toolbar element.
• All references to 'medium' in CSS classes has been replaced with 'medium-editor'
  • Example: The image element added by the image dragging extension will now have a medium-editor-image-loading class on instead of medium-image-loading
• The data-medium-element attribute on all MediumEditor elements has been renamed to data-medium-editor-element
• Toolbar classes sticky-toolbar and static-toolbar have been renamed medium-editor-sticky-toolbar and medium-editor-static-toolbar respectively

Other Changes

• The getFocusedElement() method of the toolbar extension has been removed. Use MediumEditor.getFocusedElement() instead.
• Keyboard Shortcuts are now controlled via the Keyboard Commands extension. The .key option on buttons is not longer supported for mapping keyboard shortcuts.