Developer’s corner

jQuery EditableText

This widget is a true jQuery-UI widget which displays an editable text. It adapts its style in function of the choosen jQuery-UI theme. It has been built given the instructions of the following page: jQuery-UI - Widget factory.

You can download it here: editableText-deploy.tar.gz. It must be deploy at the root of your web directory. All directories must keep the same name as in the archive: js, css, images and demos. The directory demos contains a demonstration page in which you will have to change the path of jquery.js, jquery-ui.js and jquery-ui.css. This directory is not required for the editableText widget.

Dependencies

This widget has been tested jQuery 1.6 and jQuery-UI 1.8 and requires the following jQuery-UI widgets:

  • jquery.ui.core.js
  • jquery.ui.widget.js

Usage

This widget is divided in two parts: the editor and the display. The editor and the display may be either an inline item or a block item. On the contrary to the display part, the editor may be several kinds of item (i.e. input, select, textarea, …) or even a custom item (that's to say a node you have yourself created).

So, you can create the widget either from the display item:

<p><span id="simpleText">This is the display part.</span> and the editor will be an input[type="text"].</p>
$('#simpleText').editableText();

or from the editor item:

Do you like this widget ? 
<select id="withChoice">
	<option value="Not at all">Not at all</option>
	<option value="No">No</option>
	<option value="Maybe">Maybe</option>
	<option value="A little">A little</option>
	<option value="Yes">Yes</option>
	<option value="It is so great">It is so great</option>
</select>
$('#withChoice').editableText();

In DISPLAY mode: EditableText widgets in DISPLAY mode In EDITOR mode: EditableText widgets in EDITOR mode

Options

Description Possible values Default value
type Tells whether the target item is the display part or the editor part. 'auto', 'display' or 'editor' 'auto'
display Specifies how the editable text (the display AND the editor) must be displayed. 'auto', 'inline' or 'block' 'auto'
widget_class Specifies the class of the widget item. null or any string (it will be then a class name) null
editor_class Specifies the class of the editor part. null or any string (it will be then a class name) null
display_class Specifies the class of the display part. null or any string (it will be then a class name) null
emptyValue Specifies the value displayed by default to indicate there is no value. any string ''
editFct Function called to get/set the text of the editor. A function. A function which uses the function val of the editor (if any).
editEvent Event (on the 'display' element) which shows the editor and hides the display. 'click', 'dblclick', 'mouseover', … 'click'
updateEvent Event (on the 'editor' element) which hides the editor and shows the display. 'focusout', 'click', 'dblclick, 'mouseout', … 'focusout'

Note: the option emptyValue is used only to indicate that a value is missing. It is not the default value ! In addition of this value, the class empty is added to the display element emphasing the lack of value. This class can be useful to customize the style of the editable text.

Events

Description Parameters Return value
onUpdate(…) Function called just before updating the 'display' element. It must tells whether the new text must be set or not. The 1st parameter may be changed to influence the new value to set. newText, oldText, displayItem, editorItem true, false

Example:

$('#littleComputer').editableText({
	// Message to display when there is no value:
	emptyValue: 'Type a simple math operation',
	// Compute the mathematic operation and display: "operation = result":
	onupdate: function(newText, oldText, displayItem, editorItem){
		if ($.trim(newText).length == 0){
			displayItem.css('color', '');
			return true;
		}else if (newText == oldText)
			return newText;
		try{
			displayItem.css('color', 'green');
			return newText+' = '+eval(newText);
		}catch(error){
			displayItem.css('color', 'red');
			return newText+' = ???';
		}
	},
	// Never edit the last operation:
	editFct: function(editor, newText){
		if (newText != undefined)
			return editor.val('');
		else
			return editor.val();
	}
});

Methods

Description Parameters Return value
destroy() Destroys all DOM modifications done by this jQuery-UI widget.
updateDisplay() Updates the display and hides the editor. The new displayed value
text([newText]) Gets/Sets the text to display. nothing (getter) or a string (setter) The displayed value
getEditor() Gets the editor element of this widget. The editor
getDisplay() Gets the display element of this widget. The display part
getWidget() Gets the whole widget element. The widget itself

Example: In this example, there is no updateEvent. To come back from the EDITOR mode to the DISPLAY mode, the user must click on the update button. Thus, updateEvent is null, the event click of the button calls the function updateDisplay of the editableText widget.

<span>Your name:</span>
<div id="specialEditor">
	<label for="surname">Surname: </label><input name="surname" type="text" value="I"></input><br />
	<label for="firstName">First name: </label><input name="firstName" type="text" value="am"></input><br />
	<button type="button" onclick="$('#specialEditor').editableText('updateDisplay')">Update</button>
</div>

Custom editor

$('#specialEditor').editableText({
	type: 'editor',
	display: 'inline',
	updateEvent: null,
	editFct: function(editor, newText){
		if (newText != undefined){
			var text = newText.split(' ');
			editor.children('input[name="surname"]').val(text[0]);
			editor.children('input[name="firstName"]').val(text[1]);
			return newText;
		}else
			return editor.children('input[name="surname"]').val()+' '+editor.children('input[name="firstName"]').val();
	},
	onupdate: function(newText, oldText, displayItem, editorItem){
		var text = newText.split(' ');
		return text[0].toUpperCase()+' '+text[1].toLowerCase();
	}
});

Note: This time, the editableText widget has been built from a custom editor: the DIV element specialEditor. That's why we must specify the target type: type: 'editor'. This editor is composed of 2 fields which must be concatenated: hence the override of the function editFct. Otherwise, the function onupdate only put the surname in upper case and the first name is lower case.

Version

Version: 1.0 (5th March 2012)

Download: editableText-deploy.tar.gz

Author: Grégory Mantelet (CDS)

jquery_editabletext_ui.txt · Last modified: 2013/06/05 09:20 by administrator

Thanks for acknowledging the CDS developer’s resources (libraries, source code, etc.)

© UDS/CNRS

Contact