Expand all

CodeMirrorPreferences

CodeMirrorPreferences is a panel that allows users to configure CodeMirror preferences. It is toggled by pressing Ctrl-Shift-, (or Command-Shift-, on macOS). Only the commonly used "primary" preferences with a visual effect are shown in the panel, in order to reduce in-editor clutter. A "Full preferences" link is provided to open a dialog with all available preferences. This can also be opened by pressing Alt-Shift-,.

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, [isVisualEditor]) #

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.
isVisualEditor boolean optional
 false

Whether the VE 2017 editor is being used.

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 full 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 full preferences dialog.

disabledPreferences :Set.<string> #

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

Type:

Source:

Preferences that are disabled from being changed in the panel or 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.

isVisualEditor :boolean #

Type:

  • boolean
Source:

keymap :CodeMirrorKeymap #

Type:

Source:

mode :string #

Type:

  • string
Source:

panel #

Source:

panelStateField :StateField #

Type:

Source:

preferences :Object.<string, PrefValue> #

The user's CodeMirror preferences.

Type:

Source:
The user's CodeMirror preferences.

prefsToggleEffect :StateEffectType #

Type:

Source:

primaryPreferences :Array.<string> #

Preferences that are shown in the preferences panel, as defined by $wgCodeMirrorPrimaryPreferences. These "primary" preferences should:

  • Be commonly used,
  • Be easy to understand,
  • Have an immediate visual effect, and
  • Limited to a small subset to avoid consuming too much in-editor space.

Type:

Source:

Preferences that are shown in the preferences panel, as defined by $wgCodeMirrorPrimaryPreferences.

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.

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, [view], [force]) #

Lock a preference to the given value, disabling the option in the preferences panel and 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
view EditorView 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 panel and dialog.

onKeydownPanel(event) #

Handle keydown events on the preferences panel.

Parameters:

Name Type Description
event KeyboardEvent
Source:
Handle keydown events on the preferences panel.

registerCallback(name, callback, view, [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.
view EditorView
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, view, [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
view EditorView
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, view, [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
view EditorView
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) #

Save the given user option with GlobalPreferences if it is installed, otherwise save locally. Also update the mw.user.options Map.

Parameters:

Name Type Description
optionname string
optionvalue string | number | null
Source:

Save the given user option with GlobalPreferences if it is installed, otherwise save locally.

setPreference(key, value) #

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 Description
key string
value PrefValue

A string value indicates enabled but with the given value.
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
Source:
Show the dialog with all available preferences.

toggle(view, [force]) → {boolean} #

Toggle display of the preferences panel.

Parameters:

Name Type Attributes Description
view EditorView
force boolean optional

Force the panel to open or close.

Returns:

Type
boolean
Source:
Toggle display of the preferences panel.

toggleExtension(name, view) #

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

Parameters:

Name Type Description
name string
view EditorView
Source:

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

Type Definitions

PrefValue #

Type:

  • boolean | string
Source: