Componente Datepicker de jQuery UI

Um componente de interfaces de usuário em jQuery UI que serve para mostrar um calendário com o qual selecionar uma data de maneira visual.

Por Miguel Angel Alvarez - Tradução de Celeste Veiga


Publicado em: 15/6/13
Valorize este artigo:
Uma das interfaces de usuário mais solicitadas e também das mais úteis, é um calendário para selecionar uma data. Este calendário permite que as pessoas possam escolher uma data com o mouse e de maneira visual, sem ter que escrever a data. Sem dúvida o visitante agradecerá a comodidade de selecionar a data por meio deste componente, mas também existem outras vantagens, como não obrigar a conhecer o formato de data que necessitamos para uma correta entrada de dados.

No artigo anterior já estivemos explicando as generalidades das jQuery UI, razão pela qual se recomendaria sua leitura, já que contém algumas guias que serão necessárias para aprender a utilizar qualquer tipo de componente e que vamos dar por sabida no presente texto. Convém ler por tanto o artigo Primeiros passos com jQuerty UI e a continuação Começar a usar jQuery UI.

Entender a documentação dos componentes jQuery UI

Todos os componentes oferecidos em jQuery UI podem ser encontrados corretamente documentados na página de jQuery UI, através da seção de demos e documentação. Nas páginas de demos encontraremos vários casos de uso dos componentes e também a documentação para fazê-los funcionar, entenda-se, as opções de configuração que colocam à nossa disposição , bem como os métodos dos objetos, eventos, etc.

Aproveitando que explicamos como utilizar este calendário para selecionar datas, queremos explicar também as coisas que poderemos encontrar na documentação dos componentes em geral, assim qualquer pessoa poderá continuar a partir daqui, seja passando a usos mais avançados do calendário ou a outros componentes de jQuery UI. Desse modo, convém dar uma olhada na página do demo e documentação do Datepicker, para revisar as informações que encontramos.

Na documentação é especialmente ilustrador a parte de exemplos, que possui vários casos de uso para cada componente e para distintas opções de configuração habituais. Por exemplo, para a documentação do calendário poderemos ver versões com diferentes formatos, idiomas, mostrando o número da semana no ano, mudanças na animação, ver mais de um mês ao mesmo tempo, restrição de datas para selecionar só uma classe permitida, etc. Nós nos centraremos em mostrar como localizar o calendário para que esteja escrito em espanhol e as datas também tenham o formato dd/mm/aa, ademais veremos como colocar algumas opções de configuração para mostrar um ícone ao lado do campo de texto, que uma vez pressionado saia o calendário e outras coisas.

Um pouco mais abaixo dos demos de uso de cada componente encontraremos também a documentação que mostrará a listagem completa de opções de configuração, os eventos que permite o componente, funções especiais ou métodos que podemos invocar sobre ele, etc. Convém ler com calma a seção "Overview", que tem informações gerais e depois utilizar a completa referencia de opções de configuração da seção "Options", assim como os eventos e demais.

Nota: É claro que os exemplos são úteis, pois nos mostrarão casos de uso simples sobre os componentes, que poderemos utilizar para nos guiarmos nos primeiros passos com esse componente. Porém, no momento que queiramos complicar um pouco as coisas vamos ter que revisar com calma a documentação, pois nela encontraremos todas as referencias sobre cada componente com detalhes.

Definir variáveis de configuração para o selecionador de datas

No artigo anterior de primeiros passos em jQuery UI já mostramos como carregar um componente das bibliotecas e vimos o exemplo concreto com o Datepicker, de modo que você já sabe algo sobre gerar este sistema. Especificamente necessitávamos um campo de texto INPUT.

<input type="text" name="data" id="campodata">

A seguir invocávamos o Datepicker sobre o campo de texto, com uma chamada ao método datepicker() sobre o objeto jQuery do elemento campo de texto.

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

Pois bem, para definir variáveis de configuração deste componente, podemos enviá-las a partir da chamada ao método datepicker(), enviando em notação de objeto todas as preferências de configuração que desejemos aplicar.

$("#campodata").datepicker({
   showOn: 'both',
   buttonImage: 'calendar.png',
   buttonImageOnly: true,
   changeYear: true,
   numberOfMonths: 2,
   onSelect: function(textoData, objDatepicker){
      $("#mensagem").html("<p>Voce selecionou: " + textoData + "</p>");
   }
});

Com esta listagem de variáveis estamos configurando diversas coisas do elemento para selecionar datas, as seguintes:

  • showOn: define que o calendário seja mostrado ao fazer focus no campo de texto ou ao pressionar o botão para abrir o calendário.
  • buttonImage: permite definir a URL de uma imagem para utilizá-la como botão de abrir calendário.
  • buttonImageOnly: para que só apareça a imagem como botão.
  • changeYear: para que haja um campo select com o qual mudar o ano atual do calendário.
  • numberOfMonths: para que se vejam vários meses simultaneamente em vários calendários.
  • onSelect: um evento que se produz quando o usuário seleciona uma data.
De todas as variáveis de configuração anteriores, das que só estamos vendo umas poucas das que permite o componente, é especialmente interessante o tema do evento onSelect. Ao definir um evento podemos realizar ações Javascript para realizar coisas quando seja produzido. Imaginem que ao selecionar uma data vocês querem comprovar qualquer coisa, pois por meio do evento onSelect vocês poderão realizar qualquer tipo de função para isso. Entre os eventos temos outros interessantes como onChangeMonthYear, beforeShow, onClose, etc.

Outra coisa importante é que todas as variáveis de configuração podem ser carregadas ou ao instanciar o componente ou uma vez já esteja criado o datepicker com o método datepicker(), passando como primeiro parâmetro a cadeia "option", um segundo parâmetro com o nome da variável a ser mudada e um terceiro com o valor.

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

Com essa sentença fazemos com que o calendário tenha um select para mudar rapidamente o mês. (Olhe o exemplo do final do artigo para mais informação)

Localização do calendário jQuery UI

Uma das coisas mais importantes para nosso calendário é que esteja em espanhol, não só pelos nomes de mês ou da semana, mas também pelo formato da data escrito no campo de texto uma vez tenhamos selecionado um dia do calendário.

Para localizar o calendário temos que carregar uma serie de dados nas opções do calendário, como os nomes dos dias da semana, dos meses e o formato de nossa data. Poderíamos construir estes dados nós mesmos, mas em jQuery colocaram à nossa disposição uma listagem de arquivos de configuração por idiomas.

A lista de localizações disponíveis está em http://jquery-ui.googlecode.com/svn/trunk/ui/i18n/

Embora, como dizíamos, se você não encontrar sua localização, poderá criá-la. Para criar a localização teríamos que definir variáveis de configuração como monthNamesShort, dayNames, dayNamesShort, dayNamesMin, weekHeader, etc. O código seria como este, para o idioma espanhol.

/* Inicialização em espanhol para a extensão 'UI date picker' para jQuery. */
/* Traduzido por Vester (xvester [em] gmail [ponto] 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', 'Deciembre'],
      monthNamesShort: ['Ene','Feb','Mar','Abr', 'May','Jun','Jul','Ago','Sep', 'Oct','Nov','Dic'],
      dayNames: ['Domingo', 'Lunes', 'Martes', 'Miéercoles', 'Jueves', 'Viernes', 'Sábado'],
      dayNamesShort: ['Dom','Lun','Mar','Mié','Jue','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 pode ver, se definem alguns valores em um objeto $.datepicker.regional['es'] e depois se atribuem a todos os calendários da página por meio de $.datepicker.setDefaults().

Em geral podemos colocar o código em qualquer lugar ou então copiá-lo em um arquivo à parte, como por exemplo jquery.ui.datepicker-es.js e incluí-lo com a etiqueta SCRIPT:

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

Exemplo completo de calendário Datepicker em jQuery UI

Para terminar podemos ver um exemplo de calendário que tem várias das coisas que vimos neste artigo.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd"
>
<html lang="es">
<head>
<title>Selecionar data com 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(){
   $("#campodata").datepicker({
      showOn: 'both',
      buttonImage: 'calendar.png',
      buttonImageOnly: true,
      changeYear: true,
      numberOfMonths: 2,
      onSelect: function(textoData, objDatepicker){
         $("#mensagem").html("<p>Voce selecionou: " + textoData + "</p>");
      }
   });
})
</script>
</head>
<body>

<form>
   Data: <input type="text" name="data" id="campodata">
</form>

<div id="mensagem"></div>


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

</body>
</html>

Podemos ver o exemplo em funcionamento em uma página à parte.

A verdade é que, quando pesquisamos um pouco este Datepicker, podemos ver que é um componente magnífico, com todas as opções de configuração e personalização que possamos necessitar. Falar de todas elas e apresentar exemplos seria material para um manual inteiro, por isso, para usos mais complexos recomendamos explorar a documentação de jQuery UI, porque provavelmente haverá alguma coisa que precisemos saber e que não explicamos neste artigo.






Usuários :    login / registro

Manuais relacionados
Categorias relacionadas
O autor

Home | Sobre nós | Copyright | Anuncie | Entrar em contato