¡Que buena idea!

Introducción

Una de las maravillas que ofrece el AJAX es no tener que esperar a llenar todos los datos y darle a un botón de OK para tener un feed-back del servidor. Esta facilidad de Net2Client permite que se pueda buscar en cualquier campo por autocompletación, de forma muy similar a la búsqueda de campos enlaces, con la ventaja que puede ser utilizado para cualquier campo.

¿De qué se trata?

Ya teníamos una rutina de auto-completación por ajax (con los campos tipo enlace, llamados familiarmente "la lupa"), pero ahora existe una totalmente personalizable y utilizable para cualquier cosa que se te ocurra. Fuciona básicamente con dos funciones, Una en PHP y otra en Javascript. Vamos a empezar por PHP:

Control desde PHP

Para generar una caja de búsqueda sólo hay que incluir /rutinas/suggestbox.php, estando en ambiente N2C (desde versup, verextendido, o con ambienten2c.php, a partir de la versión 5.1.c). Esta contiene la rutina suggestBox() que se puede utilizar de la siguiente manera:

//--- Generar una caja simple con todos los valores por defecto -->
$htmlCaja = suggestBox("EVELink1_PER");
echo $htmlCaja;

 Para este ejemplo se ha uilitazado el ejemplo más sencillo posible e imprimirá una caja parecida a esta. El nombre "chávez" se está buscando en el campo "Nombre Cliente", este campo está inicializado por defecto en el campo Nombre de la tabla. La lista permite buscar por cualquier campo de la tabla. Sin embargo en los campos tipo enlace la búsqueda se realiza en base al código, no al nombre.

 

//--- Generar dos cajas del mismo enlace con todos los valores por defecto -->
$htmlCaja1 = suggestBox("EVELink1_PER", "madre");
$htmlCaja2 = suggestBox("EVELink1_PER", "padre");
 
echo $htmlCaja1;
echo $htmlCaja2;

El ejemplo anterior generó dos cajas de sugerencia para la misma tabla CON ID's DIFERENTES,  una con id madre y la otra con padre. Mejor se puede presenciar en el dibujo.

Para pasar pasar parámetros, se debe utilizar un arreglo, en este ejemplo llamado $param, como puede verse a continuación:

//--- Generar una caja con id y parámetros definidos -->

$param = array(

  "sizeInput" => 30,

  "sizeSelect" => 30,

  "fixedField" => true,

  "defaultField" => "Nombre",

  "anyPlace" => true,

  "returnFields" => "",

  "extraConditions" => "",

  "limit" => 20,

);

$htmlCaja = suggestBox("EVELink1_PER", "idCaja", $param);

echo $htmlCaja;

En el ejemplo de arriba se le ha especificado a la rutina el arreglo de parámetros con todas las opciones posibles. La siguiente tabla explica para que sirve cada uno y cuál es su valor por defecto si no se envía dentro del arreglo

Parámetro Descripción Valor por defecto
sizeInput Propiedad size del input type text en el que se escribe la palabra para buscar la sugerencia 30
sizeSelect Propiedad size del select que funciona como drop down con las sugerencias para la palabra escrita 30
fixedField Si no se quiere que se muestre el select para decidir el campo de búsqueda, sino que sea asumido. Cuando se indica un campo de búsqueda fijo, el campo de búsqueda es defaultField false

defaultField

 Es el campo de búsqueda seleccionado por defecto en el drop down. También es usado cuando se especifica fixedField = true "Nombre"
anyPlace Cuando está en true, busca en toda la palabra (LIKE '%needle%') pero cuando se especifica false, sólo se busca en el principio del campo LIKE 'needle%') true
returnFields Cuando se selecciona alguna sugerencia, se devuelven estos campos adicionales al Codigo en un arreglo a la funcion suggestBox(id).returnRow(row) ""
extraConditions Condiciones adicionales que debe cumplir la sugerencia para poder mostrarse. Puede ser PERCheckbox1=1, etc. La idea es que sólo se muestren los registros útiles. Estas condiciones también pueden ser modificadas desde javascript ""
limit Cantidad de sugerencias a mostrar 20

Otro ejemplo común es el de la hoja de tiempos. Su parámetro fixedField está en true y su parámetro defaultField está en ACTNombre

 

Control desde Javascript

Una vez que la página se cargó, es posible controlar todos los aspectos de la caja de sugerencias. Una clase de javascript fué diseñada para poder controlar todos los objetos de sugerencia que puedan haber en la página. cada conjunto de inputs y selects de sugerencias tienen su propio objeto de javascript que se obtiene de la siguiente manera:

<script>

//En este ejemplo se seleccionó el campo "[CAMPO]" y la id "[ID]"

suggestBox("[CAMPO][ID]");

