evolutionComposer jQuery Plugin

Ben Tiedt — Tue, 25 Jun 2019 19:41:48 GMT

Current Revision posted to API Documentation by Ben Tiedt on 06/25/2019 19:41:48

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 [[hashtags Composer Plugin|hashtag]] and [[mentions Composer Plugin|@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 jQuery Plugin|evolutionResize plugin]].

Usage

Initializes a composer plugin against a textarea.

$('textarea.myTextArea').evolutionComposer(options)

Initialize a composer with [[hashtags Composer Plugin|hashtags]] and [[mentions Composer Plugin|@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 plugins
focus: 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 Composer Plugin|hashtags]] and [[mentions Composer Plugin|@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 input
context: 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 context
event: Event

onkeypress

Handles keypress events on the Composer's textarea, but only when the plugin defining the handler is active.

arguments:

context: Composer plugin context
event: Event

oninput

Handles input events on the Composer's textarea, but only when the plugin defining the handler is active.

arguments:

context: Composer plugin context
event: 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 value
start: word start index
stop: word stop index

replace

Replaces text on the input.

parameters

start: index at which to begin replacement
stop: index at which to end replacement
newValue: 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 highlight
stop: stop index for the highlight
className: CSS class name to apply to the highlight

renderHighlights

Renders all highlights queued up by calls to addHighlight.