Componente Datepicker de jQuery UI

Una de las interfaces de usuario más solicitadas y también de las más útiles, es un calendario para seleccionar una fecha. Este calendario permite que las personas puedan escoger una fecha a golpe de ratón y de manera visual, sin tener que escribir la fecha. Sin lugar a dudas el visitante agradecerá la comodidad de seleccionar la fecha por medio de este componente, pero también existen otras ventajas, como no obligarle a conocer el formato de fecha que necesitamos para una correcta entrada de datos.

En el artículo anterior ya estuvimos explicando las generalidades de las jQuery UI, por lo que se recomendaría su lectura, ya que contiene algunas guías que serán necesarias para aprender a utilizar cualquier tipo de componente y que vamos a dar por sabidas en el presente texto. Conviene leer por tanto el artículo Primeros pasos con jQuerty UI y la continuación Empezar a usar jQuery UI.

Entender la documentación de los componentes jQuery UI

Todos los componentes que nos ofrecen en jQuery UI los podemos encontrar correctamente documentados en la página de jQuery UI, a través de la sección de demos y documentación. En las páginas de demos encontraremos varios casos de uso de los componentes y también la documentación para hacerlos funcionar, léase, las opciones de configuración que ponen a nuestra disposición, así como los métodos de los objetos, eventos, etc.

De paso que explicamos cómo utilizar este calendario para seleccionar fechas queremos explicar también las cosas que podremos encontrar en la documentación de los componentes en general, así cualquier persona podrá continuar a partir de aquí, ya sea pasando a usos más avanzados del calendario o de otros componentes de jQuery UI. Así pues, conviene echar un vistazo a la página del demo y documentación del Datepicker, para revisar las informaciones que nos encontramos.

En la documentación es especialmente ilustrador el apartado de ejemplos, que contiene varios casos de uso para cada componente y para distintas opciones de configuración habituales. Por ejemplo, para la documentación del calendario podremos ver versiones con distintos formatos, idiomas, mostrando el número de la semana en el año, cambios en la animación, ver más de un mes al mismo tiempo, restricción de fechas para seleccionar sólo un rango permitido, etc. Nosotros nos centraremos en mostrar cómo localizar el calendario para que esté escrito en español y las fechas también tengan el formato dd/mm/aa, además veremos cómo colocar algunas opciones de configuración para mostrar un icono al lado del campo de texto, que una vez pulsado salga el calendario y otras cosas.

Un poco más abajo de los demos de uso de cada componente encontraremos también la documentación que mostrará el listado completo de opciones de configuración, los eventos que permite el componente, funciones especiales o métodos que podemos invocar sobre el mismo, etc. Conviene leer con calma apartado "Overview", que tiene informaciones generales y luego utilizar la completa referencia de opciones de configuración del apartado "Options", así como los eventos y demás.

Definir variables de configuración para el seleccionador de fechas

En el anterior artículo de primeros pasos en jQuery UI ya mostramos cómo cargar un componente de las librerías y vimos el ejemplo concreto con el Datepicker, así que algo ya sabes sobre generar este sistema. En concreto necesitábamos un campo de texto INPUT.

<input type="text" name="fecha" id="campofecha">

Luego invocábamos al Datepicker sobre el campo de texto, con una llamada al método datepicker() sobre el objeto jQuery del elemento campo de texto.

$("#campofecha").datepicker();

Pues bien, para definir variables de configuración de este componente, podemos enviarlas a partir de la llamada al método datepicker(), enviando en notación de objeto todas las preferencias de configuración que deseemos aplicarle.

$("#campofecha").datepicker({
   showOn: 'both',
   buttonImage: 'calendar.png',
   buttonImageOnly: true,
   changeYear: true,
   numberOfMonths: 2,
   onSelect: function(textoFecha, objDatepicker){
      $("#mensaje").html("<p>Has seleccionado: " + textoFecha + "</p>");
   }
});

Con este listado de variables estamos configurando diversas cosas del elemento para seleccionar fechas, las siguientes:

• showOn: define que el calendario se muestre al hacer focus en el campo de texto o al pulsar el botón para abrir el calendario.
• buttonImage: permite definir la URL de una imagen para utilizarla como botón de abrir calendario.
• buttonImageOnly: para que sólo aparezca la imagen como botón.
• changeYear: para que haya un campo select con el que cambiar el año actual del calendario.
• numberOfMonths: para que se vean varios meses a la vez en varios calendarios.
• onSelect: un evento que se produce cuando el usuario selecciona una fecha.

De todas las variables de configuración anteriores, en las que sólo estamos viendo unas pocas de las que permite el componente, es especialmente interesante el tema del evento onSelect. Al definir un evento podemos realizar acciones Javascript para realizar cosas cuando se produce. Imaginaros que al seleccionar una fecha queréis comprobar cualquier cosa, pues por medio del evento onSelect podríais realizar cualquier tipo de función para ello. Entre los eventos tenemos otros interesantes como onChangeMonthYear, beforeShow, onClose, etc.

