Expand all

CodeMirror

Interface for the CodeMirror editor.

This class is a wrapper around the CodeMirror library, providing a simplified interface for creating and managing CodeMirror instances in MediaWiki.

Lifecycle

Example

// Creating a new CodeMirror instance.
mw.loader.using( [
  'ext.CodeMirror.v6',
  'ext.CodeMirror.v6.mode.mediawiki'
] ).then( ( require ) => {
  const CodeMirror = require( 'ext.CodeMirror.v6' );
  const mediawikiLang = require( 'ext.CodeMirror.v6.mode.mediawiki' );
  const cm = new CodeMirror( myTextarea, mediawikiLang() );
  cm.initialize();
} );

// Integrating with an existing CodeMirror instance.
mw.hook( 'ext.CodeMirror.ready', ( cm ) => {
  cm.applyExtension( myExtension );
} );

Constructor

new CodeMirror(textarea, [langExtension]) #

Instantiate a new CodeMirror instance.

Parameters:

Name Type Attributes Description
textarea HTMLTextAreaElement | jQuery | string

Textarea to add syntax highlighting to.
langExtension LanguageSupport | Extension optional

Language support and its extension(s).
Source:

Properties

$textarea :jQuery #

jQuery instance of the textarea for use with WikiEditor and jQuery plugins.

Type:

Source:
jQuery instance of the textarea for use with WikiEditor and jQuery plugins.

activeLineExtension :Extension #

Extension for highlighting the active line.

Type:

Source:
Extension for highlighting the active line.

bracketMatchingExtension :Extension #

This extension adds bracket matching to the CodeMirror editor.

Type:

Source:
This extension adds bracket matching to the CodeMirror editor.

container :HTMLDivElement #

The .ext-codemirror-wrapper container. This houses both the original textarea and the CodeMirror editor.

Type:

Source:
The .ext-codemirror-wrapper container.

contentAttributesExtension :Extensionprotected #

This specifies which attributes get added to the CodeMirror contenteditable .cm-content. Subclasses are safe to override this method, but attributes here are considered vital.

Type:

Source:
See:
This specifies which attributes get added to the CodeMirror contenteditable .cm-content.

contentModel :string #

The content model of the page.

Type:

  • string
Source:
The content model of the page.

defaultExtensions :Extension|Array.<Extension> #

Default extensions used by CodeMirror. Extensions here should be applicable to all theoretical uses of CodeMirror in MediaWiki. This getter can be overridden to apply additional extensions before initialization. To apply a new extension after initialization, use applyExtension(), or through CodeMirrorExtensionRegistry using register() if it needs to be reconfigured (such as toggling on and off).

Type:

Source:
See:
Default extensions used by CodeMirror.

dirCompartment :Compartment #

Compartment to control the direction of the editor.

Type:

Source:
Compartment to control the direction of the editor.

dirExtension :Extensionprotected #

This extension adds the ability to change the direction of the editor.

Type:

Source:
This extension adds the ability to change the direction of the editor.

domEventHandlersExtension :Extensionprotected #

Extension to bubble some DOM events to the original textarea.

The CodeMirror events are natively fired on the EditorView's .cm-content element, which is accessible through view.contentDOM. The scroll event is fired on the .cm-scroller element, which is accessible through view.scrollDOM.

Type:

Source:
Extension to bubble some DOM events to the original textarea.

editorAttributesExtension :Extensionprotected #

This specifies which attributes get added to the .cm-editor element (the entire editor). Subclasses are safe to override this method, but attributes here are considered vital.

Type:

Source:
See:
This specifies which attributes get added to the .cm-editor element (the entire editor).

extensionRegistry :CodeMirrorExtensionRegistry #

Registry of CodeMirror Extensions.

Type:

Source:
Registry of CodeMirror Extensions.

gotoLine :CodeMirrorGotoLine #

The go-to line panel.

Type:

Source:
The go-to line panel.

heightExtension :Extension #

This extension sets the height of the CodeMirror editor to match the textarea. This getter can be overridden to change the height of the editor, but it's usually simpler to set the height of the textarea using CSS prior to initialization.

Type:

Source:

This extension sets the height of the CodeMirror editor to match the textarea.

isActive :boolean #

Whether the CodeMirror instance is active.

Type:

  • boolean
Source:
Whether the CodeMirror instance is active.

