jquery.textSelection: Document methods and parameters
Change-Id: I9e4112a75ae7abc8c479efc39a438c3b59933418
This commit is contained in:
Bartosz Dziewoński
parent
4a9583e7c4
commit
657ff95613
2 changed files with 124 additions and 31 deletions
|
|
@ -34,6 +34,7 @@
|
|||
"resources/src/jquery/jquery.spinner.js",
|
||||
"resources/src/jquery/jquery.suggestions.js",
|
||||
"resources/src/jquery/jquery.tabIndex.js",
|
||||
"resources/src/jquery/jquery.textSelection.js",
|
||||
"resources/lib/jquery.client/jquery.client.js",
|
||||
"resources/lib/oojs/oojs.jquery.js",
|
||||
"resources/lib/oojs-ui/oojs-ui-core.js",
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
/**
|
||||
/*!
|
||||
* These plugins provide extra functionality for interaction with textareas.
|
||||
*
|
||||
* - encapsulateSelection: Ported from skins/common/edit.js by Trevor Parscal
|
||||
|
|
@ -7,7 +7,42 @@
|
|||
* 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)
|
||||
*/
|
||||
|
||||
/**
|
||||
* @class jQuery.plugin.textSelection
|
||||
*
|
||||
* Do things to the selection in a `<textarea>`, or a textarea-like editable element.
|
||||
*
|
||||
* 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 '!'
|
||||
*/
|
||||
( function ( $ ) {
|
||||
/**
|
||||
* Do things to the selection in a `<textarea>`, or a textarea-like editable element.
|
||||
*
|
||||
* 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 '!'
|
||||
*
|
||||
* @param {string} command Command to execute, one of:
|
||||
*
|
||||
* - {@link jQuery.plugin.textSelection#getContents getContents}
|
||||
* - {@link jQuery.plugin.textSelection#setContents setContents}
|
||||
* - {@link jQuery.plugin.textSelection#getSelection getSelection}
|
||||
* - {@link jQuery.plugin.textSelection#encapsulateSelection encapsulateSelection}
|
||||
* - {@link jQuery.plugin.textSelection#getCaretPosition getCaretPosition}
|
||||
* - {@link jQuery.plugin.textSelection#setSelection setSelection}
|
||||
* - {@link jQuery.plugin.textSelection#scrollToCaretPosition scrollToCaretPosition}
|
||||
* - {@link jQuery.plugin.textSelection#register register}
|
||||
* - {@link jQuery.plugin.textSelection#unregister unregister}
|
||||
* @param {Mixed} [options] Options to pass to the command
|
||||
* @return {Mixed} Depending on the command
|
||||
*/
|
||||
$.fn.textSelection = function ( command, options ) {
|
||||
var fn,
|
||||
alternateFn,
|
||||
|
|
@ -15,24 +50,29 @@
|
|||
|
||||
fn = {
|
||||
/**
|
||||
* Get the contents of the textarea
|
||||
* Get the contents of the textarea.
|
||||
*
|
||||
* @private
|
||||
* @return {string}
|
||||
*/
|
||||
getContents: function () {
|
||||
return this.val();
|
||||
},
|
||||
|
||||
/**
|
||||
* Set the contents of the textarea, replacing anything that was there before
|
||||
* Set the contents of the textarea, replacing anything that was there before.
|
||||
*
|
||||
* @private
|
||||
* @param {string} content
|
||||
*/
|
||||
setContents: function ( content ) {
|
||||
this.val( content );
|
||||
},
|
||||
|
||||
/**
|
||||
* Get the currently selected text in this textarea.
|
||||
*
|
||||
* @private
|
||||
* @return {string}
|
||||
*/
|
||||
getSelection: function () {
|
||||
|
|
@ -47,13 +87,29 @@
|
|||
|
||||
return retval;
|
||||
},
|
||||
|
||||
/**
|
||||
* Inserts text at the beginning and end of a text selection, optionally
|
||||
* Insert text at the beginning and end of a text selection, optionally
|
||||
* inserting text at the caret when selection is empty.
|
||||
*
|
||||
* @param {Object} options Options
|
||||
* FIXME document the options parameters
|
||||
* Also focusses the textarea.
|
||||
*
|
||||
* @private
|
||||
* @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
|
||||
*/
|
||||
encapsulateSelection: function ( options ) {
|
||||
return this.each( function () {
|
||||
|
|
@ -63,6 +119,7 @@
|
|||
post = options.post;
|
||||
|
||||
/**
|
||||
* @ignore
|
||||
* Check if the selected text is the same as the insert text
|
||||
*/
|
||||
function checkSelectedText() {
|
||||
|
|
@ -86,6 +143,7 @@
|
|||
}
|
||||
|
||||
/**
|
||||
* @ignore
|
||||
* Do the splitlines stuff.
|
||||
*
|
||||
* Wrap each line of the selected text with pre and post
|
||||
|
|
@ -168,13 +226,16 @@
|
|||
options.replace, options.splitlines ] );
|
||||
} );
|
||||
},
|
||||
|
||||
/**
|
||||
* Get the position (in resolution of bytes not necessarily characters)
|
||||
* in a textarea
|
||||
* Get the current cursor position (in UTF-16 code units) in a textarea.
|
||||
*
|
||||
* @param {Object} options Options
|
||||
* FIXME document the options parameters
|
||||
* @return {number} Position
|
||||
* @private
|
||||
* @param {Object} [options]
|
||||
* @param {Object} [options.startAndEnd=false] Return range of the selection rather than just start
|
||||
* @return {Mixed}
|
||||
* - When `startAndEnd` is `false`: number
|
||||
* - When `startAndEnd` is `true`: array with two numbers, for start and end of selection
|
||||
*/
|
||||
getCaretPosition: function ( options ) {
|
||||
function getCaret( e ) {
|
||||
|
|
@ -189,10 +250,16 @@
|
|||
}
|
||||
return getCaret( this.get( 0 ) );
|
||||
},
|
||||
|
||||
/**
|
||||
* @param {Object} options options
|
||||
* FIXME document the options parameters
|
||||
* Set the current cursor position (in UTF-16 code units) in a textarea.
|
||||
*
|
||||
* @private
|
||||
* @param {Object} [options]
|
||||
* @param {number} options.start
|
||||
* @param {number} [options.end=options.start]
|
||||
* @return {jQuery}
|
||||
* @chainable
|
||||
*/
|
||||
setSelection: function ( options ) {
|
||||
return this.each( function () {
|
||||
|
|
@ -213,15 +280,17 @@
|
|||
}
|
||||
} );
|
||||
},
|
||||
|
||||
/**
|
||||
* Scroll a textarea to the current cursor position. You can set the cursor
|
||||
* position with setSelection()
|
||||
* position with #setSelection.
|
||||
*
|
||||
* @param {Object} options options
|
||||
* @cfg {boolean} [force=false] Whether to force a scroll even if the caret position
|
||||
* @private
|
||||
* @param {Object} [options]
|
||||
* @param {string} [options.force=false] Whether to force a scroll even if the caret position
|
||||
* is already visible.
|
||||
* FIXME document the options parameters
|
||||
* @return {jQuery}
|
||||
* @chainable
|
||||
*/
|
||||
scrollToCaretPosition: function ( options ) {
|
||||
function getLineLength( e ) {
|
||||
|
|
@ -290,6 +359,25 @@
|
|||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* @method register
|
||||
*
|
||||
* Register an alternative textSelection API for this element.
|
||||
*
|
||||
* @private
|
||||
* @param {Object} functions Functions to replace. Keys are command names (as in #textSelection,
|
||||
* except 'register' and 'unregister'). Values are functions to execute when a given command is
|
||||
* called.
|
||||
*/
|
||||
|
||||
/**
|
||||
* @method unregister
|
||||
*
|
||||
* Unregister the alternative textSelection API for this element (see #register).
|
||||
*
|
||||
* @private
|
||||
*/
|
||||
|
||||
alternateFn = $( this ).data( 'jquery.textSelection' );
|
||||
|
||||
// Apply defaults
|
||||
|
|
@ -299,38 +387,34 @@
|
|||
// case 'getSelection': // no params
|
||||
case 'encapsulateSelection':
|
||||
options = $.extend( {
|
||||
pre: '', // Text to insert before the cursor/selection
|
||||
peri: '', // Text to insert between pre and post and select afterwards
|
||||
post: '', // Text to insert after the cursor/selection
|
||||
ownline: false, // Put the inserted text on a line of its own
|
||||
replace: false, // If there is a selection, replace it with peri instead of leaving it alone
|
||||
selectPeri: true, // Select the peri text if it was inserted (but not if there was a selection and replace==false, or if splitlines==true)
|
||||
splitlines: false, // If multiple lines are selected, encapsulate each line individually
|
||||
selectionStart: undefined, // Position to start selection at
|
||||
selectionEnd: undefined // Position to end selection at. Defaults to start
|
||||
pre: '',
|
||||
peri: '',
|
||||
post: '',
|
||||
ownline: false,
|
||||
replace: false,
|
||||
selectPeri: true,
|
||||
splitlines: false,
|
||||
selectionStart: undefined,
|
||||
selectionEnd: undefined
|
||||
}, options );
|
||||
break;
|
||||
case 'getCaretPosition':
|
||||
options = $.extend( {
|
||||
// Return [start, end] instead of just start
|
||||
startAndEnd: false
|
||||
}, options );
|
||||
break;
|
||||
case 'setSelection':
|
||||
options = $.extend( {
|
||||
// Position to start selection at
|
||||
start: undefined,
|
||||
// Position to end selection at. Defaults to start
|
||||
end: undefined
|
||||
}, options );
|
||||
|
||||
if ( options.end === undefined ) {
|
||||
options.end = options.start;
|
||||
}
|
||||
break;
|
||||
case 'scrollToCaretPosition':
|
||||
options = $.extend( {
|
||||
force: false // Force a scroll even if the caret position is already visible
|
||||
force: false
|
||||
}, options );
|
||||
break;
|
||||
case 'register':
|
||||
|
|
@ -351,4 +435,12 @@
|
|||
return retval;
|
||||
};
|
||||
|
||||
/**
|
||||
* @class jQuery
|
||||
*/
|
||||
/**
|
||||
* @method textSelection
|
||||
* @inheritdoc jQuery.plugin.textSelection#textSelection
|
||||
*/
|
||||
|
||||
}( jQuery ) );
|
||||
|
|
|
|||
Loading…
Reference in a new issue