Expand all

CodeMirrorChild

A CodeMirrorChild is a CodeMirror instance controlled by a 'primary' CodeMirror instance.

This will sync preference changes from the primary instance and add hook handlers to toggle the child instance when the primary instance is toggled.

Example

const cm = new CodeMirror( textarea, languageExtension );
const cmChild = new cm.child( otherTextarea, cm, languageExtension );
cm.initialize();
// Will apply to both instances.
cm.toggle();

Extends

Constructor

new CodeMirrorChild(textarea, primaryInstance, [langExtension]) #

Instantiate a child CodeMirror instance given a primary instance.

Parameters:

Name Type Attributes Description
textarea HTMLTextAreaElement

Child textarea element.
primaryInstance CodeMirror

The primary CodeMirror instance to sync with.
langExtension LanguageSupport | Extension optional

Language support and its extension(s). If not provided, the primary instance's language support will be used.
Source:

Properties

$textarea :jQuery.<(HTMLTextAreaElement|ve.ui.Surface)> #

jQuery instance of the textarea or VE surface for use with jQuery plugins.

Type:

Overrides:
Source:
jQuery instance of the textarea or VE surface for use with jQuery plugins.

activeLineExtension :Extension #

Extension for highlighting the active line.

Type:

Overrides:
Source:
Extension for highlighting the active line.

bracketMatchingConfig :Config|undefined #

The extended configuration for bracket matching. Setting this will update the bracket matching extension

Example

// Highlight matching angle brackets in addition to the default.
mw.hook( 'ext.CodeMirror.ready' ).add( ( cm ) => {
  const config = cm.bracketMatchingConfig || {};
  config.brackets = ( config.brackets || '()[]{}' ) + '<>';
  cm.bracketMatchingConfig = config;
} );

Type:

Overrides:
Source:
The extended configuration for bracket matching.

bracketMatchingExtension :Extension #

This extension adds bracket matching to the CodeMirror editor.

Type:

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

child :CodeMirrorChild #

Get a CodeMirrorChild object for use on other textareas that should have preferences synced with this CodeMirror instance.

Type:

Overrides:
Source:

Get a CodeMirrorChild object for use on other textareas that should have preferences synced with this CodeMirror instance.

closeBracketsExtension :Extension #

This extension adds automatic closing of brackets to the CodeMirror editor.

Type:

Overrides:
Source:
This extension adds automatic closing of brackets to the CodeMirror editor.

columnGuideExtension :Extensionprotected #

This extension adds a vertical column guide to the editor at column 80.

Type:

Overrides:
Source:
This extension adds a vertical column guide to the editor at column 80.

compactPanelsExtension :Extension #

Extension for the compact panel design. The class it adds makes the search and go-to line panels float over the editor instead of pushing the contents down.

Type:

Overrides:
Source:
Extension for the compact panel design.

container :HTMLDivElement #

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

Type:

Overrides:
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:

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

defaultExtensions :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:

Overrides:
Source:
See:
Default extensions used by CodeMirror.

dirCompartment :Compartment #

Compartment to control the direction of the editor.

Type:

Overrides:
Source:
Compartment to control the direction of the editor.

dirExtension :Extensionprotected #

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

Type:

Overrides:
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:

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

editRecoveryExtension #

Edit Recovery support.

Overrides:
Source:
Edit Recovery support.

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:

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

extensionRegistry :CodeMirrorExtensionRegistry #

Registry of CodeMirror Extensions.

Type:

Overrides:
Source:
Registry of CodeMirror Extensions.

extensionRegistryDefaults :Object.<Extension>protected #

The Extensions to register with the CodeMirrorExtensionRegistry at construction, keyed by preference name. Subclasses may override this to restrict or extend which preference-backed extensions are available in their integration.

NOTE: This is called by the CodeMirror constructor, so overrides must not reference instance properties that are only set after super() has been called.

Type:

Overrides:
Source:

The Extensions to register with the CodeMirrorExtensionRegistry at construction, keyed by preference name.

gotoLine :CodeMirrorGotoLine #

The go-to line panel.

Type:

Overrides:
Source:
The go-to line panel.

hasFocus :boolean #

Whether the editor has focus.

Type:

  • boolean
Overrides:
Source:
Whether the editor has focus.

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:

Overrides:
Source:

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