//campo: "EVELink1_PER" id: ""

suggestBox("EVELink1_PER");

//campo: "EVELink1_PER" id: "padre"

suggestBox("EVELink1_PERpadre");

//campo: "EVELink1_PER" id: 1

suggestBox("EVELink1_PER1");

</script>

Para obtener el objeto se llama la función pasando de parámetro el nombre del campo concatenado con la id seleccionada. Si no existe una id, simplemente se escribe el nombre del campo.

Métodos

Una vez que se tiene el objeto que controla la manera de la que se muestran las sugerencias y los resultados, lo podemos manipular de acuerdo a nuestra necesidad. Para saber que se puede hacer, voy a describir los métodos que lo conforman:

<script>

//Se obtiene el objeto:

var LinkPER = suggestBox("EVELink1_PERpadre");

//Realizar una búsqueda de sugerencias con el texto escrito en el momento

LinkPER.performSearch();

//Método que altera las condiciones originales de búsqueda

LinkPER.alterConditions();

//Método que recibe los resultado de sugerencias del servidor

LinkPER.returnSearch();

//Método llamado al seleccionar algún elemento de la lista de sugerencias

LinkPER.selectSuggest();

//Método llamado para devolver el resultado de seleccionar alguna sugerencia.

LinkPER.returnRow(row);

</script>

Todos estos métodos son llamados automáticamente dependiendo de las acciones realizadas por la persona que esté usando la caja para seleccionar la sugerencia deseada. Casi todos los métodos pueden seguir funcionando sin modificaciones, pero es importante conocer returnRow.

returnRow

Este es el método que siempre va a tener que ser modificado para que el usuario decida que hacer con el resultado. El panorama es este:

  1. Una persona comienza a utilizar la caja de sugerencias.
  2. Cada vez que presiona una tecla, el objeto va buscando automáticamente las sugerencias.
  3. La persona se detiene a mirar las sugerencias y escoge algún resultado.
  4. Si hacen falta campos adicionales, se buscan al servidor y finalmente se llama LinkPER.returnRow(row);

Este es el caso que todos esperamos que suceda, ahora necesitamos el control del resultado para tomar la acción correspondiente. Y esto es lo que se puede hacer:

<script>

//Se obtiene el objeto:

var LinkPER = suggestBox("EVELink1_PERpadre");

//Se modifica el método actual de devolución de resultados

LinkPER.returnRow = function (row){

alert(row['PERCodigo']);
};

</script>

En cualquier momento, de hecho, preferiblemente al inicio de la página, podemos colocar esta instrucción. Esto va a modificar el método returnRow para esta caja de búsqueda específica y cada vez que el usuario seleccione un resultado, la nueva función del usuario es la que se va a llamar, generando así un alert con el código del cliente (para este ejemplo.

Esto que acabamos de hacer se puede hacer de igual manera con el resto de los métodos del objeto de sugerencias, pero es preferible no modificar ningún otro ya que todos dependen entre sí, a exepción de este y alterConditions.

<script>

//Se obtiene el objeto:

var LinkPER = suggestBox("EVELink1_PERpadre");

//Se modifica el método actual de devolución de resultados

LinkPER.alterConditions = function (conditions){



  return conditions + ' AND PERCheckbox1=1';

};

</script>

El método anterior funciona recibiendo las condiciones originales que genrealmente se ven igual que esta: "PERNombre LIKE '%alejandro%'" y se modifican. Estas nuevas condiciones modificadas se devuelven y se utilizan posteriormente para obtener los resultados. En el ejemplo anterior vemos como por ejemplo se están buscando todos los que tengan alejandro en el nombre, pero que también tienen que estar activos (por ejemplo si PERCheckbox1 significa activo.

Notas importantes:

  • De los métodos de javascript del objeto de control de sugerencias, sólo es obligatorio modificar returnRow ya que es el que le permite obtener el resultado al usuario.
  • Para ponerlo a funcionar hace falta usar:
    1. /rutinas/suggestbox.php en php
    2. /rutinas/suggestbox.js en javascript
    3. /rutinas/jquery.js en javascript
  • Requiere un login iniciado, no funcionaría sin COKO.

Ejemplo

Lo más seguro es que ya hayan utilizado la 701 para ingresar tiempos. Tomaremos este ejemplo de esa aplicación:

for ($i = 1; $i <= $CantidadFilas; $i++){
    $suggestBoxes .= "
    ActSuggest$i = suggestBox('AR5Link1_ACP$i');
    ActSuggest$i.returnRow = function(row){
        document.seg.AR5Link1_ACP_$i.value = row['ACPCodigo'];
    }";
};

Como puede verse, aquí se están creando varias lineas (for $i). Para cada línea se está llamando