Otra cosa importante es que todas las variables de configuración se pueden cargar o bien al instanciar el componente o bien una vez ya está creado el datepicker con el método datepicker(), pasando como primer parámetro la cadena "option", un segundo parámetro con el nombre de la variable a cambiar y un tercero con el valor.

$("#campofecha").datepicker( "option", "changeMonth", true );

Con esa sentencia hacemos que el calendario tenga un select para cambiar rápidamente el mes. (Mirar el ejemplo del final del artículo para más información)

Localización del calendario jQuery UI

Una de las cosas más importantes para nuestro calendario es que esté en español, no sólo por los nombres de mes o de la semana, sino también por el formato de la fecha escrito en el campo de texto una vez seleccionamos un día del calendario.

Para localizar el calendario tenemos que cargar una serie de datos en las opciones del calendario, como los nombres de los días de la semana, de los meses y el formato de nuestra fecha. Todos estos datos podríamos construirlos por nosotros mismos, pero en jQuery han puesto a nuestra disposición un listado de archivos de configuración por idiomas.

La lista de localizaciones disponibles está en http://jquery-ui.googlecode.com/svn/trunk/ui/i18n/

Aunque, como decíamos, si no encuentras tu localización, la puedes crear. Para crear la localización tendríamos que definir variables de configuración como monthNamesShort, dayNames, dayNamesShort, dayNamesMin, weekHeader, etc. El código sería como este, para el idioma español.

/* Inicialización en español para la extensión 'UI date picker' para jQuery. */
/* Traducido por Vester (xvester [en] gmail [punto] com). */
jQuery(function($){
   $.datepicker.regional['es'] = {
      closeText: 'Cerrar',
      prevText: '<Ant',
      nextText: 'Sig>',
      currentText: 'Hoy',
      monthNames: ['Enero', 'Febrero', 'Marzo', 'Abril', 'Mayo', 'Junio', 'Julio', 'Agosto', 'Septiembre', 'Octubre', 'Noviembre', 'Diciembre'],
      monthNamesShort: ['Ene','Feb','Mar','Abr', 'May','Jun','Jul','Ago','Sep', 'Oct','Nov','Dic'],
      dayNames: ['Domingo', 'Lunes', 'Martes', 'Miércoles', 'Jueves', 'Viernes', 'Sábado'],
      dayNamesShort: ['Dom','Lun','Mar','Mié','Juv','Vie','Sáb'],
      dayNamesMin: ['Do','Lu','Ma','Mi','Ju','Vi','Sá'],
      weekHeader: 'Sm',
      dateFormat: 'dd/mm/yy',
      firstDay: 1,
      isRTL: false,
      showMonthAfterYear: false,
      yearSuffix: ''};
   $.datepicker.setDefaults($.datepicker.regional['es']);
});

Como se puede ver, se definen unos valores en un objeto $.datepicker.regional['es'] y luego se asigna a todos los calendarios de la página por medio de $.datepicker.setDefaults().

En general es código lo podemos colocar en cualquier sitio o bien copiarlo en un archivo a parte, como por ejemplo jquery.ui.datepicker-es.js e incluirlo con la etiqueta SCRIPT:

<script type="text/javascript" src="js/jquery.ui.datepicker-es.js"></script>

Ejemplo completo de calendario Datepicker en jQuery UI

Para acabar podemos ver un ejemplo de calendario que tiene varias de las cosas que hemos visto en este artículo.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd"
>
<html lang="es">
<head>
<title>Seleccionar fecha con jQuery UI</title>
   <link type="text/css" href="css/le-frog/jquery-ui-1.8.1.custom.css" rel="Stylesheet" />   
   <script type="text/javascript" src="../../jquery-1.4.2.min.js"></script>
   <script type="text/javascript" src="js/jquery-ui-1.8.1.custom.min.js"></script>
   <script type="text/javascript" src="js/jquery.ui.datepicker-es.js"></script>
<script>
$(document).ready(function(){
   $("#campofecha").datepicker({
      showOn: 'both',
      buttonImage: 'calendar.png',
      buttonImageOnly: true,
      changeYear: true,
      numberOfMonths: 2,
      onSelect: function(textoFecha, objDatepicker){
         $("#mensaje").html("<p>Has seleccionado: " + textoFecha + "</p>");
      }
   });
})
</script>
</head>
<body>

<form>
   Fecha: <input type="text" name="fecha" id="campofecha">
</form>

<div id="mensaje"></div>


<a href="#" id="cambiames">Mostrar formulario para cambiar mes</a>
<script>
$(document).ready(function(){
   $("#cambiames").click(function(){
      $("#campofecha").datepicker( "option", "changeMonth", true );
   });
});
</script>

</body>
</html>

Podemos ver el ejemplo en marcha en una página aparte.

Lo cierto es que, cuando investigamos un poco este Datepicker, podemos ver que es un componente magnífico, con todas las opciones de configuración y personalización que podamos necesitar. Hablar de todas ellas y presentar ejemplos sería material para un manual entero, por ello, para usos más complejos recomendamos explorar la documentación de jQuery UI, porque probablemente haya alguna cosa que nos haga falta saber y que no hemos explicado en este artículo.