Introduction

SmartTextBox is a jQuery plugin that turns text inputs into javascript driven widget that allow navigating the options using keyboard, auto completion and many other features, while being fully customizable. The plugin is inspired by  Guillermo Rauch’s TextBoxList, at the time his plugin was only available on mootools. The plugin was originally supposed to be used only on internal projects, but as time passed, I decided to clean it up and to publish it in jQuery plugin’s list.

Current version

The current version of SmartTextBox is 1.2.0-rc1

Demo

A demo page of the most common usages of the SmartTextBox plugin is available here.

Sources

The sources are availables in the WOPU project, hosted by googlecode, there

Download

The plugin is downloadable here. For direct download of the lastest version just click there.

Requirements

SmartTextBox required jQuery 1.2 or higher.

Installation

Just download the plugin, be sure you already have jQuery included on your pages, copy the files, then simply add in the headers :

<link charset="utf-8" media="screen" type="text/css" href="/path/to/smarttextbox/SmartTextBox.css" rel="stylesheet"/>
<script charset="utf-8" type="text/javascript" src="/path/to/smarttextbox/SmartTextBox.js"></script>

License

SmartTextBox comes under the GPL license.

Browsers support

SmartTextBox supports all major browser (IE6/7/8, FF2/3, Chrome, Safari, Opera)

Usage

SmartTextBox follows the jQuery principles in terms of usage and accessibility. Creating a SmartTextBox from an input is very easy :

$("#myInput").smartTextBox();

SmartTextBox is fully customizable, and options can be passed as follow :

$("#myInput").smartTextBox({submitKeys : [13], autocomplete : true, separator : ";"});

Options

Here is the list of options usable when creating a SmartTextBox :

Events

SmartTextBox also allow the wiring of custom user events. All events handlers are fired with 2 parameters : the first is the element triggering the event, the second is the SmartTextBox object which the element is attached to. The events are customizable by the following keys in the options :

API

Once created, the SmartTextBox API calls can be accessed through the $(“#myInput”).smartTextBox method :

$(el).smartTextBox("add","a label")

$(el).smartTextBox("remove",labelOrIndex)

$(el).smartTextBox("load", values)

$(el).smartTextBox("clear")

$(el).smartTextBox("autocomplete", values)

Changelog

1.2.0-rc1 – 2010-08-14

• New features

- new ‘autocompleteUrl’ option : can now load list of autocomplete values from an json ajax call (one time values load)

- new ‘onlyAutocomplete’ option (default to false). When set to true, The SmartTextBox will only accept labels added from the autocompletion list.

- new ‘uniqueValues’ option (default to true). When set to true, the SmartTextBox will only accept the labels once (that mean a label cannot be added more than once). Also, when this mode is active, the autocompletion will not propose already-added labels.

- autocompletion search mode can now be choosen between ‘start of word’ and ‘full text search’ ( see the ‘fullSearch’ option )

• Changes

- major change in the autocomplete configuration : autocompleteOptions map has been remove. Now autocomplete configuration is made directly in the SmartTextBox options map.

This cause the following options rename :

- minLength renamed to minSearchLength

• Bug fixes

- deleting elements using keyboard now correctly focus previous or next element.

- autocomplete options are now correctly passed to autocomplete instance at SmartTextBox initialization.

- autocomplete results are now correctly highlighted.

1.1.2 – 2010-08-12

• Bug fixes

- backspace key now works back as intended when typing text in boxes

1.1.1 – 2010-08-12

• Bug fixes

- fix plugin for IE6 ( stupid comma… )

- use of backspace key to delete boxes now longer cause the browser to go to last page

1.1 – 2010-08-03

• New features

- added custom event wiring capability

• API Changes

- the method “values” renamed to “load”

• Bug fixes

- the API methods “load” and “autocomplete” can now work with lists as intended

- the API method “remove” can now work with an index as intended

1.0 – 2010-08-02

- Initial public release.

Dans ce tutorial, j’expliquerai comment créer une méthode gérant un argument optionnel, puis une autre pouvant recevoir un nombre variable d’argument.

Arguments optionnels

Mettont que nous ayons besoin de trier une liste. Pour ce faire, nous créons une méthode qui s’occupe de trier la liste, puis de la retourner ( dans l’exemple, la fonction fait juste appel à la méthode sort de la liste, mais on imagine la déclaration d’une vrai méthode de tri puis de son exécution )

On obtientrait donc quelque chose de ce type :

mySort = function(l){
    l.sort();
    return l;
};
>>> mySort([4,2,3]);
[2,3,4]

Cependant, plus tard lors de notre développement, apparait un autre besoin : il faudrait pouvoir trier la liste, mais en sens inverse cette fois-ci.

Plusieurs solutions apparaissent alors :

La premiere serait de séparer les deux étapes, en effectuant d’abord l’appel à mySort(), puis ensuite à myReverse() par exemple ( qui, ferait d’ailleurs simplement return l.reverse() dans cet exemple très basique ). Mais cela allourdirait le code.

La seconde est de rajouter un second paramètre à mySort, pour spécifier l’ordre dans lequel on veut trier la liste.
On obtiendrait alors quelque chose de ce genre :

mySort = function(l, order){
    l.sort();
    if(order=="reverse") l.reverse();
    return l;
};
>>> mySort([2,4,3], "normal")
[2,3,4]
>>> mySort([2,4,3], "reverse")
[4,3,2]

On observe effectivemment qu’en fonction du second paramètre ( “normal” ou “reverse” ), le sens du tri est, ou non, inversé.

Seulement voila, cela oblige à passer un second parametre à chaque appel de sa méthode. Paramètre au final inutile si on veut trier la liste ‘simplement’, sans l’inverser.

Et bien en fait (oh surprise!) non.

En effet, une astuce trop peu connue des débutants est l’utilisation de paramètres optionnels. Un paramètre contenu dans la déclaration d’une méthode et non envoyé lors de l’appel de cette dernière ne pose,en fait, pas de problème. La variable est simplement considérée comme étant à la valeur null.

exemple :

f = function(a){
    return a
}
>>> f(2)
2
>>> f()
null

On constate qu’effectivemment, quand le paramètre ‘a’ n’est pas envoyé à la fonction ‘f’, ‘a’ est quand meme défini, et a la valeur null, dans le corps de la fonction. En exploitant cela, on peut modifier notre méthode de tri pour obtenir la suivante :

mySort = function(l, reverse){
    l.sort();
    if(reverse) l.reverse();
    return l;
};
>>> mySort([2,4,3])
[2,3,4]
>>> mySort([2,4,3], "reverse")
[4,3,2]

A noter qu’ici, la variable reverse est utilisé comme un flag : dans l’exemple on lui donne la valeur “reverse”, mais un simple “true” aurait suffit ( même si “reverse” aide à la lisibilitée du code )

Utilisation de la variable argument

Au passage, une autre astuce (un peu plus avancée celle la) concernant les arguments en javascript : dans une fonction, la variable ‘arguments’ contient la liste des arguments qui ont été passés.

Très simplement :

myTest2 = function(){
    return arguments;
};
>>> myTest2()
null
>>> myTest2(1,2,3)
[1,2,3]

Et cela marche quelque soient les arguments ‘normallement’ définis :

myTest2 = function(a,b){
    return arguments;
};
>>> myTest2()
null
>>> myTest2(1,2,3)
[1,2,3]

Arguments est une liste tout ce qu’il y a de plus classique : on peut connaitre sa taille avec arguments.length, et on recupère un élement avec arguments[position].

Concretement, cela permet d’envoyer un nombre variable de paramètres.

Par exemple, on peut envisager une fonction qui additionne un nombre quelconque de variables.

Additionner = function(){
    var sum = 0;
    for(var i=0; i < arguments.length; i++){
        sum += arguments[i];
    }
    return sum;
};
>>> Additionner()
0
>>> Additionner(1,2)
3
>>> Additionner(1,2,3)
6
>>> Additionner(1,2,3,6,12,48)
72

On constate bien qu’on peut passer un nombre variable de paramètres, et que le résultat de la méthode est la somme de tous.

En recherchant sur google, on tombe vite sur ce qui semble être la solution au problème : en effet, javascript dispose d’une méthode typeof, retournant une string identifiant le type de l’élément.

exemples :

>>> typeof 1
"number"
>>> typeof "hello"
"string"

Jusque la, tout va bien. Cependant, les surprises arrivent dès qu’on pousse les tests un peu plus :

>>> typeof [1,2,3]
"object"

Tiens, il considère ma liste comme un objet !

>>> typeof new Date()
"object"

Et les dates aussi !

>>> typeof null
"object"

Même null est considéré comme étant du type object…

En effet, l’opérateur typeof n’identifie que les types suivants :

"number"
"string"
"function"
"boolean"
"object"

Dans la pratique, on a besoin de pouvoir faire la différence entre une liste et un objet, ou de savoir si un paramètre est une date, ou si le retour d’une méthode est une erreur, par exemple.

La solution consiste donc à bricoler sa propre méthode typeof, pour avoir une identification plus précise des variables. Concrètement, pour identifier un type, on va chercher une bidouille sur la variable à chaque fois.

Par exemple :

Pour les dates c’est très simple, on regarde si le constructeur est bien ‘Date’.

if( var.constructor==Date) // it's a date.

Pour les listes, on pourrait faire pareil ( regarder si le constructeur est bien ‘Array’ ), cependant cela peut poser problème dans certains cas. les selecteurs jQuery, par exemple, sont des listes (on peut faire selecteur[0]), mais sont crées à partir du constructeur object.
Pour les identifier, on vérifie donc à la place la présence d’un attribut ‘length’ sur la variable testée

if (el.length) // it's a list

Pour null, on fait juste un test avec la variable null !

if (var==null) // it's null !

Il reste deux autres pseudotypes, moins utilisés, mais qu’il peut être tout de même utile de dissocier :

Les erreurs (utile en cas de retour dans un catch par exemple)
La classe erreur est spécifique au navigateur (evidemment), cependant, sous tous, elle dispose toujours de deux attributs : ‘message’ et ‘name’. On verifie donc la présence de ces deux attributs, et pour bien faire, on vérifie bien la présence de “Error” dans l’attribut nom.

if(el.message!=null && el.name!=null && el.name.search("Error")>-1) return 'error';

Et pour finir, les noeuds DOM. La aussi, c’est de la bidouille : on verifie l’existence d’un attribut nodeName ou tagName sur la variable.

if(el.nodeName || el.tagName) return 'node'; // it's a node

Ce qui donne la méthode suivante :

/**
* Return 'advanced' type for an element
* Type can be of :
*  - 'null'
*  - 'string'
*  - 'number'
*  - 'boolean'
*  - 'function'
*  - 'list'
*  - 'node'
*  - 'date'
*  - 'error'
*  - 'object'
* @param el
**/
typeOf = function(el){
var elType = typeof el;

// null type
if(el==null) return 'null';

// basic types : number, string, function
if(elType=='number'||elType=='string'||elType=='function'||elType=='boolean')
    return elType;

// date
if(el.constructor==Date) return "date";

// domElem
if(el.nodeName || el.tagName) return 'node';

// list
if(el.length) return 'list';

// error
if(el.message!=null && el.name!=null && el.name.search("Error")>-1) return 'error';

// object
return 'object';
}

Et voila, une fonction typeOf qu’elle est mieux que l’originale !

>>> typeOf([1,2,3])
'list'
>>> typeOf(null)
'null'
>>> typeOf(document.body)
'node'
>>> typeOf(new Date())
'date'

Et les type originels sont identifiés aussi :

>>> typeOf(1)
'number'
>>> typeOf('hello')
'string'
>>> typeOf(String)
'function'
>>> typeOf(true)
'boolean'

Voila, comment gagner pas mal de temps sur les verifs avec une méthode de 10 lignes !