Home Page do Portal
Brasil, um país de todos

Relatórios Trac

Table of Contents

O módulo de relatórios Trac fornece um simples mas poderoso facilitador de geração de relatórios para apresentar informações sobre tickets na base de dados Trac.

Ao invés de ter sua própria definição do formato do relatório, TracReports baseia-se na sintaxe padrão SQL SELECT para customizar definições de relatório.

Um relatório consiste basicamente em:

  • ID -- Identificador único (sequencial)
  • Title -- Título descritivo
  • Description -- Uma breve descrição do relatório, no texto em formato WikiFormatting.
  • Report Body -- Lista dos resultados da consulta do relatório, formatado de acordo com os métodos descritos abaixo.
  • Footer -- Links para outros formatos de download para este relatório.

Mudando a ordenação

Relatórios simples - relatórios não agrupados para ser específico - podem ser ordenados por qualquer coluna simplesmente clicando no cabeçalho da coluna.

Se um cabeçalho da coluna é um hyperlink (vermelho), clique na coluna na qual você deseja ordernar por. Clicando no cabeçalho novamente, inverterá a ordenação.

Outros Formatos de Download

Exceto na visualização padrão HTML, relatórios podem também serem exportados em vários formatos alternativos. No fim da página do relatório, você achará uma lista de formatos disponíveis. Clique no link desejado para fazer o download do relatório no formato desejado.

Delimitador de Virgulas - CSV(Comma Separated Values)

Exporte o relatório em texto-puro, cada linha na sua própria linha,cada coluna separada por uma vírgula (','). Nota: O dado de uma coluna é retirado dos caracteres de retorno de linha, próxima linha e vírgulas para preservar a estrutura.

Delimitador-Tab

Como acima, mas utiliza o caracter tab (\t) ao invés de vírgula. (',')

RSS - Conteúdo XML para Syndication

Todos relatórios suportam syndications usando XML/RSS2.0. Para assinar, clique no ícone laranja 'XML' no fim da página. Veja TracRss para informações gerais sobre o suporte RSS no Trac.

Criando Relatórios Customizados

Criar um relatório customizado necessita um bom conhecimento de SQL.

Um relatório é basicamente uma consulta SQL, executada e apresentada pelo Trac. Relatórios podem ser visualizados e criados de uma expressão SQL customizada diretamente pela interface web.

Basicamente, um relatório consiste de uma expressão SELECT de uma tabela 'ticket', usando colunas disponíveis e ordenando na forma que você desejar.

Colunas Ticket

Uma tabela ticket contém as seguintes colunas:

  • id
  • time
  • changetime
  • component
  • severity
  • priority
  • owner
  • reporter
  • cc
  • url
  • version
  • milestone
  • status
  • resolution
  • summary
  • description

Veja TracTickets para uma detalhada descrição dos campos da coluna.

Exemplo: Todos tickets ativos, ordenados por prioridade e tempo 

SELECT id AS ticket, status, severity, priority, owner, 
       time as created, summary FROM ticket 
  WHERE status IN ('new', 'assigned', 'reopened')
  ORDER BY priority, time

Relatórios Avançados: Variáveis Dinâmicas

Para relatórios mais flexíveis, Trac suporta o uso de variáveis dinâmicas em relatórios de sintaxe SQL. Em poucas palavras, variáveis dinâmicas são strings especiais que são substitídos por dados customizados antes da execução da consulta.

Usando Variáveis na Consulta

A sintaxe para variáveis dinâmicas é simples, qualquer palavra maiúscula começando com '$' é considerado variável.

Exemplo: 

SELECT id AS ticket,summary FROM ticket WHERE priority='$PRIORITY'

Para atribuir um valor a $PRIORITY ao visualizar o relatório, você deve defini-lo como um argumento no URL do relatório, deixando de fora o '$'.

Exemplo: 

 http://projects.edgewall.com/trac/reports/14?PRIORITY=high

Variáveis Constantes/Especiais

Aqui está uma mágica das variáveis dinâmicas para permitir relatórios práticos, seus valores são automaticamente setados sem ter que mudar o URL.

  • $USER -- Nome do usuário logado.

Exemplo (Lista todos tickets associados a mim): 

SELECT id AS ticket,summary FROM ticket WHERE owner='$USER'

Relatórios Avançados: Customizando Formatações

Trac também é capaz de relatórios mais avançados, incluindo customização de layouts, grupos de resultados e estilos de CSS definidos pelo usuário. Para criar estes relatórios, nós iremos usar sintaxes SQL especializados para controlar a saída do relatório Trac.

Colunas Especiais

Para formatar relatórios, TracReports procura por nome de colunas 'mágicas' no resultado da consulta. Estes nomes 'mágicos' são processados e afetam o layout e estilo do relatório final.

Formatação Automáticas de Colunas

  • ticket -- Número ID do Ticket. Se transforma em um hyperlink para aquele ticket.
  • created, modified, date, time -- Formata células como uma data e/ou hora.
  • description -- Campo de descrição do Ticket, analisado pelo wiki.

Exemplo: 

SELECT id as ticket, created, status, summary FROM ticket

Customizando Formatação de Colunas

Colunas nas quais os nomes começam e terminam com 2 underscores (Exemplo: _'_color_'_)são assumidos como dicas de formatação, afetando a aparência da coluna.

  • _'_group_'_ -- Resultados do grupo baseado nos valores desta coluna. Cada grupo deverá ter seu próprio cabeçalho e tabela.
  • _'_color_'_ -- Deve ser valor numérico de 1 até 5 para selecionar uma cor de linha pre-definida. Tipicamente usado para colorir linhas de acordo com a prioridade.
  • _'_style_'_ -- Uma expressão CSS style customizada para usar na linha atual.

Exemplo: Lista tickets ativos, agrupados por milestone, coloridos por priority 

SELECT p.value AS __color__,
     t.milestone AS __group__,
     (CASE owner WHEN 'daniel' THEN 'font-weight: bold; background: red;' ELSE '' END) AS __style__,
       t.id AS ticket, summary
  FROM ticket t,enum p
  WHERE t.status IN ('new', 'assigned', 'reopened') 
    AND p.name=t.priority AND p.type='priority'
  ORDER BY t.milestone, p.value, t.severity, t.time

Nota: O resultado da concatenação das tabelas é usado para associar prioridades de ticket com seus respectivas representações numéricas da tabela enum.

Mudando layout das linhas do relatório

Por padrão, Todas colunas de cada linha são mostradas em uma única linha no relatório HTML, possivelmente formatado de acordo com a descrição acima. Porém, é também possível criar múltiplas linhas de entrada do relatório.

  • column_ -- Quebre a linha após isto. Colocando um underscore ('_') no nome da coluna, as colunas restantes continuarão na segunda linha.
  • _column_ -- Linha cheia. Adicionando um underscore ('_') ambas no começo e fim no nome da coluna, os dados serão mostrados em linhas separadas.
  • _column -- Esconda dados. Prefixando um underscore ('_') no nome da coluna instrui Trac a esconder o conteúdo da saída do HTML. Isto é útil para informações que serão visíveis apenas se for salva em outros formatos (CSV ou RSS/XML).

Exemplo: Lista tickets ativos, agrupados por milestone, colorido por prioridade, com descrição e layout de linhas múltiplas 

SELECT p.value AS __color__,
       t.milestone AS __group__,
       (CASE owner 
          WHEN 'daniel' THEN 'font-weight: bold; background: red;' 
          ELSE '' END) AS __style__,
       t.id AS ticket, summary AS summary_,             -- ## Quebra de linha aqui
       component,version, severity, milestone, status, owner,
       time AS created, changetime AS modified,         -- ## Date é formatada
       description AS _description_,                    -- ## Usa uma linha inteira
       changetime AS _changetime, reporter AS _reporter -- ## Esconde da saída HTML
  FROM ticket t,enum p
  WHERE t.status IN ('new', 'assigned', 'reopened') 
    AND p.name=t.priority AND p.type='priority'
  ORDER BY t.milestone, p.value, t.severity, t.time

Veja também: TracTickets, TracQuery, TracGuide