Native: Element

Extends the Element native object to include methods useful in managing inputs.

Author: Aaron Newton

Element Method: tidy

Uses String:tidy to clean up common special characters with their ASCII counterparts (smart quotes, elipse characters, stuff from MS Word, etc.).

Syntax

$('myInput').tidy();
 

Returns

• (element) This Element.

Element Method: getTextInRange

Returns the text of an input within a range.

Syntax

$('myInput').getTextInRange(start, end);
 

Arguments

1. start - (integer) beginning select position
2. end - (integer) end position

Returns

• (string) the text in the specified range

Notes

• If the range specified is out of bounds (for instance, if the text is "123" and you query for the range 2-10) the text that is found within the bounds is returned. If no text falls within the bounds, an empty string is returned.

Element Method: getSelectedText

Get the text selected in an input, returns a range (see Element.getTextInRange).

Syntax

$('myInput').getSelectedText();
 

Returns

• (string) The text that is selected

Notes

• If no text is selected, an empty string is returned.

Element Method: getSelectionStart

Returns the index of start of the selected text.

Syntax

$('myInput').getSelectionStart();
 

Returns

• (number) The numerical index of the start of the selection.

Element Method: getSelectionEnd

Returns the index of end of the selected text.

Syntax

$('myInput').getSelectionEnd();
 

Returns

• (number) The numerical index of the end of the selection.

Notes

• If there is no selection, this value will be equal to Element:getSelectionStart

Element Method: getSelectedRange

Returns the range of what is selected within the element.

Syntax

$('myInput').getSelectionRange();
 

Returns

• (object) start and end values (each an integer).

Example return

{start: 2, end: 12}
 

Element Method: setCaretPosition

Sets the caret at the given position.

Syntax

$('myInput').setCaretPosition(pos);
 

Arguments

1. pos - (integer) the location to place the caret OR "end" to place it at the end.

Returns

• (element) This Element.

Example

$('myInput').setCaretPosition(3);
$('myInput').setCaretPosition("end");
 

Element Method: getCaretPosition

Returns the caret position.

Syntax

$('myInput').getCaretPosition();
 

Returns

• (integer) The caret position.

Element Method: selectRange

Selects text within a given range.

Syntax

$('myInput').selectRange(start, end);
 

Arguments

1. start - (integer) starting integer
2. end - (integer) ending integer

Returns

• (element) This Element.

Example

$('myInput').selectRange(2, 4);
 
<input id="test" value="012345" />
$('test').selectRange(2, 4); //selects "23"
 

Element Method: insertAtCursor

Inserts a value at the cursor location; if text is selected, it replaces this text.

Syntax

$('myInput').insertAtCursor(value[, selectText]);
 

Arguments

1. value - (string) value to insert.
2. selectText - (boolean) selects the text after it's been inserted

Returns

• (element) This Element.

Example

$('myInput').insertAtCursor("<br />");
$('myInput').insertAtCursor("type something here", true);
 

Element Method: insertAroundCursor

Inserts two strings around the selected text.

Syntax

$('myInput').insertAroundCursor(options);
 

Arguments

1. options - (object) key/value set of options.

Options

1. before - (string) the prefix to insert before the selected text
2. after - (string) the suffix to insert after the selected text
3. defaultMiddle - (string) value to insert between the prefix and the suffix if no text was selected (defaults to "SOMETHING HERE")

Returns

• (element) This Element.

Example

<input id="test" value="ninjas are the most dangerous thing in the world" />
//let's assume that the user selects the word "ninjas"
$('test').insertAroundCursor({before: "<", after: ">", defaultMiddle: "tag-name"});
//value is now:
//<ninjas> are the most dangerous thing in the world
 

Hash: Element.Properties

This Hash contains the functions that respond to the first argument passed in Element:get, Element:set and Element:erase (this is all standard Mootools methodology).

Element Property: inputValue

Setter:

Sets the value of the form Element.

Syntax:

myElement.set('inputValue', value);
 

Arguments:

1. value - (mixed) a string, boolean, or array, depending on the type of input.

Returns:

• (element) This Element.

Notes:

• When this setter is used on a standard text input or textarea, it just proxies myInput.set('value', value);
• When used on a radio or checkbox, you can pass in a boolean to check or uncheck it, or pass in a string and if the string matches the name, the input will be checked
• When used on a select, you can pass in a string for the option to check (unchecking all others) or an array of strings to check more than one (for multi-selects)

Examples:

$('mySelect').set('inputValue', 'option1'); //option with value 'option1' is selected
$('myMultiSelect').set('inputValue', ['option1', 'option2]); 
    //options w/ values 'option1' and 'option2' are selected
$('myRadio').set('inputValue', true); //the radio is checked
$('myRadio').set('inputValue', 'red'); //if the radio's name is 'red', it is checked
$('myCheckbox').set('inputValue', true); //the checkbox is checked
$('myCheckbox').set('inputValue', 'red'); //if the checkbox's name is 'red', it is checked
$('myTextArea').set('inputValue', 'foo'); //the value of the textarea is 'foo'
$('myTextInput').set('inputValue', 'foo'); //the value of the text input is 'foo'
 

Getter:

Returns the value of the input.

Syntax:

myElement.get('inputValue');
 

Returns:

• (mixed) Depending on the type of object, it may return a string, boolean, or array

Notes:

• When this getter is used on a standard text input or textarea, it just proxies myInput.get('value');
• When used on a checkbox, if the input is checked it will return the true, other wise false
• When used on a radio it will return the value of the radio that is checked that shares the same name or null if none are.
• When used on a select list it will return the value (a string) of the selected option or it's text value if the value is not defined
• When used on a multi-select it will always return an array of the values (strings) of the selected options (or their text values if value is not defined)