Documentação

8 Listagens

Este tipo de página permite criar uma listagem de registros com formulário de filtro de registros, paginação de resultados, ordenação, exclusão, e edição de registros.

8.1 Criação

Para criar uma listagem, deve ser utilizada a opção “Nova página”, e em seguida, selecionar “Listagem”. Após, será aberto um diálogo com informações necessárias para a criação.

Para criar uma listagem, deve-se informar respectivamente:

  1. A base de dados desejada.

  2. A tabela que a listagem buscará as informações

  3. O módulo em que a página ficará agrupada.

  4. Informar se a página aparecerá no menu da aplicação.

  5. O nome da página no menu da aplicação.

  6. O nome da classe controladora da listagem.

  7. Informar se a página será pública. Páginas públicas são acessíveis para usuários não logados na aplicação.

Após a criação, a listagem será apresentada em uma tela com um formulário de filtragem no topo e a própria listagem de exemplo na parte central da tela. No topo fica a barra de ferramentas, à direita o painel de propriedades, eventos e filtros.

Com a criação, o desenvolvedor pode proceder com as definições de quais campos serão utilizados como filtro (formulário de cima), e também como esses campos serão filtrados (operadores lógicos). O desenvolvedor também poderá configurar quais colunas serão exibidas, e também incluir novas colunas na listagem(datagrid) contendo informações de tabelas relacionadas, ou mesmo cálculos entre colunas.

Página listagem

8.2 Propriedades da listagem (datagrid)

As propriedades da listagem permitem alterar definir suas colunas visíveis, e propriedades gerais como ordenação, agrupamento de ações, quantidade de registros por páginas, dentre outros. Para editar as propriedades da listagem, basta clicar sobre o botão com o formato de engrenagem, que fica à esquerda da listagem de exemplo, que é exibida na parte central da tela.

Propriedade Valor
Colunas Permite definir quais colunas serão exibidas, por meio da marcação das colunas através de caixas de seleção. São exibidas como opções todas as colunas da tabela sobre a qual a página está sendo montada.
Título do conteúdo extra (popover) Define um conteúdo de um popover, que é um texto a ser exibido em uma caixa flutuante ao passar o mouse sobre as linhas da listagem.
Conteúdo No conteúdo do popover, é possível relacionar inclusive atributos de outras tabelas.
Ordem Define a ordenação default da listagem, e a propriedade "ordem" define a direção da ordenação.
Agrupar ações* Transforma várias ações da listagem em um menu do tipo dropdown exibido no início de cada linha
Limite de re registros por página Define quantos registros serão exibidos por página da listagem.

*Exemplo de ações agrupadas:

Ações agrrupadas

8.3 Filtros de campos

Ao trabalhar com uma listagem, o usuário poderá filtrá-la com base nos campos do formulário de filtro localizado na parte superior da tela. Neste formulário, o desenvolvedor pode acrescentar novos campos de filtro. Para cada campo, será necessário configurar a maneira que o mesmo será utilizado como filtro. Para tal, é necessário clicar sobre o campo, e em seguida acessar a aba "Filtros". Os filtros mais simples são do tipo "Comparação direta", que permite comparar uma coluna do banco com o campo selecionado do formulário.

Um exemplo seria filtrar as cidades por estado em uma listagem de cidades. Neste exemplo só serão exibidas cidades que forem do estado selecionado..

Filtro listagem

O filtro do tipo subconsulta, permite comparar o campo do formulário com um campo relacionado da tabela exibida na listagem. Um exemplo seria uma listagem de vendas que deve ser filtrada pelo estado da cidade do cliente. Neste caso, bastaria acrescentar uma TCombo de estados no formulário e preencher "Coluna do banco de dados" com o campo que representa o estado do cliente relacionado com a venda, por meio do relacionamento entre campos (venda→cliente → cidade→ estado→id). Assim, o filtro é estabelecido entre o estado selecionado no formulário, e o estado do cliente vinculado àquela venda.

Filtro subconsulta

8.4 Filtros de carregamento

Enquanto que os campos do formulário sobre a listagem permitem o usuário realizar uma filtragem dinâmica em tempo de execução sobre a listagem, existe também a pré-filtragem da listagem, que permite estabelecer filtros "fixos", executados independentemente dos filtros do usuário.

Para definir estes filtros, basta clicar sobre o ícone em formato de "engrenagem" à esquerda da listagem, e acessar a aba "Filtros", localizada à direita da tela. Nesta aba, podem ser realizados filtros de "comparação direta" entre uma coluna do banco de dados, e um valor de filtro (que pode ser fixo ou uma variável de seção). Variáveis de seção contém informações do usuário logado e também podem ser utilizadas como filtro. Já o filtro do tipo "subconsulta" permite estabelecer um filtro entre um campo relacionado à tabela em questão e um valor (que pode ser fixo ou variável de seção).

Um exemplo seria uma listagem de vendas em que é necessário ter um pré-filtro fixo pelo estado do cliente da venda. Nesse caso, bastaria localizar o estado do cliente por meio de um campo relacionado (venda→ cliente→ cidade→estado→id), e estabelecer um filtro de igualdade com o valor "RS", que seria digitado no "Valor do filtro". Assim, somente vendas de clientes do estado “RS” seriam exibidas. O usuário também pode fazer filtros usando variáveis de seção. Ao clicar em "Adicionar filtro" vários filtros desse tipo podem ser adicionados.

A seguir um exemplo de uma listagem que exibe apenas vendas feitas pelo usuário logado no sistema.

Subconsultra

8.4.1 Diferença entre regras e filtros

Regras

Regras normalmente são utilizadas para pré-filtrar alguma coisa. Por exemplo pode-se cadastrar uma regra na listagem para que sejam mostradas somente às vendas realizadas pelo usuário logado na aplicação.

Regras também aparecem em campos do tipo DB. Campos DB tem suas opções carregadas diretamente do banco de dados. Um exemplo seria uma caixa de seleção de pessoas onde é necessário que sejam exibidas apenas as que são vendedores.

Regras campo

Filtros

Os filtros normalmente aparecem em páginas que precisam de um filtro para apresentar o resultado exemplos:

  • Listagens

  • Relatoŕios

  • Gráficos

  • Documentos

  • Desenhos

  • Etiquetas

Em todos os casos os filtros se encontram nos campos que ficam dentro de formulários que irão filtrar os resultados de cada página.

Regras e filtros podem ser de dois tipos

  • Comparação direta

  • Subconsulta

Os dois tipos são explicados no capítulo anterior 8.4

8.5 Propriedades das colunas

Para ajustar uma coluna específica, basta clicar sobre o ícone em forma de "engrenagem" de uma determinada coluna onde diversas propriedades podem ser ajustadas.

Propriedade Valor
Atributo a ser exibido Coluna do banco de dados que será exibida pode-se inclusive escolher colunas de uma tabela relacionada. Como exemplo, podemos citar o “tipo de venda” em uma tabela de vendas tipo_venda→nome.
Rótulo É possível definir o título da coluna
Largura Tamanho da coluna dentro da listagem.
Alinhamento Alinhamento dos valores da coluna: esquerda, direita e centralizado.
Componente de edição Permite habilitar um campo de edição para aquela coluna da listagem. O campo de edição permitirá o usuário editar o valor da coluna dentro da própria listagem.
Ordenável Permite definir, se ao clicar no nome da coluna os valores serão ordenados de forma crescente e decrescente alternadamente.
Transformação Permite aplicar uma função de transformação (formatação monetária, conversão de datas, barras de progresso, etc) sobre a coluna da listagem, alterando sua forma de exibição.
Totalizador Permite definir uma fórmula de totalização na listagem.

8.6 Ações das linhas

Os registros de uma listagem podem ter ações para realizar diversas funções, por padrão uma listagem possui uma ação para edição que normalmente é um link para um formulário específico e uma ação para exclusão. Novas ações podem ser adicionadas através do botão nova ação localizado acima da lista. As ações podem executar métodos de outras páginas através da opção "Ação da página" e escolher a desejada, ou executar um código único, para isso deve-se acessar a aba "Eventos" na lateral direita da página e alterar o código fonte. Para mais informações sobre edição de código ver capítulo 21 Edição de código fonte

8.6.1 Condição de exibição

Normalmente todos os botões de ação da listagem são exibidas, o que facilmente pode ser alterado pela opção "Condição de exibição". É necessário nomear o método para ter acesso a edição de código fonte. Será criado um pseudo código base, nele deverão ser realizadas as comparações e cálculos necessários. Esse método deve retornar um valor booleano, em casos verdadeiros a ação será exibida e casos falsos não.

Exemplo de condição de exibição: exibe a ação de Cancelar venda apenas para itens com estado de venda igual a nova .

Condição de exibição

Abaixo um código base funcional, onde o EstadoVenda::nova é dado que foi inserido diretamente pelo modelo de dados é já pode ser usado em comparações.

public function onShowCancelarVenda($object)
{
    try 
    {
        if($object->estado_venda_id == EstadoVenda::nova )
        {
            return true;
        }

        return false;
    }
    catch (Exception $e) 
    {
        new TMessage('error', $e->getMessage());    
    }
}   

8.7 Atributo a ser exibido

O atributo a ser exibido na listagem pode ser uma coluna direta, mas pode ser também um atributo relacionado, ou mesmo um cálculo entre atributos.

Como visto no capítulo 4.4.7 Coluna visualizável, atributos relacionados são exibidos automaticamente se a tabela relacionada possuir um atributo definido como visualizável. A figura a seguir é um exemplo onde o Adianti Builder exibe automaticamente o nome do cliente.

Atributo a ser exibido

8.7.1 Calculadora de atributos

Além de selecionar o campo a ser exibido, o Adianti Builder também oferece uma função de calculadora entre atributos. Um exemplo de uso da calculadora seria, dentro de uma grid de vendas criar uma coluna que exibirá o valor total do item calculando os descontos e quantidades.

Calculadora de atributos

8.8 Exportar como CSV

Ao criar uma listagem o Adianti Builder automaticamente criar uma ação Exportar como CSV que fica junto com as outras ações no formulário de buscas. Esta opção irá criar um arquivo no formato CSV com todos os dados da listagem abaixo. Só serão colocados no arquivo os registro que obedecerem o filtro previamente aplicado, caso não seja aplicado nenhum filtro o arquivo conterá todos os registros da tabela.

É possível alterar o rótulo, cor e ícone do botão através do seu painel de propriedades. No painel de eventos o desenvolvedor tem acesso ao código fonte da geração do arquivo CSV, onde ele pode configurá-loa conforme suas necessidades. Por padrão o arquivo fica armazenado na pasta /tmp da aplicação e é exibido assim que for gerado.