Zabuto Calendar: um plugin JQuery para calendários simples e eficiente

Precisa exibir um calendário? Precisa destacar datas neste calendário? Precisa associar eventos à estas datas? Eis uma biblioteca jquery fácil, leve e limpa.

ìndice:

Boa noite, caros. Gostaria de compartilhar com vocês minha satisfação em utilizar uma certa biblioteca jquery para exibir calendários, que é leve, fácil de customizar e não deixa o código fonte sujo. É a Zabuto Calendar. Ela é ideal para calendários simples, desses que mostram datas especiais e links para eventos destas datas.


Figura 1 - Exemplo simples do calendário da Zabuto
 
Além do JQuery, a biblioteca faz uso do Twitter Bootstrap para funcionar. Ou seja, é meio caminho andado para inserir e customizar facilmente o calendário sem criar sujeira, além de poder utilizar todos os benefícios do Bootstrap.

A página da biblioteca é https://github.com/zabuto/calendar, onde podemos baixá-la e temos uma pequena documentação a respeito. Nesta mesma documentação, contém o link dos exemplos de utilização: http://zabuto.com/dev/calendar/examples/; estes, sim, valem a pena explorar. A princípio, parecem poucos exemplos, mas é porque eles são bem diretos e a biblioteca possui o essencial para ser ótima em seu própósito.


Pontapé inicial

Então, vamos começar. Tomando por base a página de exemplos da biblioteca, e considerando sempre que o JQuery e o Bootstrap já estejam incluídos, vejam como é fácil inserir a versão mais simples do calendário na página web da sua aplicação:
 
<!—- Incluir os arquivos js e css da biblioteca --> 
<script src="(CAMINHO)/zabuto_calendar.min.js"></script> 
<link rel="stylesheet" type="text/css" href="(CAMINHO)/zabuto_calendar.min.css"> 

<!—- Definir o element que se transformará no calendário --> 
<div id="my-calendar"></div> 

<!-— Inicializar o calendário quando a página estiver pronta --> 
<script type="application/javascript"> 
$(document).ready(function () 
{ 
      $("#my-calendar").zabuto_calendar();
}); 
</script> 
Exemplo de código inicial para uso da Zabuto Calendar

E pronto, o calendário irá aparecer. Neste exemplo, não foi feita nenhuma configuração, nem adicionado nenhum evento. Por utilizar o bootstrap, o calendário gerado vai seguir o css do mesmo que estiver na sua aplicação. Possivelmente você vai desejar adaptá-lo e destacar datas especiais com eventos; vamos ver como fazer isso nas seções a seguir.

Figura 2 - Calendário gerado com o código inicial


Configurações
 
  • Linguagem:  a Zabuto permite configurar o idioma do calendário entre dez linguagens disponíveis – Inglês (default), Alemão, Espanhol, Francês, Italiano, Holandês, Português (ufa, hehe), Russo, Sueco e Turco.
  • Navegação: é possível determinar o mês e ano em que o calendário será inicializado. Também pode-se remover os navegadores de anterior|próximo mês, ou limitar a navegação para até N meses antes|depois.
  • Estilo: você pode definir (1) se vai querer separar os dias em células individuais ou não, (2) se quer destacar o dia de hoje, (3) se quer exibir os nomes dos dias da semana no cabeçalho, (4) se sua semana começará no domingo ou na segunda, e (5) se deseja customizar o link para navegação entre meses. Este último permite que você possa utilizar um ícone ao invés de link de texto, por exemplo; a biblioteca recomenda o uso da Fonts Awesome na sua aplicação (que é outra biblioteca que uso muito e super indico).

Sobre CSS, o jeito é explorar o HTML gerado através do depurador do navegador (eu uso o Firebug, no Firefox), verificando os elementos que você deseja personalizar e gerando seu estilo para eles. Importante: não amarre o CSS do calendário ao ID do elemento que irá contê-lo. Além de ser má prática, o Zabuto troca o ID do elemento ao gerar o calendário.

Abaixo, um pequeno exemplo utilizando algumas destas configurações. Recomendo mais uma vez que entrem na página de exemplos da biblioteca (http://zabuto.com/dev/calendar/examples/), e vejam exemplos para todas as configurações  citadas acima.
 
<script type="application/javascript"> 
$(document).ready(function () 
{ 
    $("#calendario-eventos").zabuto_calendar({
        language: "pt",
        today: true,
        show_days: true,
        cell_border: true,
    });
}); 
</script>

<style type="text/css">
    
    .calendario-eventos div.zabuto_calendar .day {
        padding:0 !important;
    }
    
    .calendario-eventos div.zabuto_calendar .table tr.calendar-month-header th > span {
        padding-top:3px;
    }

    .calendario-eventos div.zabuto_calendar .table tr.calendar-month-header th span {
        padding-bottom:3px;
    }

    .calendario-eventos div.zabuto_calendar .table tr.calendar-month-header th {
        padding-bottom:0px;
        padding-top:3px;
        background-color:#FAF2F2;
        color:#e49a88;
    }

    .calendario-eventos div.zabuto_calendar .badge-today, 
    .calendario-eventos div.zabuto_calendar div.legend span.badge-today {
        background-color: #e49a88;
    }
</style>
Exemplo de código-fonte com algumas alterações de configuração e estilo


Figura 3 - Calendário gerado  no exemplo


Inserindo e customizando datas e eventos

E agora, a parte que acho que mais interessa: como destacar datas no calendário, e também como associá-las a eventos.

Primeiramente, é necessário já estar com a lista de datas definida. Ela deve ser passada na inicialização da biblioteca através de um vetor de objetos JSON; estes objetos devem possuir um formato específico:
 
{date: yyyy-mm-dd, badge: boolean, title: string, body: string: footer: string, classname: string}
Formato JSON esperado para destacar datas no calendário.

Dos campos acima, somente a data é obrigatória. Os outros podem ser usados conforme a necessidade, o que veremos nos próximos exemplos. A lista de objetos JSON contendo as datas a destacar pode ser enviada para a biblioteca através de Ajax, ou declarada diretamente no script. Vamos ver um exemplo de cada a seguir; ambos irão exibir o calendário da Figura 4 - veja que, a princípio, o evento da data é exibido em uma tooltip (legenda ao passar o cursor sobre a data).

Figura 4 - Resultado da declaração de datas.
 
1 - Exemplo com declaração direta:
 
<!-— Elemento calendário --> 
<div id="calendario-eventos" class="calendario-eventos"></div> 

<script type="application/javascript"> 
    // Datas a destacar - declaração direta
    var eventData = [
        { "date": "2017-07-10", "title": "Tarde de autógrafos - Lucca Silva" },
        { "date": "2017-07-12", "badge": true, "title": "Tarde de autógrafos - Elizete Maria Moura" }
    ];

$(document).ready(function () 
{ 
    $("#calendario-eventos").zabuto_calendar({ 
        data: eventData,
        language: "pt",
        today: true,
        show_days: true,
        cell_border: true,
    });
}); 
</script>
Código com declaração das datas direto no javascript
 
2 - Exemplo com declaração em action chamada via ajax:
 
public JsonResult ObterEventos()
        {
            var jsonData = new object { };
            try
            {
                // Faz de conta que estou acessando o banco e obtendo as datas.
                var dataJson1 = new { date = "2017-07-10", title = " Tarde de autógrafos - Lucca Silva "};
                var dataJson2 = new { date = "2017-07-12", badge = true,  title = " Tarde de autógrafos - Elizete Maria Moura " };	                
                jsonData = new object[] { dataJson1, dataJson2};
            }
            catch (Exception e)
            {
                jsonData = new { status = "ERRO", erro = "Erro de sistema: " + e.Message };
            }
            return Json(jsonData,  JsonRequestBehavior.AllowGet);
        }
Action em C# montando a lista de objetos JSON com as datas e eventos
 
<!-— Elemento calendário --> 
<div id="calendario-eventos" class="calendario-eventos"></div> 

<script type="application/javascript"> 

$(document).ready(function () 
{ 
    $("#calendario-eventos").zabuto_calendar({ 
        ajax: {
            url: "Evento/ObterEventos",
        },
        language: "pt”
    });
}); 
</script>
Javascript inicializando a biblioteca, chamando a action


Exibindo os eventos da data em uma modal

Caso deseje exibir informações mais detalhadas sobre uma data, você pode utilizar uma modal, configurando a opção modal: true na inicialização da biblioteca. E aí, todas as datas cujo objeto JSON possua o campo body se transformarão em um link, que clicado exibe uma modal cujo conteúdo é o valor de body. Isso pode ser útil para informar, por exemplo, mais de um evento por data.
 
public JsonResult ObterEventos()
        {
            var jsonData = new object { };
            try
            {
                // Faz de conta que estou acessando o banco e obtendo as datas.
                var dataJson1 = new { date = "2017-07-15", title = "Tarde de autógrafos 1" , body = "<ul><li>14:30 - Marina Silva</li><li>17:00 - Samara Eliote Moraes</li></ul>", footer = "Informação extra"};
                var dataJson2 = new { date = "2017-07-16", title = "Tarde 2" };
                var dataJson3 = new { date = "2017-07-17", title = "Tarde 3" };
                jsonData = new object[] { dataJson1, dataJson2, dataJson3 };
            }
            catch (Exception e)
            {
                jsonData = new { status = "ERRO", erro = "Erro de sistema: " + e.Message };
            }
            return Json(jsonData,  JsonRequestBehavior.AllowGet);
        }
Código de action C#, informando em uma de suas datas o campo body (e também o campo footer)

 
<script type="application/javascript"> 

$(document).ready(function () 
{ 
    $("#calendario-eventos").zabuto_calendar({
        ajax: {
            url: "Evento/ObterEventos",
            modal: true
        },
        language: "pt",
        today: true,
        show_days: true,
        cell_border: true,
    });
});
</script>
Chamada da biblioteca, informando o campo modal como true
 


Figura 5 - Modal resultante da data contendo campo body


Classes e legendas

Voltando ao formato do objeto JSON, veja que ele possui o atributo classname, que é aplicado na célula da data. Se desejar, dá pra usar classes variadas e as badges do Bootstrap para colorir suas datas conforme sua necessidade, e depois configurar uma legenda no calendário, como mostra o exemplo de legendas da página da biblioteca, em http://zabuto.com/dev/calendar/examples/set_legend.html .


Exemplo de uso de classes e legendas, retirado da página de documentação


Triggers

Por último, a Zabuto oferece duas funções de trigger: [action] para configurar o que acontece ao clicar em uma data, e [action_nav] para configurar o que acontece ao clicar na navegação dos meses.
 
<script type="application/javascript"> 

$(document).ready(function () 
{ 
    $("#calendario-eventos").zabuto_calendar({
        action: function () {
            return alertDia(this.id);
        },
        action_nav: function () {
            return alertMes(this.id);
        },
        ajax: {
            url: "Evento/ObterEventos",
            modal: true
        },
        language: "pt",
        today: true,
        show_days: true,
        cell_border: true,
    });
});

function alertDia(id) {
    var dia = $("#" + id).data("date");
    var hasEvent = $("#" + id).data("hasEvent");
    alert("Clicou no dia "+dia + ", possui eventos = " +hasEvent);
}

function alertMes(id) {
    var nav = $("#" + id).data("navigation"); // next ou prev (proximo ou anterior)
    var to = $("#" + id).data("to");
    alert("Clicou em " + nav + " e agora foi para " + to.month + '/' + to.year);
}
</script>
Código utilizando as triggers.

Por exemplo, eu utilizei destes triggers para atender uma necessidade particular de uma aplicação minha: precisei informar abaixo do calendário a lista completa de eventos que ocorreriam em um determinado mês.  Então, eu criei uma div abaixo do calendário e preenchia a lista de eventos do mês exibido via ajax, de acordo com a navegação do usuário.


E fim, por enquanto

E é isto! Uma biblioteca de calendário fácil de inserir, fácil de configurar, que não enche seu código de linhas e mais linhas, que já está alinhada com o Bootstrap, permite usar Fonts Awesome e tem somente o que você precisa – e é tudo o que você vai precisar. Para calendários somente de exibição de eventos e datas especiais, está mais que perfeito.

Espero que tenham gostado e se divirtam explorando as páginas de documentação e exemplos, citados no começo deste artigo. Até mais!
 

1 comentários

avatar
rafaela em 29/12/2017 disse:
as setas que fazer o meses passarem n aparecem com nenhuma cor, tentei manipular seguido seguindo a classes como demonstrou no código acima na parte de estilização, mas n funcionou, verifiquei cada detalhe e nada. Mudando de assunto, as dicas daqui me ajudou muito, obrigado parabéns... Responder

Envie seu comentário