keymap :CodeMirrorKeymap #

CodeMirror key mappings and help dialog.

Type:

Source:
CodeMirror key mappings and help dialog.

langExtension :LanguageSupport|Extension #

Language support and its extension(s).

Type:

Source:
Language support and its extension(s).

lineNumberingExtension :Extension #

Extension for line numbering.

Type:

Source:
Extension for line numbering.

lineWrappingExtension :Extension #

Extension for line wrapping.

Type:

Source:
Extension for line wrapping.

lintExtension :Extensionprotected #

This extension adds the ability to lint the code in the editor.

Type:

Source:
This extension adds the ability to lint the code in the editor.

lintSource :function|null #

The function to lint the code in the editor.

Type:

  • function | null
Source:
The function to lint the code in the editor.

phrasesExtension :Extensionprotected #

Overrides for the CodeMirror library's internalization system.

Type:

Source:
See:
Overrides for the CodeMirror library's internalization system.

preferences :CodeMirrorPreferences #

The CodeMirror preferences panel.

Type:

Source:
The CodeMirror preferences panel.

readOnly :boolean #

Whether the textarea is read-only.

Type:

  • boolean
Source:
Whether the textarea is read-only.
The CodeMirror search panel.

searchExtension :Extension #

Extension for search and goto line functionality.

Type:

Source:
Extension for search and goto line functionality.

specialCharsExtension :Extensionprotected #

We give a small subset of special characters a tooltip explaining what they are. The messages and for what characters are defined here. Any character that does not have a message will instead use CM6 defaults, which is the localization of 'codemirror-control-character' followed by the Unicode number.

Type:

Source:
See:
We give a small subset of special characters a tooltip explaining what they are.

textSelection :CodeMirrorTextSelection #

jQuery.textSelection overrides for CodeMirror.

Type:

Source:
jQuery.textSelection overrides for CodeMirror.

textarea :HTMLTextAreaElement #

The textarea that CodeMirror is bound to.

Type:

Source:
The textarea that CodeMirror is bound to.

updateExtension :Extension #

This extension listens for changes in the CodeMirror editor and fires the ext.CodeMirror.input hook with the ViewUpdate object.

Type:

Source:

Fires:

This extension listens for changes in the CodeMirror editor and fires the ext.CodeMirror.input hook with the ViewUpdate object.

view :EditorView #

The editor user interface.

Type:

Source:
The editor user interface.

whitespaceExtension #

This extension highlights whitespace characters.

Source:
This extension highlights whitespace characters.

Methods

activate()protected #

Activate CodeMirror on the textarea. This sets the state property and shows the editor view, hiding the original textarea.

initialize is expected to be called before this method.

Source:
Activate CodeMirror on the textarea.

addDarkModeMutationObserver() #

Use a MutationObserver to watch for CSS class changes to the element, and update the CodeMirror editor's theme accordingly. This is ony necessary for non-wikitext, where we don't use our own CSS classes during tokenization.

Source:

Use a MutationObserver to watch for CSS class changes to the element, and update the CodeMirror editor's theme accordingly.

addEditRecoveredHandler()protected #

Set a new edit recovery handler.

Source:
Set a new edit recovery handler.

addFormSubmitHandler()protected #

Sync the CodeMirror editor with the original textarea on form submission.

Source:
Sync the CodeMirror editor with the original textarea on form submission.

addMwHook(hook, fn)protected #

Add a handler for the given Hook. This method is used to ensure no hook handlers are duplicated across lifecycle methods, All handlers will be removed during deactivation.

Parameters:

Name Type Description
hook string
fn function
Source:
Add a handler for the given Hook.

addTextAreaJQueryHook()protected #

Define jQuery hook for .val() on the textarea.

Source:
See:
Define jQuery hook for .val() on the textarea.

applyExtension(extension) #

Apply an Extension to the CodeMirror editor. This is accomplished through top-level reconfiguration of the EditorView.

If the extension needs to be reconfigured (such as toggling on and off), use the extensionRegistry instead.

Example

mw.loader.using( 'ext.CodeMirror.v6' ).then( ( require ) => {
  mw.hook( 'ext.CodeMirror.ready' ).add( ( cm ) => {
    const { EditorView, Prec } = require( 'ext.CodeMirror.v6.lib' );
    // Disable spellchecking. Use Prec.high() to override the
    // contentAttributesExtension which adds spellcheck="true".
    cm.applyExtension( Prec.high( EditorView.contentAttributes.of( {
      spellcheck: 'false'
    } ) ) );
  } );
} );

