resources/src/jquery/jquery.textSelection.js
/*!
* These plugins provide extra functionality for interaction with textareas.
*
* - encapsulateSelection: Ported from skins/common/edit.js by Trevor Parscal
* © 2009 Wikimedia Foundation (GPLv2) - https://www.wikimedia.org
* - getCaretPosition, scrollToCaretPosition: Ported from Wikia's LinkSuggest extension
* https://github.com/Wikia/app/blob/c0cd8b763/extensions/wikia/LinkSuggest/js/jquery.wikia.linksuggest.js
* © 2010 Inez Korczyński (korczynski@gmail.com) & Jesús Martínez Novo (martineznovo@gmail.com) (GPLv2)
*/
/**
* Do things to the selection in a `<textarea>`, or a textarea-like editable element.
* Provided by the `jquery.textSelection` ResourceLoader module.
*
* @example
* mw.loader.using( 'jquery.textSelection' ).then( () => {
* const contents = $( '#wpTextbox1' ).textSelection( 'getContents' );
* } );
*
* @module jquery.textSelection
*/
( function () {
/**
* Checks if you can try to use insertText (it might still fail).
*
* @ignore
* @return {boolean}
*/
function supportsInsertText() {
return $( this ).data( 'jquery.textSelection' ) === undefined &&
typeof document.execCommand === 'function' &&
typeof document.queryCommandSupported === 'function' &&
document.queryCommandSupported( 'insertText' );
}
/**
* Insert text into textarea or contenteditable.
*
* @ignore
* @param {HTMLElement} field Field to select.
* @param {string} content Text to insert.
* @param {Function} fallback To execute as a fallback.
*/
function execInsertText( field, content, fallback ) {
var inserted = false;
if (
supportsInsertText() &&
!(
// Support: Chrome, Safari
// Inserting multiple lines is very slow in Chrome/Safari (T343795)
// If this is ever fixed, remove the dependency on jquery.client
$.client.profile().layout === 'webkit' &&
content.split( '\n' ).length > 100
)
) {
field.focus();
try {
if (
// Ensure the field was focused, otherwise we can't use execCommand() to change it.
// focus() can fail if e.g. the field is disabled, or its container is inert.
document.activeElement === field &&
// Try to insert
document.execCommand( 'insertText', false, content )
) {
inserted = true;
}
} catch ( e ) {}
}
// Fallback
if ( !inserted ) {
fallback.call( field, content );
}
}
var fn = {
/**
* Get the contents of the textarea.
*
* @return {string}
* @memberof module:jquery.textSelection
*/
getContents: function () {
return this.val();
},
/**
* Set the contents of the textarea, replacing anything that was there before.
*
* @param {string} content
* @return {jQuery}
* @chainable
* @memberof module:jquery.textSelection
*/
setContents: function ( content ) {
return this.each( function () {
var scrollTop = this.scrollTop;
this.select();
execInsertText( this, content, function () {
$( this ).val( content );
} );
// Setting this.value may scroll the textarea, restore the scroll position
this.scrollTop = scrollTop;
} );
},
/**
* Get the currently selected text in this textarea.
*
* @return {string}
* @memberof module:jquery.textSelection
*/
getSelection: function () {
var el = this.get( 0 );
var val;
if ( !el ) {
val = '';
} else {
val = el.value.slice( el.selectionStart, el.selectionEnd );
}
return val;
},
/**
* Replace the selected text in the textarea with the given text, or insert it at the cursor.
*
* @param {string} value
* @return {jQuery}
* @chainable
* @memberof module:jquery.textSelection
*/
replaceSelection: function ( value ) {
return this.each( function () {
execInsertText( this, value, function () {
var allText = $( this ).textSelection( 'getContents' );
var currSelection = $( this ).textSelection( 'getCaretPosition', { startAndEnd: true } );
var startPos = currSelection[ 0 ];
var endPos = currSelection[ 1 ];
$( this ).textSelection( 'setContents', allText.slice( 0, startPos ) + value +
allText.slice( endPos ) );
$( this ).textSelection( 'setSelection', {
start: startPos,
end: startPos + value.length
} );
} );
} );
},
/**
* Insert text at the beginning and end of a text selection, optionally
* inserting text at the caret when selection is empty.
*
* Also focusses the textarea.
*
* @param {Object} [options]
* @param {string} [options.pre] Text to insert before the cursor/selection
* @param {string} [options.peri] Text to insert between pre and post and select afterwards
* @param {string} [options.post] Text to insert after the cursor/selection
* @param {boolean} [options.ownline=false] Put the inserted text on a line of its own
* @param {boolean} [options.replace=false] If there is a selection, replace it with peri
* instead of leaving it alone
* @param {boolean} [options.selectPeri=true] Select the peri text if it was inserted (but not
* if there was a selection and replace==false, or if splitlines==true)
* @param {boolean} [options.splitlines=false] If multiple lines are selected, encapsulate
* each line individually
* @param {number} [options.selectionStart] Position to start selection at
* @param {number} [options.selectionEnd=options.selectionStart] Position to end selection at
* @return {jQuery}
* @chainable
* @memberof module:jquery.textSelection
*/
encapsulateSelection: function ( options ) {
return this.each( function () {
var selText, isSample,
pre = options.pre,
post = options.post;
/**
* Check if the selected text is the same as the insert text
*
* @ignore
*/
function checkSelectedText() {
if ( !selText ) {
selText = options.peri;
isSample = true;
} else if ( options.replace ) {
selText = options.peri;
} else {
while ( selText.charAt( selText.length - 1 ) === ' ' ) {
// Exclude ending space char
selText = selText.slice( 0, -1 );
post += ' ';
}
while ( selText.charAt( 0 ) === ' ' ) {
// Exclude prepending space char
selText = selText.slice( 1 );
pre = ' ' + pre;
}
}
}
/**
* Do the splitlines stuff.
*
* Wrap each line of the selected text with pre and post
*
* @ignore
* @param {string} text Selected text
* @param {string} preText Text before
* @param {string} postText Text after
* @return {string} Wrapped text
*/
function doSplitLines( text, preText, postText ) {
var insText = '',
selTextArr = text.split( '\n' );
for ( var i = 0; i < selTextArr.length; i++ ) {
insText += preText + selTextArr[ i ] + postText;
if ( i !== selTextArr.length - 1 ) {
insText += '\n';
}
}
return insText;
}
isSample = false;
$( this ).trigger( 'focus' );
if ( options.selectionStart !== undefined ) {
$( this ).textSelection( 'setSelection', { start: options.selectionStart, end: options.selectionEnd } );
}
selText = $( this ).textSelection( 'getSelection' );
var allText = $( this ).textSelection( 'getContents' );
var currSelection = $( this ).textSelection( 'getCaretPosition', { startAndEnd: true } );
var startPos = currSelection[ 0 ];
var endPos = currSelection[ 1 ];
checkSelectedText();
var combiningCharSelectionBug = false;
if (
options.selectionStart !== undefined &&
endPos - startPos !== options.selectionEnd - options.selectionStart
) {
// This means there is a difference in the selection range returned by browser and what we passed.
// This happens for Safari 5.1, Chrome 12 in the case of composite characters. Ref T32130
// Set the startPos to the correct position.
startPos = options.selectionStart;
combiningCharSelectionBug = true;
// TODO: The comment above is from 2011. Is this still a problem for browsers we support today?
// Minimal test case: https://jsfiddle.net/z4q7a2ko/
}
var insertText = pre + selText + post;
if ( options.splitlines ) {
insertText = doSplitLines( selText, pre, post );
}
if ( options.ownline ) {
if ( startPos !== 0 && allText.charAt( startPos - 1 ) !== '\n' && allText.charAt( startPos - 1 ) !== '\r' ) {
insertText = '\n' + insertText;
pre += '\n';
}
if ( allText.charAt( endPos ) !== '\n' && allText.charAt( endPos ) !== '\r' ) {
insertText += '\n';
post += '\n';
}
}
if ( combiningCharSelectionBug ) {
$( this ).textSelection( 'setContents', allText.slice( 0, startPos ) + insertText +
allText.slice( endPos ) );
} else {
$( this ).textSelection( 'replaceSelection', insertText );
}
if ( isSample && options.selectPeri && ( !options.splitlines || ( options.splitlines && selText.indexOf( '\n' ) === -1 ) ) ) {
$( this ).textSelection( 'setSelection', {
start: startPos + pre.length,
end: startPos + pre.length + selText.length
} );
} else {
$( this ).textSelection( 'setSelection', {
start: startPos + insertText.length
} );
}
$( this ).trigger( 'encapsulateSelection', [ options.pre, options.peri, options.post, options.ownline,
options.replace, options.splitlines ] );
} );
},
/**
* Get the current cursor position (in UTF-16 code units) in a textarea.
*
* @param {Object} [options]
* @param {Object} [options.startAndEnd=false] Return range of the selection rather than just start
* @return {number|number[]}
* - When `startAndEnd` is `false`: number
* - When `startAndEnd` is `true`: array with two numbers, for start and end of selection
* @memberof module:jquery.textSelection
*/
getCaretPosition: function ( options ) {
function getCaret( e ) {
var caretPos = 0,
endPos = 0;
if ( e ) {
caretPos = e.selectionStart;
endPos = e.selectionEnd;
}
return options.startAndEnd ? [ caretPos, endPos ] : caretPos;
}
return getCaret( this.get( 0 ) );
},
/**
* Set the current cursor position (in UTF-16 code units) in a textarea.
*
* @param {Object} [options]
* @param {number} options.start
* @param {number} [options.end=options.start]
* @return {jQuery}
* @chainable
* @memberof module:jquery.textSelection
*/
setSelection: function ( options ) {
return this.each( function () {
// Opera 9.0 doesn't allow setting selectionStart past
// selectionEnd; any attempts to do that will be ignored
// Make sure to set them in the right order
if ( options.start > this.selectionEnd ) {
this.selectionEnd = options.end;
this.selectionStart = options.start;
} else {
this.selectionStart = options.start;
this.selectionEnd = options.end;
}
} );
},
/**
* Scroll a textarea to the current cursor position. You can set the cursor
* position with {@link module:jquery.textSelection.setSelection setSelection}.
*
* @param {Object} [options]
* @param {string} [options.force=false] Whether to force a scroll even if the caret position
* is already visible.
* @return {jQuery}
* @chainable
* @memberof module:jquery.textSelection
*/
scrollToCaretPosition: function ( options ) {
return this.each( function () {
var clientHeight = this.clientHeight,
origValue = this.value,
origSelectionStart = this.selectionStart,
origSelectionEnd = this.selectionEnd,
origScrollTop = this.scrollTop;
// Delete all text after the selection and scroll the textarea to the end.
// This ensures the selection is visible (aligned to the bottom of the textarea).
// Then restore the text we deleted without changing scroll position.
this.value = this.value.slice( 0, this.selectionEnd );
this.scrollTop = this.scrollHeight;
// Chrome likes to adjust scroll position when changing value, so save and re-set later.
// Note that this is not equal to scrollHeight, it's scrollHeight minus clientHeight.
var calcScrollTop = this.scrollTop;
this.value = origValue;
this.selectionStart = origSelectionStart;
this.selectionEnd = origSelectionEnd;
if ( !options.force ) {
// Check if all the scrolling was unnecessary and if so, restore previous position.
// If the current position is no more than a screenful above the original,
// the selection was previously visible on the screen.
if ( calcScrollTop < origScrollTop && origScrollTop - calcScrollTop < clientHeight ) {
calcScrollTop = origScrollTop;
}
}
this.scrollTop = calcScrollTop;
$( this ).trigger( 'scrollToPosition' );
} );
}
};
/**
* Register an alternative textSelection API for this element.
*
* @method register
* @param {Object} functions Functions to replace. Keys are command names (as in {@link module:jquery.textSelection.textSelection textSelection},
* except 'register' and 'unregister'). Values are functions to execute when a given command is
* called.
* @memberof module:jquery.textSelection
*/
/**
* Unregister the alternative textSelection API for this element (see {@link module:jquery.textSelection.register register}).
*
* @method unregister
* @memberof module:jquery.textSelection
*/
/**
* Execute a textSelection command about the element.
* @example
* var $textbox = $( '#wpTextbox1' );
* $textbox.textSelection( 'setContents', 'This is bold!' );
* $textbox.textSelection( 'setSelection', { start: 8, end: 12 } );
* $textbox.textSelection( 'encapsulateSelection', { pre: '<b>', post: '</b>' } );
* // Result: Textbox contains 'This is <b>bold</b>!', with cursor before the '!'
* @memberof module:jquery.textSelection
* @method
* @param {string} command Command to execute, one of:
*
* - {@link module:jquery.textSelection.getContents getContents}
* - {@link module:jquery.textSelection.setContents setContents}
* - {@link module:jquery.textSelection.getSelection getSelection}
* - {@link module:jquery.textSelection.replaceSelection replaceSelection}
* - {@link module:jquery.textSelection.encapsulateSelection encapsulateSelection}
* - {@link module:jquery.textSelection.getCaretPosition getCaretPosition}
* - {@link module:jquery.textSelection.setSelection setSelection}
* - {@link module:jquery.textSelection.scrollToCaretPosition scrollToCaretPosition}
* - {@link module:jquery.textSelection.register register}
* - {@link module:jquery.textSelection.unregister unregister}
* @param {any} [commandOptions] Options to pass to the command
* @return {any} Depending on the command
*/
$.fn.textSelection = function ( command, commandOptions ) {
var alternateFn = $( this ).data( 'jquery.textSelection' );
// Apply defaults
switch ( command ) {
// case 'getContents': // no params
// case 'setContents': // no params with defaults
// case 'getSelection': // no params
// case 'replaceSelection': // no params with defaults
case 'encapsulateSelection':
commandOptions = $.extend( {
pre: '',
peri: '',
post: '',
ownline: false,
replace: false,
selectPeri: true,
splitlines: false,
selectionStart: undefined,
selectionEnd: undefined
}, commandOptions );
break;
case 'getCaretPosition':
commandOptions = $.extend( {
startAndEnd: false
}, commandOptions );
break;
case 'setSelection':
commandOptions = $.extend( {
start: undefined,
end: undefined
}, commandOptions );
if ( commandOptions.end === undefined ) {
commandOptions.end = commandOptions.start;
}
break;
case 'scrollToCaretPosition':
commandOptions = $.extend( {
force: false
}, commandOptions );
break;
case 'register':
if ( alternateFn ) {
throw new Error( 'Another textSelection API was already registered' );
}
$( this ).data( 'jquery.textSelection', commandOptions );
// No need to update alternateFn as this command only stores the options.
// A command that uses it will set it again.
return;
case 'unregister':
$( this ).removeData( 'jquery.textSelection' );
return;
}
var retval = ( alternateFn && alternateFn[ command ] || fn[ command ] ).call( this, commandOptions );
return retval;
};
}() );