indentGuidesExtension :Extension #

This extension adds indent guides to the CodeMirror editor.

Type:

Overrides:
Source:
This extension adds indent guides to the CodeMirror editor.

initialReadOnly :booleanprotected #

The read-only state to use before there is a view, which is what readOnlyExtension seeds the state with. Integrations bound to something other than a textarea should override this.

Type:

  • boolean
Overrides:
Source:

The read-only state to use before there is a view, which is what readOnlyExtension seeds the state with.

isActive :boolean #

Whether the CodeMirror instance is active.

Type:

  • boolean
Overrides:
Source:
Whether the CodeMirror instance is active.

keymap :CodeMirrorKeymap #

CodeMirror key mappings and help dialog.

Type:

Overrides:
Source:
CodeMirror key mappings and help dialog.

langExtension :LanguageSupport #

Language support and its extension(s).

Type:

Overrides:
Source:
Language support and its extension(s).

lineNumberingExtension :Extension #

Extension for line numbering.

Type:

Overrides:
Source:
Extension for line numbering.

lineWrappingExtension :Extension #

Extension for line wrapping.

Type:

Overrides:
Source:
Extension for line wrapping.

lintApi :LintSource|undefined #

The function to lint the code in the editor using a MediaWiki API. It can be disabled by setting this.lintApi.disabled = true.

Example

mw.hook( 'ext.CodeMirror.ready' ).add( ( cm ) => {
  if ( cm.lintApi ) {
    cm.lintApi.disabled = true;
  }
} );

Type:

Overrides:
Source:
The function to lint the code in the editor using a MediaWiki API.

lintExtension :Extensionprotected #

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

Type:

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

lintSource :LintSource|undefined #

The function to lint the code in the editor using a web worker. It can be disabled by setting this.lintSource.disabled = true.

Example

mw.hook( 'ext.CodeMirror.ready' ).add( ( cm ) => {
  if ( cm.lintSource ) {
    cm.lintSource.disabled = true;
  }
} );

Type:

Overrides:
Source:
The function to lint the code in the editor using a web worker.

mode :string #

The CodeMirror "mode" (language).

Type:

  • string
Overrides:
Source:
The CodeMirror "mode" (language).

persistPreferences :booleanprotected #

Whether to save preference changes to the user's options. Subclasses that are not the user's main editor should override this and return false, so that the editor does not change preferences the user set elsewhere. Preferences are still read, and still apply for the life of the editor.

Note this is distinct from locked preferences, which force a specific PrefValue for the life of the editor.

Type:

  • boolean
Overrides:
Source:
Whether to save preference changes to the user's options.

phrasesExtension :Extensionprotected #

Overrides for the CodeMirror library's internalization system.

Type:

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

preferences :CodeMirrorPreferences #

The CodeMirror preferences dialog.

Type:

Overrides:
Source:
The CodeMirror preferences dialog.

primaryInstance :CodeMirror #

The primary CodeMirror instance.

Type:

Source:
The primary CodeMirror instance.

readOnly :boolean #

Whether the editor is read-only. Assigning to this reconfigures the editor in place, so it can be changed at any time after initialization. Before then it comes from initialReadOnly.

A read-only editor is still focusable and its contents still selectable. Use EditorView.editable to make it non-editable.

Type:

  • boolean
Overrides:
Source:
Whether the editor is read-only.

readOnlyExtension :Extensionprotected #

The read-only state of the editor, in a Compartment so that readOnly can reconfigure it after initialization.

Type:

Overrides:
Source:

The read-only state of the editor, in a Compartment so that readOnly can reconfigure it after initialization.

The CodeMirror search panel.

searchExtension :Extension #

Extension for search and goto line functionality.

Type:

Overrides:
Source:
Extension for search and goto line functionality.

sortLines :CodeMirrorSortLines #

CodeMirror line sorting functionality.

Type:

Overrides:
Source:
CodeMirror line sorting 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:

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

state :EditorState|undefined #

The current EditorState of the CodeMirror editor. This is given by the EditorView instance, which is only available after initialization.

Type:

Overrides:
Source:
The current EditorState of the CodeMirror editor.

supportedExtensions :Array.<string>|nullprotected #

Names that CodeMirrorExtensionRegistry#register will accept, or null to accept any name. Subclasses that can only support some extensions should override this, so that extensions registered later — by a gadget, or by applyLinter() — are refused as well.

NOTE: This is called by the CodeMirror constructor, so overrides must not reference instance properties that are only set after super() has been called.

Type:

Overrides:
Source:

Names that CodeMirrorExtensionRegistry#register will accept, or null to accept any name.

textSelection :CodeMirrorTextSelection #

jQuery.textSelection overrides for CodeMirror.

Type:

Overrides:
Source:
jQuery.textSelection overrides for CodeMirror.

textarea :HTMLTextAreaElement|ve.ui.Surface #

The textarea or VE surface that CodeMirror is bound to.

Type:

Overrides:
Source:
The textarea or VE surface that CodeMirror is bound to.

themes :CodeMirrorThemes #

The CodeMirror themes manager.

Type:

Overrides:
Source:
The CodeMirror themes manager.

trailingWhitespaceExtension #

This extension highlights trailing whitespace characters.

Overrides:
Source:
This extension highlights trailing whitespace characters.

updateExtension :Extension #

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

Type:

Overrides:
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:

Overrides:
Source:
The editor user interface.

whitespaceExtension #

This extension highlights whitespace characters.

Overrides:
Source:
This extension highlights whitespace characters.

wrappedElement :HTMLElementprotected #

The element that container is wrapped around, and which the container hides. Integrations bound to something other than a textarea should override this, so that the view is added beside the right element.

Type:

Overrides:
Source:

The element that container is wrapped around, and which the container hides.

Methods

activate()protected #

Activate CodeMirror on the textarea. This shows the editor view, hiding the original textarea.

initialize is expected to be called before this method.

Overrides:
Source:
Activate CodeMirror on the textarea.

addEditRecoveryHandler()protected #

Set a new edit recovery handler.

Overrides:
Source:
Set a new edit recovery handler.

addFormSubmitHandler()protected #

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

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

addHashChangeHandler()protected #

Scroll the CodeMirror editor on hashchange.

Overrides:
Source:
Scroll the CodeMirror editor on hashchange.

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
Overrides:
Source:
Add a handler for the given Hook.

addTextAreaJQueryHook()protected #

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

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

addToDOM(extensions)protected #

Add the CodeMirror EditorView to the DOM, wrapping wrappedElement in the container element.

Parameters:

Name Type Description
extensions Extension
Overrides:
Source:

Add the CodeMirror EditorView to the DOM, wrapping wrappedElement in the container element.

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

const require = await mw.loader.using( 'ext.CodeMirror' );
mw.hook( 'ext.CodeMirror.ready' ).add( ( cm ) => {
  const { EditorView, Prec } = require( 'ext.CodeMirror.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
Overrides:
Source:
See:
Apply an Extension to the CodeMirror editor.

applyLinter(lint, [config]) #

Apply an extra linter to the CodeMirror editor. This linter respects the user preference for enabling or disabling linting.

Example

// Report Ukrainian letter 'і' among Latin letters as a warning.
const lint = {
  pattern: /[a-zA-Z]і|і(?=[a-zA-Z])/g,
  callback( match ) {
    return {
      from: match.index + match[ 0 ].indexOf( 'і' ),
      to: match.index + match[ 0 ].indexOf( 'і' ) + 1,
      severity: 'warning',
      message: 'Ukrainian letter "і" found among Latin letters.',
      actions: [ {
        name: 'To Latin',
        apply( view, from, to ) {
          view.dispatch( {
            changes: { from, to, insert: 'i' }
          } );
        }
      } ]
    };
  }
};
mw.hook( 'ext.CodeMirror.ready' ).add( ( cm ) => {
  cm.applyLinter( lint );
} );

Parameters:

Name Type Attributes Description
lint function | Object

Function that takes a string and returns an array of Diagnostic, or an object with a pattern RegExp and callback function that takes a RegExp match and returns Diagnostic or an array of Diagnostic.
config Object optional

Optional configuration.
Overrides:
Source:
Apply an extra linter 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.

Overrides:
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.

Fires:

Overrides:
Source:
Destroy the CodeMirror instance and revert to the original textarea.

dispatch(spec) #

Apply a transaction to the editor. Together with state, this is what makes a CodeMirror instance an Editor.

Parameters:

Name Type Description
spec Object
Overrides:
Source:

Apply a transaction to the editor.

focus([isActive]) #

Focus the CodeMirror editor.

Parameters:

Name Type Attributes Description
isActive boolean optional

Whether the CodeMirror editor is active.
Overrides:
Source:
Focus the CodeMirror editor.

getLineNumberingExtension([firstLineNumber]) → {Extension} #

Line numbering, starting at the given number.

Use this instead of CodeMirror#lineNumberingExtension when the code in the editor is part of a larger file, and the first line is not line 1.

Parameters:

Name Type Attributes Default Description
firstLineNumber number optional
 1

Number to show for the first line.

Returns:

Type
Extension
Overrides:
Source:
Line numbering, starting at the given number.

getNewEditorState(extensions) → {EditorState}protected #

Create a new EditorState with the given extensions and the contents of the element that CodeMirror is bound to.

Parameters:

Name Type Description
extensions Extension

Returns:

Type
EditorState
Overrides:
Source:

Create a new EditorState with the given extensions and the contents of the element that CodeMirror is bound to.

getSourceContents() → {string}protected #

Get the contents of the element that CodeMirror is bound to. This is used to populate the initial document, and to re-sync the contents when re-activating.

Returns:

Type
string
Overrides:
Source:
Get the contents of the element that CodeMirror is bound to.

hideEditor()protected #

Hide the editor and give jQuery.textSelection back to the textarea, as deactivate() does on the way out. Integrations that render no editor of their own should override this.

Overrides:
Source:

Hide the editor and give jQuery.textSelection back to the textarea, as deactivate() does on the way out.

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 optional
 this.defaultExtensions

Extensions to use.

Fires:

Overrides:
Source:
Setup CodeMirror and add it to the DOM.

logEditFeature(action)protected #

Log usage of CodeMirror.

Parameters:

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

removeFromDOM()protected #

Remove the CodeMirror EditorView from the DOM, unwrapping the element it was attached to, as the inverse of addToDOM(). Integrations that attach CodeMirror to something other than a textarea should override this.

Overrides:
Source:

Remove the CodeMirror EditorView from the DOM, unwrapping the element it was attached to, as the inverse of addToDOM().

removeMwHooks([hook], [fn])protected #

Remove handlers registered with #addMwHook for the given Hook, or remove all handlers if no hook is specified.

Parameters:

Name Type Attributes Description
hook string optional
fn function optional

If specified, only this handler will be removed for the given hook.
Overrides:
Source:

Remove handlers registered with #addMwHook for the given Hook, or remove all handlers if no hook is specified.

restoreSelectionAndScrollPosition(selectionStart, selectionEnd, scrollTop, hadFocus)protected #

Hand the hidden textarea's state over to the editor: disable IME on the textarea so it can't conflict with CodeMirror, then restore the selection, scroll position and focus state that were captured before the textarea was hidden.

This is the activate counterpart to syncSelectionAndScrollPosition(). Integrations that aren't bound to a textarea should override it as a no-op.

Parameters:

Name Type Description
selectionStart number
selectionEnd number
scrollTop number
hadFocus boolean
Overrides:
Source:

Hand the hidden textarea's state over to the editor: disable IME on the textarea so it can't conflict with CodeMirror, then restore the selection, scroll position and focus state that were captured before the textarea was hidden.

setCodeMirrorPreference(prefValue) #

Save CodeMirror enabled preference.

Parameters:

Name Type Description
prefValue boolean

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

setupFeatureLogging()protected #

Add hook handlers to log usage of CodeMirror features.

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

showEditor()protected #

Reveal the editor and route jQuery.textSelection through it, as activate() does on the way in. Integrations that render no editor of their own should override this.

Overrides:
Source:

Reveal the editor and route jQuery.textSelection through it, as activate() does on the way in.

syncEditorContentsToSource()protected #

Sync the CodeMirror editor contents to the original textarea.

Overrides:
Source:
Sync the CodeMirror editor contents to the original textarea.

syncSelectionAndScrollPosition(from, to, scrollTop)protected #

Sync the selection and scroll position to the original textarea.

Parameters:

Name Type Description
from number
to number
scrollTop number
Overrides:
Source:
Sync the selection and scroll position to the original textarea.

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.

Fires:

Overrides:
Source:
Toggle CodeMirror on or off from the textarea.