jQuery.fn.evolutionComposer
The composer is a jQuery plugin which enhances a textarea
element with a shell API, enabling plugins to add extra interactive functionality to the textarea
in a cooperative manner. Composer plugins define when they should be activated and released based on states of the textarea
, and can manipulate the textarea
's, text, size, highlights, and ultimately its value as returned to the client code.
Composer plugins enable hashtag and @mention support on textareas via Evolution-provided plugins, though the composer is not limited to only these plugins.
Each composer instance also implements auto-resizing against the textarea via the evolutionResize plugin.
Usage
Initializes a composer plugin against a textarea
.
$('textarea.myTextArea').evolutionComposer(options)
Initialize a composer with hashtags and @mentions.
$('textarea.myTextArea').evolutionComposer({
plugins: ['hashtags', 'mentions']
});
Retrieves the current value of the Composer. In the case of usage of hashtags or mentions, the value will include the proper tokens for tags and mentions.
var value = $('textarea.myTextArea').evolutionCompser('val');
Options
plugins
: Array of Composer plugin objects or string names of Composer pluginsfocus
: when true, auto-focuses. default:false
contentTypeId
: when set, identifies the type of content being edited
All other options are passed to Composer plugins.
Methods
val
Gets or sets the current value of the composer.
Note: This should be used instead of $('textarea').val()
, as each Composer plugin gets the opportunity to mutate the value before it is returned to the caller.
// get a value
var value = $('textarea').evolutionComposer('val');
// set a value
$('textarea').evolutionComposer('val', 'new value');
onkeydown
Handles the keydown event within a Composer.
Note: This should be used instead of $('textarea).on('keydown', fn)
as each Composer plugin gets the opportunity to conditionally interact and cancel this event.
$('textarea').evolutionComposer('onkeydown', function(e) {
// handle event
});
oninput
Handles the input event within a Composer.
Note: This should be used instead of $('textarea).on('input', fn)
as each Composer plugin gets the opportunity to conditionally interact and cancel this event. Input
is shimmed in older browsers which do not natively support the event.
$('textarea').evolutionComposer('oninput', function(e) {
// handle event
});
resize
Resizes a Composer.
Note: This should be used instead of applying width and height directly to the textarea
as each Composer plugin gets the opportunity to interact with this change.
var newWidth = 300,
newHeight = 200;
$('textarea').evolutionComposer('resize', newWidth, newHeight);
Composer Plugin API Methods
Composer plugins are objects defined within jQuery.fn.evolutionComposer.plugins
. Composer plugins cooperate with each other, declaring when they should be active or inactive, and share in mutating the final state of the composer's value. Built-in plugins include hashtags and @mentions.
init
Called on each plugin passed to the Composer when the Composer is created.
arguments
context
: Composer plugin context
onTransform
Called on each plugin passed to the Composer whenever the value of the Composer changes, either through user interaction or through evolutionComposer(
val)
.
arguments:
context
: Composer plugin context
shouldActivate
When a plugin is not currently active, called on each plugin passed to the Composer on input
events until one returns true
. When a plugin returns true
, that plugin is considered active and is passed key events exclusively (blocking other plugins) until the plugin releases control back to the composer.
An example usage of this technique is hashtag and @mention auto-complete selection mode, where typing '@' will trigger specific plugin-defined actions, UI, and event handlers to to run until a selection is made or cancelled.
arguments:
context
: Composer plugin context
returns:
- Boolean true or false
onActivate
Called on a plugin when it transitions to the active state due to user interaction and the shouldActivate
method
arguments:
context
: Composer plugin context
onDeactivate
Called on a plugin when it transitions to the inactive state due to the plugin releasing itself via the context
's release()
method.
arguments:
context
: Composer plugin context
val
Allows a plugin passed to the Composer an opportunity to mutate the value of the decorated textarea
before it is returned to the caller of $('textarea').evolutionComposer('val'). In this manner, a Composer plugin can track internal state that is not visible to the user but is available as tokens within the final value returned to the caller, such as hashtag or @mention tokens.
arguments:
val
: Current raw value of the inputcontext
: Composer plugin context
returns:
- Transformed value, potentially modified by the plugin.
onkeydown
Handles keydown
events on the Composer's textarea
, but only when the plugin defining the handler is active.
arguments:
context
: Composer plugin contextevent
: Event
onkeypress
Handles keypress
events on the Composer's textarea
, but only when the plugin defining the handler is active.
arguments:
context
: Composer plugin contextevent
: Event
oninput
Handles input
events on the Composer's textarea
, but only when the plugin defining the handler is active.
arguments:
context
: Composer plugin contextevent
: Event
Composer Plugin API Context
Each method of the Composer Plugin API is passed the current Composer context. The context exposes data to the plugin as well as enables manipulation of the composer via methods on the context.
settings
All options initially passed to Composer during its construction via $('textarea').evolutionComposer(options)
.
input
The selected textarea
elements decorated by the Composer instance.
data
Stores or retrieves contextual data against a plugin instance of the composer instance.
// store data
context.data(key, value);
// retrieve data
var value = context.data(key);
val
Returns the current raw value of the composer, not processed by other plugins.
var value = context.val()
release
When active, context.release()
releases control back to the parent evolutionComposer
plugin. Only when a plugin is active does it receive keypress
, keydown
, and input
events.
context.release();
caretPosition
Returns the Composer's current caret position index.
var position = context.caretPosition();
currentWord
Returns an object regarding the current word surrounding a caret position.
var currentWord = context.currentWord();
Object contains the properties:
value
: word valuestart
: word start indexstop
: word stop index
replace
Replaces text on the input.
parameters
start
: index at which to begin replacementstop
: index at which to end replacementnewValue
: new value to splice in
clearHighlights
Clears any current highlights on the input.
context.clearHighlights();
addHighlight
Adds a highlight to the input. The highlight does not render immediately, but is instead tracked until renderHighlights
is called.
context.addHighlight({ 5, 20, 'myClassName' });
parameters
start
: start index for the highlightstop
: stop index for the highlightclassName
: CSS class name to apply to the highlight
renderHighlights
Renders all highlights queued up by calls to addHighlight
.