Live Replace

What it does

Enables real-time replacement of text or specific patterns as you type, offering immediate updates and seamless editing.

Installation

First you have to switch into your project location using the command line.

cd path/to/your/project

Now you should be in the same directory as the package.json file. Then you can install the plugin as follows:

npm install @xeditor/plugin-live-replace --save --registry https://npm.xeditor.com

Configuration

The structure of the default plugin configuration looks like this

Note that every property with undefined as a possible value is optional.

{
	pluginId: 'replacer',
	ptype: 'uxxeditorlivereplace',
	// True to add the default replacement configurations, false to ignore them (defaults to true)
	// Can also be an array that contains the IDs of the replacement items to add
	// The default replacements are a minimal set of replacement configurations that provide some basic text replace features
	addDefaultReplacements: boolean | string[] | undefined,
	// True to replace found matches on paste, false to allow the paste of unreplaced matches (defaults to true)
	replaceOnPaste: boolean | undefined,
	// True to replace all matches on save (defaults to false)
	replaceOnSave: boolean | undefined,
	// Enables or disables live replacement (configured by `config`) (defaults to true)
	enableLiveReplace: boolean | undefined,
	// Enables or disables text correction (configured by `spelling`) (defaults to true)
	enableTextCorrection: boolean | undefined,
	// Enables or disables the context menu (defaults to true)
	enableContextMenu: boolean | undefined,
	// True to force a complete undo of a replacement, false to add a seperate history entry for the replacement (defaults to false)
	forceCompleteUndo: boolean | undefined,
	// The default locale used for spelling if none is present in the request URL (defaults to 'en')
	defaultLocale: 'de' | 'en' | string | undefined,
	// Spelling configuration used for text correction (defaults to [])
	spelling: string[] | undefined | {
		de: string[],
		en: string[]
	},
	// Replacement configuration that contains all replacement items that should be used (defaults to [])
	config: object[] | undefined
}

Default replacements

ID	Description
3dot	Replaces three dots (...) with a single character (…)
common	Replaces some common characters e.g. (c) = ©
util	Replaces (user|doc|time|date) with the corresponding information
upper	Replaces the first letter after a (.?!) with the uppercase version of it
unicode	Replaces a unicode code with the respective character e.g. \u2026 = …
dash	Replaces '--' or ' - ' with '–'
quote	Replaces normal quotes with upper or lower typographic quotes

The structure of a replacement configuration item looks like this

{
	// String, regular expression or function to match some text within the document.
	match: string | RegExp | () => {
		index: number,
		text: string,
		regexMatch: [] // Result of a RegExp.match
	},
	// String or function used to replace the matched text
	replace: string | (editor, plugin, $, node, nodeText, matchedText, index) => string | string[] | Ext.ux.xeditor.Element | Ext.ux.xeditor.Element[] | Ext.ux.xeditor.NodeList,
	// Priority of this replacement item (the highest priority will be used if multiple items match on the same text) (defaults to 0)
	priority: number | undefined,
	// True to prevent this item from matching in range replacements (defaults to false)
	stop: boolean | undefined,
	// True to force spaces before and after the given match (defaults to false)
	asWord: boolean | undefined,
	// Indicates how the plugin should treat the input cache after a successful replacement (defaults to 'update')
	cacheMode: 'clear' | 'update' | 'keep' | undefined,
	// Config that tells the editor which character sequences trigger this replacement (defaults to null)
	// If configured patterns do not need to be fully typed and already existing text can also be used for live text replacement
	trigger: string | string[] | undefined | {
		// One or more texts that trigger this replacement
		text: string | string[],
		// The maximum distance from the pattern to the cursor location
		distance: number | undefined
	},
	// Used to match the context around the match, if set, the configured before and after groups will NOT be replaced.
	// The properties before, after and main set the 1 based index of the corresponding capture group within the match regex.
	// The properties beforeSize and afterSize indicate the maximum size of the groups.
	strip: boolean | undefined | {
		// Before group index (defaults to 1)
		before: number | undefined,
		// After group index (defaults to 3)
		after: number | undefined,
		// Main group index (defaults to 2)
		main: number | undefined,
		// Max before group size (defaults to 1)
		beforeSize: number | undefined,
		// Max after group size (defaults to 1)
		afterSize: number | undefined
	}
}

A simple example of how a basic plugin configuration looks like

{
	pluginId: 'replacer',
	ptype: 'uxxeditorcommontextreplace',
	addDefaultReplacements: true,
	replaceOnPaste: true,
	replaceOnSave: false,
	enableLiveReplace: true,
	enableTextCorrection: true,
	enableContextMenu: true,
	forceCompleteUndo: false,
	defaultLocale: 'en',
	// Note that text correction works better the more words are configured
	spelling: [
		'administration',
		'international',
		'something',
		'car',
		'television'
	],
	// The config array contains the replacement configuration items described above
	config: [{
		match: /\.{3}/,
		replace: '\u2026',
		priority: 10,
		stop: true
	}, {
		match: '(c)',
		replace: '\u00a9'
	}, {
		match: /=(.+)(\s)/,
		replace: function(editor, plugin, nodeText, matchedText, index, node, $) {
			var result = eval($[1]);
			return result ? result.toString() + $[2] : null;
		}
	}, {
		// Replacement of a lower typographic quote
		// This match uses strip to match a expression that should NOT be fully replaced.
		// Everything that will be matched through the before or after groups will stay in the text, only the main group will be replaced
		//    before  main  after
		//        v    v    v
		match: /(\s|^)(")([^\s])/,
		replace: '\u201e',
		// Strip is `true` so all values of the strip configuration will stay at their corresponding default values
		strip: true
	}]
}