Expand all

CodeMirrorPreferences

CodeMirrorPreferences is a dialog that allows users to configure CodeMirror preferences. It is opened by pressing Ctrl-Shift-, (or Command-Shift-, on macOS).

Note that this code, like MediaWiki Core, refers to the user's preferences as "options". In this class, "preferences" refer to the user's preferences for CodeMirror, which are stored as a single user 'option' in the database.

Constructor

new CodeMirrorPreferences(extensionRegistry, mode, cmKeymap, [persistPreferences]) #

Parameters:

Name Type Attributes Default Description
extensionRegistry CodeMirrorExtensionRegistry
mode string

The CodeMirror mode being used, e.g. 'mediawiki', 'javascript', etc.
cmKeymap CodeMirrorKeymap

Reference to the keymap instance.
persistPreferences boolean optional
 true

Save changes to the user's options. Pass false to keep them for the life of the editor only.

Fires:

Source:

Properties

api :mw.Api #

Type:

Source:

callbackPreferences :Map #

Preferences registered with registerCallback(). These do not have an associated Extension and instead execute a callback function when the preference is changed.

The Map object is keyed by preference name, with values being the callback function.

Type:

Source:

Preferences registered with registerCallback().

dialogConfig :Object #

Configuration for the preferences dialog.

Each key is a section name having an i18n message key of the form codemirror-prefs-section-<section>.

Values are arrays of preference names that belong to that section. Any preference not listed here will be shown in the "Other" section.

Type:

Source:
Configuration for the preferences dialog.

disabledPreferences :Set.<string> #

Preferences that are disabled from being changed in the preferences dialog when lockPreference() is called.

Type:

Source:

Preferences that are disabled from being changed in the preferences dialog when lockPreference() is called.

extension #

Source:

extensionRegistry :CodeMirrorExtensionRegistry #

Type:

Source:

formSpecification :Map.<string, FormSpecifier> #

If any feature calls for a form element that's not just a checkbox, it needs to be listed here. Key is the preference name, and the value is a form specifier.

Type:

Source:

If any feature calls for a form element that's not just a checkbox, it needs to be listed here.

keymap :CodeMirrorKeymap #

Type:

Source:

mode :string #

Type:

  • string
Source:

persistPreferences :boolean #

Type:

  • boolean
Source:

preferences :Object.<string, PrefValue> #

The user's CodeMirror preferences.

Type:

Source:
The user's CodeMirror preferences.

slowPreferences :Set.<string> #

Preferences that are considered "slow" and indicated as such in the preferences dialog.

Type:

Source:
Preferences that are considered "slow" and indicated as such in the preferences dialog.

view :EditorView #

Type:

Source:

Methods

fetchPreferences() → {Object.<string, PrefValue>} #

Fetch the user's CodeMirror preferences from the user options API, or clientside storage for unnamed users.

Returns:

Type
Object.<string, PrefValue>
Source:

Fetch the user's CodeMirror preferences from the user options API, or clientside storage for unnamed users.

firePreferencesApplyHook(prefName, [value]) #

Parameters:

Name Type Attributes Description
prefName string
value PrefValue optional

Fires:

Source:

getCheckbox() #

Source:

getDefaultPreferences() → {Object.<string, PrefValue>} #

The default CodeMirror preferences in boolean format, derived from $wgCodeMirrorDefaultPreferences or $wgCodeMirrorDefaultPreferencesCode depending on the current mode.

Returns:

Type
Object.<string, PrefValue>
Source:

The default CodeMirror preferences in boolean format, derived from $wgCodeMirrorDefaultPreferences or $wgCodeMirrorDefaultPreferencesCode depending on the current mode.

getPreference(prefName) → {PrefValue} #

Get the value of the given CodeMirror preference.

Parameters:

Name Type Description
prefName string

Returns:

Type
PrefValue
Source:
Get the value of the given CodeMirror preference.

getSelect() #

Source:

hasNonDefaultPreferences() → {boolean} #

Check if the user has any preferences that differ from the defaults. This is used to determine whether EventLogging should happen.

Returns:

Type
boolean
Source:
Check if the user has any preferences that differ from the defaults.

lockPreference(prefName, [editor], [force]) #

Lock a preference to the given value, disabling the option in the preferences dialog. The user option in the database is not changed.

This is useful for integrations that need to disable incompatible extensions.

Parameters:

Name Type Attributes Default Description
prefName string
editor Editor optional
force PrefValue optional
 false

Force the extension to be enabled or disabled (boolean), or enabled with a given value (string).
Source:

Lock a preference to the given value, disabling the option in the preferences dialog.

registerCallback(name, callback, editor, [slow]) #

Instead of an Extension, register a callback function that is executed when the preference value is changed. The callback is executed immediately if the preference is already set when registered.

Parameters:

Name Type Attributes Default Description
name string
callback function

Function that takes the new preference value.
editor Editor
slow boolean optional
 false

Setting to true will indicate that the feature is "potentially slow" in the preferences dialog.
Source:

Instead of an Extension, register a callback function that is executed when the preference value is changed.

registerExtension(name, extension, editor, [slow]) #

Register an Extension with CodeMirrorExtensionRegistry and enable it if the corresponding preference is set.

Parameters:

Name Type Attributes Default Description
name string
extension Extension
editor Editor
slow boolean optional
 false

Setting to true will indicate that the feature is "potentially slow" in the preferences dialog.
Source:

Register an Extension with CodeMirrorExtensionRegistry and enable it if the corresponding preference is set.

registerExtensionFromValueMap(name, editor, [slow]) #

Register and enable an Extension with CodeMirrorExtensionRegistry from a reconfiguration value retrieved from the preference value.

This can be used for initially registering features that use non-boolean values.

Parameters:

Name Type Attributes Default Description
name string
editor Editor
slow boolean optional
 false

Setting to true will indicate that the feature is "potentially slow" in the preferences dialog.
Source:

Register and enable an Extension with CodeMirrorExtensionRegistry from a reconfiguration value retrieved from the preference value.

saveUserOptionInternal(optionname, optionvalue) #

Update the given user option, overriding the global user option if applicable. All CodeMirror user options should also be listed in "GlobalPreferencesAutoPrefs" in extension.json so that they are auto-globals (T428887).

Parameters:

Name Type Description
optionname string
optionvalue string | number | null
Source:
Update the given user option, overriding the global user option if applicable.

setPreference(key, value, [editor]) #

Set the given CodeMirror preference and update the user option in the database, or clientside storage for unnamed users. Preferences remain "sticky" only for the mediawiki (wikitext) mode, or to all non-mediawiki modes.

The value is either a boolean (enabled or disabled), or a string. The string can be of any form, such serialized JSON. Each individual feature is responsible for decoding or normalizing the value, if necessary.

Parameters:

Name Type Attributes Description
key string
value PrefValue

A string value indicates enabled but with the given value.
editor Editor optional

Apply the preference to this editor as well as storing it. Integrations that cannot be reconfigured through the CodeMirrorExtensionRegistry should instead act on the CodeMirror~'ext.CodeMirror.preferences.apply' hook.
Source:

Set the given CodeMirror preference and update the user option in the database, or clientside storage for unnamed users.

showPreferencesDialog(view) → {boolean} #

Show the dialog with all available preferences.

Parameters:

Name Type Description
view EditorView

Returns:

Type
boolean

Fires:

Source:
Show the dialog with all available preferences.

toggleExtension(name, editor) #

Toggle an Extension on or off with CodeMirrorExtensionRegistry and update the preference.

Parameters:

Name Type Description
name string
editor Editor
Source:

Toggle an Extension on or off with CodeMirrorExtensionRegistry and update the preference.

Type Definitions

PrefValue #

Type:

  • boolean | string
Source: