Control.TextArea
Cross browser textarea manipulation for Prototype.js
Introduction
Decent, flexible WYSIWYG editing in the browser is still an inconsistent affair at best in terms of user experience, integration effort, and generated markup. In the meantime a crop of text formatting languages such as Markdown, Textile, BBCode and wiki markup have emerged as ways for users to enter rich content in a controlled enviornment.
Control.TextArea provides a toolbar for textareas where users are entering text in one of these markup languages. In addition to a toolbar it provides access to a cross browser text selection and manipulation API so that creating new functionality, or integration with your custom application features is vastly easier.
Example
The example below demonstrates both components of Control.TextArea as it is used in other areas of the site. This implementation is specific to the Markdown formatting language.
Sample Code
var toolbar = new Control.TextArea.Toolbar(new Control.TextArea('markdown_example'));
//all button callbacks are automatically bound to the Control.TextArea object
toolbar.addButton('Bold',function(){
this.wrapSelection('**','**');
});
toolbar.addButton('Link',function(){
var selection = this.getSelection();
var response = prompt('Enter Link URL','');
if(response == null)
return;
this.replaceSelection('[' + (selection == '' ? 'Link Text' : selection) + '](' + (response == '' ? 'http://link_url/' : response) + ')');
});
toolbar.addButton('Code Block',function(){
this.injectEachSelectedLine(function(lines,line){
lines.push((event.shiftKey ? line.replace(/ /,'') : ' ' + line));
return lines;
});
});How to Read the API Table
Anything in the method and property lists that ends with "()" is a method, and anything that doesn't is a property. All events are specifiable in the options hash, or via "observe()" if Object.Event has been included on the page before Control.Tabs was. In a method signature, each argument is separated by a comma, if the words are lower case it refers to the data type and gives a hint to what it is used for, if there is an upper case word it refers to the class of object that must be used. Arguments with [square brackets] around them are optional.
Control.TextArea Instance Methods and Properties
| Return | Name | Description |
| Control.TextArea | initialize(mixed element_id) | String id or Element object of a textarea. |
| string | getValue() | Get the value / contents of the textarea. |
| string | getSelection() | Get the currently selected text. |
| void | replaceSelection(string new_text) | Replace the currently selected text. |
| void | wrapSelection(string before_text, string after_text) | Wrap the currently selected text. |
| void | insertBeforeSelection(string text) | |
| void | insertAfterSelection(string text) | |
| void | injectEachSelectedLine(function callback [,string before_text [,string after_text]]) | Works just like Prototype's Enumerable.inject(). The callback will be called for each selected line, and the return array will be joined, and will replace the current selection. |
| void | insertBeforeEachSelectedLine(string text [,string before_text [,string after_text]]) | Inserts text before each selected line. Optionally you can put text before and after the whole selection as well. |
| int | onChangeTimeoutLength | Length of time before the change event is triggered. |
| Element | element | The textarea element that this instance is attached to. |
Control.TextArea Events
If Object.Event has been included, events can be observed by calling Control.TextArea.observe() to observe all instances, or by calling observe() on any particular instance to just observe that one.
| Name | Description |
| change(string new_value) | This event exists because the 'change' event on the textarea element is not fired when we modify the contents via this script. Observing 'change' on the Control.TextArea instance instead will allow you to observe when the textarea changes from key presses, manipulation from Control.TextArea, and on cuts and pastes for browsers that allow it. |
Control.TextArea.Toolbar Instance Methods and Properties
| Return | Name | Description |
| Control.TextArea.ToolBar | initialize(Control.TextArea instance [,mixed toolbar_id]) | If no toolbar_id (Element or string id) is passed, a UL element is inserted before the textarea element in the Control.TextArea instance. |
| void | attachButton(Element node, function callback) | Attach a callback to a node that already exists on the page, callback will be bound to the Control.TextArea instance. |
| void | addButton(string link_text, function callback [,attributes Hash]) | Creates an LI element with an A element inside and attaches it to the toolbar, callback will be bound to the Control.TextArea instance. If attributes are present they will be attached to the A element. |
| Control.TextArea | textarea | The Control.TextArea instance the toolbar is attached to. |
| Element | container | The toolbar Element. |
RSS Changelog
Is available at http://livepipe.net/projects/control_textarea/changelog.rss
Downloads & SVN
The new 2.0 version is available via the button in the upper right.
The Control Suite subversion repository is available at: svn://livepipe.net/control_suite/
The last 1.0 series release is available at http://livepipe.net/downloads/control.textarea.1.0.1.js
Online Forum
Do you have questions, bug reports or suggestions? Visit the Control.TextArea online forum.
Other Resources
Have you written a post or article about Control.TextArea? Please contact me!