Parameters:

Name Type Description
extension Extension
Source:
See:
Apply an Extension to the CodeMirror editor.

deactivate()protected #

Deactivate CodeMirror on the textarea, restoring the original textarea and hiding the editor. This life-cycle method should retain the view but discard the state.

Source:

Deactivate CodeMirror on the textarea, restoring the original textarea and hiding the editor.

destroy() #

Destroy the CodeMirror instance and revert to the original textarea. This action should be considered irreversible.

Source:

Fires:

Destroy the CodeMirror instance and revert to the original textarea.

initialize([extensions]) #

Setup CodeMirror and add it to the DOM. This will hide the original textarea.

This method should only be called once per instance. Use toggle, activate, and deactivate to enable or disable the same CodeMirror instance programmatically, and restore or hide the original textarea.

Parameters:

Name Type Attributes Default Description
extensions Extension | Array.<Extension> optional
 this.defaultExtensions

Extensions to use.
Source:

Fires:

Setup CodeMirror and add it to the DOM.

logEditFeature(action)protected #

Log usage of CodeMirror.

Parameters:

Name Type Description
action string
Source:
See:
Log usage of CodeMirror.

setupFeatureLogging()protected #

Add hook handlers to log usage of CodeMirror features.

Source:
Add hook handlers to log usage of CodeMirror features.

toggle([force]) #

Toggle CodeMirror on or off from the textarea. This will call initialize if CodeMirror is being enabled for the first time.

Parameters:

Name Type Attributes Description
force boolean optional

true to enable CodeMirror, false to disable. Note that the ext.CodeMirror.toggle hook will not be fired if this parameter is set.
Source:

Fires:

Toggle CodeMirror on or off from the textarea.

setCodeMirrorPreference(prefValue)static #

Save CodeMirror enabled preference.

Parameters:

Name Type Description
prefValue boolean

true to enable CodeMirror where possible on page load.
Source:
Save CodeMirror enabled preference.

Events

'ext.CodeMirror.destroy'(textarea) #

Called just after CodeMirror is destroyed and the original textarea is restored.

Parameters:

Name Type Description
textarea HTMLTextAreaElement

The original textarea.
Source:
Called just after CodeMirror is destroyed and the original textarea is restored.

'ext.CodeMirror.initialize'(textarea) #

Called just before CodeMirror is initialized. This can be used to manipulate the DOM to suit CodeMirror (i.e. if you manipulate WikiEditor's DOM, you may need this).

Parameters:

Name Type Description
textarea HTMLTextAreaElement | ve.ui.Surface

The textarea or VisualEditor surface that CodeMirror is bound to.
Source:
Called just before CodeMirror is initialized.

'ext.CodeMirror.input'(update) #

Called when document changes are made in CodeMirror. The original textarea is not necessarily updated yet.

Parameters:

Name Type Description
update ViewUpdate
Source:
Called when document changes are made in CodeMirror.

'ext.CodeMirror.preferences.apply'(prefName, prefValue) #

Fired when a CodeMirror preference is changed or initially applied in a session. The preference may not have been saved to the database yet.

Parameters:

Name Type Description
prefName string
prefValue boolean
Source:
Fired when a CodeMirror preference is changed or initially applied in a session.

'ext.CodeMirror.preferences.ready'(preferences) #

Fired just before CodeMirrorPreferences has been instantiated.

Parameters:

Name Type Description
preferences CodeMirrorPreferences
Source:
Fired just before CodeMirrorPreferences has been instantiated.

'ext.CodeMirror.ready'(cm) #

Called just after CodeMirror is initialized.

Parameters:

Name Type Description
cm CodeMirror

The CodeMirror instance.
Source:
Called just after CodeMirror is initialized.

'ext.CodeMirror.toggle'(enabled, cm, textarea) #

Called when CodeMirror is toggled on or off.

Parameters:

Name Type Description
enabled boolean

true if CodeMirror is now enabled, false if disabled.
cm CodeMirror

The CodeMirror instance.
textarea HTMLTextAreaElement

The original textarea.
Source:
Called when CodeMirror is toggled on or off.