{"id":1404,"date":"2011-01-17T13:40:06","date_gmt":"2011-01-17T19:40:06","guid":{"rendered":"http:\/\/bililite.nfshost.com\/blog\/?p=1404"},"modified":"2015-01-14T14:05:19","modified_gmt":"2015-01-14T20:05:19","slug":"cross-browser-text-ranges-and-selections","status":"publish","type":"post","link":"https:\/\/bililite.com\/blog\/2011\/01\/17\/cross-browser-text-ranges-and-selections\/","title":{"rendered":"Cross-Browser Text Ranges and Selections"},"content":{"rendered":"

Updated to version 2.3 on 2014-02-26 for data routines.<\/strong><\/p>\r\n

I was trying to update my sendkeys<\/code> plugin<\/a> to use contentEditable<\/code><\/a>, and realized that it was getting harder and harder to do without some selection\/text replacement library. Each browser is different and even different elements are treated differently. There are a few<\/a> libraries<\/a> out<\/a> there<\/a>, but none handled both input<\/code> and textarea<\/code> elements and<\/strong> regular elements, and would constrain the selections to a given element (critical if I want to edit only part of a document) and none made it easy to simulate arrow keys, moving the selection left or right. So I figured I would make my own.

\r\n

See the code on Github<\/a>.<\/p>\r\n

See the demo (try it in different browsers!)<\/a>.<\/p>\r\n\r\n

I was entering a world of hurt.<\/p>\r\n

But I think I survived, with a great deal of knowledge about browsers and a useful package of routines.<\/p>\r\n

Usage<\/h4>\r\n

bililiteRange(element)<\/code> returns an abstraction of a range of characters within element<\/code>, initially all of the element. The range never extends outside the element. element<\/code> is a DOM element. jQuery is not required or used for this; it involved too much under-the-hood hacking that it was easier to write everything myself.<\/p>\r\n

Note that this fails for the entire <body><\/code> element. I know why, but I don't have the time to fix it, and I haven't used it. If there's any demand, please let me know.<\/p>\r\n

The object exposes the following methods:<\/p>\r\n

\r\n
all()<\/code><\/dt>\r\n
Returns the entire text of the element without changing the bounds of the range.<\/dd>\r\n
all(text {String})<\/code><\/dt>\r\n
Sets the entire text of the element to text<\/code> without changing the bounds of the range.<\/dd>\r\n\r\n
bounds()<\/code><\/dt>\r\n
Returns an Array [start, end]<\/code> of the bounds of the current range. start<\/code> is always >= 0 and end<\/code> is always <= length of the text of the entire element.<\/dd>\r\n
bounds(Array | 'all' | 'selection')<\/code><\/dt>\r\n
Sets the bounds of the current range to the Array [start, end]<\/code>, limited to [0, length of whole element]<\/code>. Does not throw an error for limits out of bounds, just silently limits it. bounds('all')<\/code> sets the range to cover the entire element. bounds('selection')<\/code> sets the range to the part of the current selection that is in the element. This only uses the actual selection if the element is the same as document.activeElement<\/code><\/a>; if the element is not active, then bililiteRange<\/code> sets up event listeners to remember the selection from when the element was<\/em> the active element, and uses that. If the element was never active, it does its best: if the selection is before<\/em> the element, returns [0,0]<\/code> and if the selection is after<\/em> the element, returns [length of whole element, length of whole element]<\/code>. See my discussion of preserving the selection on blur<\/a>.<\/dd>\r\n\r\n
clone()<\/code><\/dt>\r\n
Return a new bililiteRange with the same bounds as this one.<\/dd>\r\n\r\n
data()<\/code><\/dt>\r\n
Returns an object tied to the underlying element. See my later post on bililiteRange data<\/a>.<\/dd>\r\n\r\n
element()<\/code><\/dt>\r\n
Returns the DOM element that the range was defined on.<\/dd>\r\n \r\n
insertEOL()<\/code><\/dt>\r\n
Replaces the text at the current range with a line break. For input<\/code> and textarea<\/code> elements, this is the same as text('\\n')<\/code>. For other elements, this inserts a br<\/code> element.<\/dd>\r\n
This part remains flaky for contenteditable<\/code> elements. I can't get the standards-based browsers to select <br><\/code> elements consistently. Use at your own risk (or fix it for me and let me know!)<\/dd>\r\n\r\n
scrollIntoView([Function])<\/code><\/dt>\r\n
Does its best to scroll the beginning of the range into the visible part of the element, by analogy to Element.scrollIntoView<\/a>. See my post<\/a> for a longer discussion. Note that it does not<\/em> move the element itself, just sets element.scrollTop<\/code> so that the start of the range is within the visible part of the element. If it already visible, does nothing. This only scrolls vertically, not horizontally.<\/dd>\r\n
The function passed in used to do the scrolling, with one parameter that is the target scrollTop<\/code>, and this<\/code> set to the element itself. So, to animate the scrolling, use range.scrollIntoView(function (top) { $(this).animate({scrollTop: top}) })<\/code>. The default function is function (top) { this.scrollTop = top }<\/code>.<\/dd>\r\n\r\n
select()<\/code><\/dt>\r\n
If the element is the same as document.activeElement<\/code><\/a>, then set the window selection to the current range. If the window is not active, change the saved selection to the current range, and use that for bounds('selection')<\/code>. Sets up event listeners so that when the element is activated, the saved selection is restored. See my discussion of preserving the selection on blur<\/a>.<\/dd>\r\n
Note that this does not<\/em> set the focus on the element; use range.element().focus()<\/code> to do that. Note also that elements that are not editable and do not have a tabindex<\/code> cannot be focussed.<\/dd>\r\n\r\n
selection()<\/code><\/dt>\r\n
Short for rng.bounds('selection').text()<\/code>, to get the text currently selected.<\/dd>\r\n
selection(String)<\/code><\/dt>\r\n
Short for rng.bounds('selection').text(text, 'end').select()<\/code>; useful for inserting text at the insertion point. This just inserts the String argument straight in the text; for a more sophisticated function, see sendkeys<\/code> below.<\/dd>\r\n\r\n
sendkeys(String)<\/code><\/dt>\r\n
Basically does text(String, 'end')<\/code> but interprets brace-surrounded words (like '{Backspace}'<\/code> as special commands that execute the corresponding functions in bililiteRange.sendkeys<\/code>, in this case bililiteRange.sendkeys['{Backspace}']<\/code>. See the description<\/a> of the functions available and how to add more.<\/dd>\r\n\r\n
text()<\/code><\/dt>\r\n
Returns a String<\/code> containing the text of the current range (with '\\r\\n'<\/code> converted to '\\n'<\/code>).<\/dd>\r\n
text(String [, 'start'|'end'|'all'])<\/code><\/dt>\r\n
Sets the text of the current range to String<\/code>. If the second argument is present, also sets bounds, to the start of the inserted text, the end of the inserted text (what happens with the usual \"paste\" command) or the entire inserted text. Follow this with select()<\/code> to actually set the selection.<\/dd>\r\n\r\n
top()<\/code><\/dt>\r\n
Returns the \"offsetTop\" for the range--the pixels from the top of the padding box of the element to the beginning of the range. See MSDN's description<\/a> of element dimensions. Will be negative if the element is scrolled so that the range is above the visible part of the element. To scroll the element so that the range is at the top of the element, set element.scrollTop = range.top()<\/code>. See range.scrollIntoView()<\/code> above, and my extended discussion<\/a>.<\/dd>\r\n\r\n
wrap(Node)<\/code><\/dt>\r\n
Wraps the range with the DOM Node<\/a> passed in (generally will be\r\n an HTML element). Only works with ranges defined on the DOM itself; throws an error for ranges in\r\n <input><\/code> or\r\n <textarea><\/code> elements. Depending on the browser, will throw an error for invalid HTML\r\n (like wrapping a <p><\/code>\r\n with a <span><\/code>). For example, to highlight the range, use\r\n rng.wrap (document.createElement('strong'));<\/code><\/dd>\r\n\r\n<\/dl>\r\n\r\n\r\n

Examples<\/h4>\r\n

Replace the first character of an element: bililiteRange(element).bounds([0,1]).text('X')<\/code><\/p>\r\n

Select all of an element: bililiteRange(element).bounds('all').select()<\/code><\/p>\r\n

Implement a \"backspace\" key on an editable element (assuming the element is focused and the selection has been made by the user): 

var rng = bililiteRange(element).bounds('selection');\r\nvar bounds = rng.bounds();\r\nif (bounds[0] == bounds[1]){\r\n  \/\/ no characters selected; it's just an insertion point. Remove the previous character\r\n  rng.bounds([bounds[0]-1, bounds[1]]);\r\n}\r\nrng.text('', 'end'); \/\/ delete the characters and replace the selection<\/code><\/pre><\/p>\r\n
Implement a \"left arrow\" key on an editable element: 
var rng = bililiteRange(element).bounds('selection');\r\nvar bounds = rng.bounds();\r\nif (bounds[0] == bounds[1]){\r\n  \/\/ no characters selected; it's just an insertion point. Move to the left\r\n  rng.bounds([bounds[0]-1, bounds[0]-1]);\r\n}else{\r\n  \/\/ move the insertion point to the left of the selection\r\n  rng.bounds([bounds[0], bounds[0]]);\r\n}\r\nrng.select();<\/code><\/pre><\/p>\r\n\r\n
Plugins<\/h4>\r\n
Inspired by jQuery, I exposed the prototype for the underlying object so it is possible to extend bililiteRange<\/code>. bililiteRange.extend({myplugin:  function(){ do things where this is the bililiteRange object; notably this._el is the original element }; })<\/code>. For instance, you could create the plugin:<\/p>\r\n