Como criar sumários dinamicamente com o TOC (Table of Contents) jQuery plugin

Determinados tipos de sites (ou somente algumas páginas de sites) às vezes precisam de um sumário para que o conteúdo fique bem organizado e para oferecer uma visão geral sobre o conteúdo. Um sumário em páginas de web também é muito útil em relação á usabilidade, dado que facilita a experiência do visitante ter um “apanhado geral” sobre o que vai encontrar.

Agora imagine como seria bom se houvesse uma maneira de criar sumários dinamicamente para as páginas de seu site! “Seria”, não; é! É possível criar sumários de forma dinâmica através do plugin TOC (Table of Contents) jQuery plugin (jquery.toc) para jQuery!

Sobre o TOC jQuery Plugin

Na página oficial do TOC jQuery Plugin é possível encontrar informações importantes sobre o funcionamento do plugin, histórico de atualizações, exemplo de funcionamento, dentre outros. Mas, para você que está lendo este artigo diretamente no desenvolvimento para web, é possível ver em todos os artigos o plugin em ação, já que implementei a criação dinâmica de sumários oficialmente aqui no blog! Desabilite o javascript que você vai ver, ou melhor, não vai ver o Sumário! ;-)

O funcionamento do plugin é em cima das tags de títulos e subtítulos presentes nas páginas do site. Através da análise destes o plugin:

• Gera um Sumário (“Table of Contents”) dinamicamente (através de tags de lista);
• Adiciona automaticamente numeração ao Sumário e aos correspondentes títulos e subtítulos da página.

E, seguindo a “filosofia” do jQuery, tudo é feito de forma bastante automática e simplificada, bastando somente algumas pouquíssimas linhas de código para colocar a extensão em funcionamento!

Funcionamento do jquery.toc

A primeira coisa a se fazer, logicamente, é baixar o query.toc.  Lembrando que é sempre aconselhável baixar a última versão disponível – na data de publicação deste artigo é a v1.0.2. Em relação a seu tamanho, também não há nada com o que se preocupar: sua versão “normal” tem 5.3KB e a versão compactada tem 2.4KB. Depois disso, basta fazer a “chamada” do script (abaixo da chamada ao jQuery, claro) e começar a codificar.

Lembrando que é conveniente fazer a chamada de todos javascripts e codificar na linguagem ao final do documento, preferencialmente antes de “</body>”.

Codificando

Primeiro é importante escolher em qual lugar vai aparecer o sumário dinâmico. É bom dedicar uma DIV especialmente para isso para evitar erros/conflitos. Para facilitar, neste exemplo a DIV terá o ID “toc”.

1

<div id="toc"></div> <!-- sim, é uma DIV vazia... -->

Uma das condições para o correto funcionamento do TOC jQuery Plugin é que cada título/subtítulo que se queira incluir no sumário tenha o atributo id para ser referenciado e que será usado nos links de âncora do Sumário criado. Falando claramente: todos seus títulos/subtítulos têm que ter id.

Logicamente que criar manualmente um id para cada título/subtítulo a fim de gerar dinamicamente o Sumário seria um trabalho extra e, diga-se de passagem, desnecessário, já que é possível fazer isso via javascript/jQuery. Vamos por partes.

O primeiro objetivo é “pegar” todos título/subtítulos da página (no trecho em que se queira incluir no Sumário dinâmico) e acrescentar um id para cada um. O id pode ser qualquer nome que seja diferente para cada título/subtítulo; afinal, trata-se de um id (mais informações a respeito, leia o artigo sobre diferenças entre IDs e Classes):

1
2
3
4
5

(function ($) {
    $("#content :header").each(function(){ // http://tinyurl.com/celarh
        // fazer qualquer coisa com cada título/subtítulo dentro de #content (nome-alvo fictício)
    });
})(jQuery);

No caso da geração automática de Sumário de conteúdos com o plugin TOC jQuery, nosso objetivo, como já explicado, é dar um id para cada título/subtítulo. Poderíamos criar um nome genérico e fazer um contador para marcar com números (o resultaria seria “#id1″, “#id2″, “#id3″…); mas acho mais “elegante” manter o texto do título e, para enfeitar mais um pouco, inserir “_” no lugar de cada espaço (dado que nomes de IDs não podem conter white spaces).

Vamos gerar um ID para cada título/subtítulo baseados nas seguintes premissas:

• Nome será o texto do título/subtítulo;
• Todos caracteres minúsculos;
• Eliminação de qualquer caractere que não seja letra ou número (incluindo caracteres especiais);
• Substituição de espaços por underscore (“_”).

Então, estamos assim, por enquanto:

1
2
3
4
5
6

(function ($) {
    $("#content :header").each(function(){
        var id = ($(this).text()).toLowerCase().replace(/[^a-zA-Z 0-9]+/g,'').replace(/\s/g, '_'); // http://tinyurl.com/dl9z35
        $(this).attr('id', id); //  http://tinyurl.com/68cxmw
    });
})(jQuery);

Depois disso, já temos todos os títulos e subtítulos “alvo” com um ID. Agora é o momento de mandar o jquery.toc entrar em ação:

1
2
3
4
5
6
7
8

(function ($) {
    $("#content :header").each(function(){
        var id = ($(this).text()).toLowerCase().replace(/[^a-zA-Z 0-9]+/g,'').replace(/\s/g, '_');
        $(this).attr('id', id);
    });
 
    $('#toc').toc(); // #toc é o "container" do Sumário, definido anteriormente
})(jQuery);

O “grosso” da coisa é isso! Pode fazer seus testes e ver que o Sumário foi criado automaticamente e está funcional, com todas as âncoras apontando para seus respectivos títulos/subtítulos.

“Refinando” o Sumário dinâmico

Para obter um resultado mais “fino” ainda falta codificar alguns detalhes.

Por exemplo: vamos supor que, por algum motivo, você queira que alguns títulos/subtítulos não entrem na listagem do Sumário. Consultando a documentação oficial do TOC jQuery Plugin é possível identificar que isso é possível através da opção exclude. Vamos supor que não queremos que os títulos primários e o título secundário de id “apresentacao” entrem na listagem; então o trecho ficaria:

1

$('#toc').toc({exclude: 'h1, h2#apresentacao'});

Em conversa com o desenvolvedor do plugin, fiquei sabendo que existe uma limitação quanto ao número de elementos possíveis no exclude. Então, caso tenha bastantes elementos que não gostaria que estivesse listados no Sumário, uma boa dica é criar uma classe qualquer (por exemplo “toc-exclude”) e marcar os elementos indesejáveis com ela. Então, ficaria algo como:

1

$('#toc').toc({exclude: 'h1, h2#apresentacao, .toc-exclude'});

Aproveitando que estamos querendo fazer um trabalho bem-feito e que jQuery nos permite isso com muita facilidade, não nos custa indicar ao visitante que aquela listagem é um Sumário, inserindo, via jQuery, um subtítulo antes da DIV “toc”:

1

$('#toc').toc({exclude: 'h1, h2#apresentacao, .toc-exclude'}).prepend('<h2>Sum&aacute;rio</h2>'); // http://tinyurl.com/bjlr42

O script final de nosso exemplo – que serve de “base” para a implementação do jquery.toc em qualquer site – fica assim:

1
2
3
4
5
6
7
8

(function ($) {
    $("#content :header").each(function(){
        var id = ($(this).text()).toLowerCase().replace(/[^a-zA-Z 0-9]+/g,'').replace(/\s/g, '_');
        $(this).attr('id', id);
    });
 
    $('#toc').toc({exclude: 'h1, h2#apresentacao, .toc-exclude'}).prepend('<h2>Sum&aacute;rio</h2>');
})(jQuery);

Conclusões sobre o Table of Contents jQuery plugin

Como foi demonstrado, criar um sumário automático-dinâmico com jQuery utilizando o plugin jquery.toc é algo bastante simples. E ele pode ser usado em qualquer tipo de site, inclusive os que utilizam CMSs, como os desenvolvidos em WordPress – vejam que este blog é WordPress e o recurso está presente.

Como “desafio”, no site em que for implementar o jquery.toc faça o seguinte: gere a DIV #toc através de jQuery ao invés de deixá-la na marcação (X)HTML. Coloque o link para o site nos comentários! ;-)