BufferOverflow

AutoSuggest es un plugin para jQuery que nos permite convertir fácilmente cualquier INPUT de texto en una caja con auto-completado. La misma se crea con una estructura HTML totalmente limpia y sin utilizar imágenes, lo que permite la fácil personalización visual con CSS. El plugin tiene un peso de apenas 9,6KiB.

Para utilizarlo, incluimos jQuery (en mi caso siempre lo cargo desde Google) y el plugin.

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js" type="text/javascript"></script>
<script src="../scripts/jquery.autoSuggest.minified.js" type="text/javascript"></script>

Se puede utilizar de la siguiente manera:

<script type="text/javascript">
$(function(){
    $("#auto").autoSuggest(data);
});
</script>

Donde #auto es el INPUT que queremos utilizar y data son las sugerencias, estas pueden ser obtenidas desde un array incluido en el mismo script (sin hacer una llamada ajax) o desde una URL (utilizando ajax). Veamos como un ejemplo utilizando un array dentro del mismo script:

<script type="text/javascript">
 data = {items: [
    {value: "Mick Jagger"},
    {value: "Johnny Storm"},
    {value: "Richard Hatch"},
    {value: "Kelly Slater"},
    {value: "Rudy Hamilton"},
    {value: "Michael Jordan"}
]};
$("#auto").autoSuggest(data.items);
</script>

O haciendo una peticion ajax:

<script type="text/javascript">
$("#auto").autoSuggest("auto.php");
</script>

Donde el script PHP puede ser algo como esto:

<?PHP
    $input = $_GET["q"];
    $data = array();
    // query your DataBase here looking for a match to $input
    $query = mysql_query("SELECT * FROM my_table WHERE my_field LIKE '%$input%'");
    while ($row = mysql_fetch_assoc($query)) {
        $json = array();
        $json['value'] = $row['id'];
        $json['name'] = $row['username'];
        $json['image'] = $row['user_photo'];
        $data[] = $json;
    }
    header("Content-type: application/json");
    echo json_encode($data);
?>

Cuando se van seleccionando las opciones, estas se guardan en un campo oculto separadas por coma. El name del campo oculto es as_values_ seguido del string que especifiquemos nosotros con la opcion asHtmlID. Por ej, si queremos que el name sea as_values_nombres:

<script type="text/javascript">
$("#auto").autoSuggest("auto.php", {asHtmlID: "nombres"});
</script>

Luego con PHP usamos:

$_POST['as_values_nombres'];

Tenemos algunas opciones mas:

selectionLimit: numero (Valor por defecto: Sin limite) Especifica la cantidad máxima de items que se pueden seleccionar, por ej si queremos que solo se puedan seleccionar 3 items:

<script type="text/javascript">
$("#auto").autoSuggest("auto.php", {asHtmlID: "nombres", selectionLimit: 3});
</script>

limitText: string (Valor por defecto: “No More Selections Are Allowed”) Texto que se muestra cuando se alcanza el limite especificado con selectionLimit.
emptyText: string (Valor por defecto: “No Results”) Texto que se muestra al no encontrar coincidencias
selectedItemProp:string (Valor por defecto: “value”) El nombre de la propiedad del objeto que se va a usar para mostrar.
selectedValuesProp:string (Valor por defecto: “value”) El nombre de la propiedad del objeto que se va a guardar en el campo oculto.
searchObjProps:string (Valor por defecto: “value”) El nombre de la propiedad del objeto que se va a usar para la busqueda. Si se quieren usar varias opciones se las puede separar con coma.
El uso de las tres opciones anteriores puede ser algo confuso, pero puede ser mas facil entenderlo con el siguiente ejemplo:

<script type="text/javascript">
var data = {items: [
    {value: "21", name: "Mick Jagger", searchname: "Mick Jagger, Mick Jager"},
    {value: "43", name: "Johnny Storm", searchname: "Johnny Storm"},
    {value: "46", name: "Richard Hatch", searchname: "Richard Hatch"},
    {value: "54", name: "Kelly Slater", searchname: "Kelly Slater"},
    {value: "55", name: "Rudy Hamilton", searchname: "Rudy Hamilton"},
    {value: "79", name: "Michael Jordan", searchname: "Michael Jordan"}
]};
$("#auto").autoSuggest("auto.php", {selectedValuesProp: "value", selectedItemProp: "name", searchObjProps: "searchname"});
</script>

De esa forma value se guardara en el campo oculto y sera enviado con el formulario (Si se selecciona a Mick Jagger y a Kelly Slater, entonces lo que se enviará con el formulario será: “21, 54″), name se mostrará al usuario y searchname se usará para buscar coincidencias con el texto ingresado.

startText: string (Valor por defecto: “Enter Name Here”) Texto a mostrar cuando el campo de texto esta vacío.
preFill: objeto o string (Valor por defecto: Objeto vacío) Opciones ya seleccionadas cuando se carga la pagina. Se le puede pasar un string con las opciones separadas por coma o un objeto.
queryParam: string (Valor por defecto: “q”) Nombre del parámetro que se va a usar para la petición ajax. auto.php?q=
retrieveLimit: numero (Vacío por defecto) Puede ser usado para especificar un limite en el query ajax ya que agrega un &limit= en el mismo.
extraParams: string (Vacío por defecto) Sirve para especificar cualquier otro parámetro en la petición ajax. En el caso de que sean varios, recordá seprarlos con un andpersand (&).
matchCase: true o false (Valor por defecto: false)  hace que la busqueda sea case sensitive en caso de ser true.
minChars: numero (Valor por defecto: 1)  Cantidad de caracteres que son necesarios para que comience la busqueda.
keyDelay: numero (Valor por defecto: 400) Tiempo de espera en milisegundos antes de que comience la búsqueda. El valor por defecto es 400.
showResultList: true o false (Valor por defecto: true) Si se establece en false, la lista desplegable con las opciones nunca se mostrará.
start: Permite establecer una función personalizada que se activa al ejecutar AutoSuggest (en la mayoria de los casos, al cargar la pagina).
selectionClick: Permite establecer una funcion personalizada que se activa cuando se hace click sobre una opcion ya haya sido seleccionada previamente.
selectionAdded: Permite establecer una funcion personlizada que se activa cuando se selecciona una opción de la lista.
selectionRemoved: Permite establecer una función personalizada que se activa cuando se elimina una opción ya seleccionada. Tal vez un efecto fadeout en el elemento eliminado.
beforeRetrieve: Funcion que se aplica antes de comenzar a buscar. Se puede usar por ej, para mostrar un gif “loading” mientras se hace la peticion ajax.
retrieveComplete: Funcion que se ejecuta cuando se termina de buscar. Se puede usar para ocultar el gif antes mencionado.
resultClick: Funcion que se ejecuta al hacer click sobre alguna de las opciones de la lista desplegable.
resultsComplete: Permite especificar una funcion personalizada a ejecutarse una vez desplegada la lista de resultados.