4.6 - Aba List: plain vs grouped
Aba List — plain vs grouped
A aba List aparece apenas para item_type=list. Ela controla como a tabela do card é construída — quais colunas mostrar, em que ordem, agrupada em árvore ou não. Veja nos prints abaixo.
list_type
A escolha mais importante da aba: plain (tabela simples) ou grouped (árvore agregada).
plain
Tabela com Top N linhas e colunas customizadas. Ideal para rankings, listas de atividades, "últimos contatos criados".
Usa page_size, sort_field_id, sort_dir e list_column_ids.
grouped
Árvore agregada em dois níveis (bucket + sub-bucket). Ideal para drill manual: por vendedor, por mês, por categoria.
Usa group_by_field_id, group_by_granularity e measure_ids.
Print 1 — aba Lista de um item plain (Latest Contacts) com 5 colunas configuradas:
Note na direita o preview idêntico ao que aparece no dashboard final — a tabela com Nome, E-mail, Telefone, País, Cidade.
Modo plain em detalhe
4 campos controlam a tabela renderizada.
| Campo | O que faz | Padrão |
|---|---|---|
page_size |
Número de linhas exibidas na tabela. | 10 |
sort_field_id |
Campo do model_id usado para ordenar (filtro SORT_FIELD_DOMAIN — sem o2m/m2m/binary). |
— |
sort_dir |
asc ou desc. |
asc |
list_column_ids |
One2many boardkit.dashboard.item.column — ordem definida por sequence. |
— |
list_column_ids — o subgrupo Coluna
Cada linha de list_column_ids é um registro de boardkit.dashboard.item.column com dois campos: sequence (ordem de exibição, menor = primeiro) e field_id (campo do model_id).
Tipos de campo excluídos do dropdown
O renderer não sabe desenhar binary, one2many e many2many. Eles são removidos do dropdown do field_id. Para Many2one (ex.: país, vendedor), a coluna aparece com o display_name — é a forma mais comum.
Print 2 — aba Lista de uma atividade (mail.activity) — colunas diferentes refletem dados diferentes:
Repare como o Tipo de lista muda toda a configuração subsequente.
Modo grouped em detalhe
Em vez de linhas individuais, o card vira uma árvore com buckets de primeiro nível e sub-buckets com agregações. 6 campos:
| Campo | O que faz |
|---|---|
group_by_field_id |
Obrigatório. Campo do model_id que define o nível superior da árvore. |
group_by_granularity |
Quando group_by é date/datetime: hour, day, week, month, quarter, year. |
boolean_true_label |
Quando group_by é boolean, customiza a legenda do "True" (default Yes). |
boolean_false_label |
Mesmo para o "False" (default No). |
measure_ids |
One2many — uma ou mais agregações plotadas em cada sub-bucket. |
measure_ids.field_id |
Cada measure tem seu próprio campo numérico (mesmo NUMERIC_FIELD_DOMAIN). |
Onde aparece a árvore?
Em grouped, o card mostra o group_by_field_id como nó raiz. Cada nó tem uma linha por measure configurada — ex.: Vendedor → Soma de Receita + Contagem de Pedidos.
sort_field_id e sort_dir — onde atuam
Estes campos têm dois usos distintos:
Em plain
Ordena as linhas individuais da tabela. Combine com page_size para um Top N.
Ex.: sort_field_id=create_date, sort_dir=desc, page_size=10 → últimos 10 contatos criados.
Em grouped / funnel
Ordena os buckets dentro do grupo (ou os estágios de um funnel, sobrepondo-se ao chart_sort da aba Chart).
Ex.: em funnel de CRM, use stage_id.sequence para manter a ordem natural do pipeline.
Quando usar List e quando NÃO usar
Use List quando…
- O usuário precisa ver detalhes textuais (nome, e-mail, valor).
- Você tem poucos registros relevantes (≤ 200 linhas).
- Precisa de um drill direto para a lista (cada linha pode ter uma action).
- Está mostrando "últimos eventos" (atividades, mensagens, contatos recentes).
Evite List quando…
- Você tem mais de 1000 linhas — o card fica lento; prefira um gráfico de barras Top N.
- Quer comparar tendência ao longo do tempo → use
lineouareana aba Chart. - Quer ver um único número → use
tileoukpina aba Value. - Os campos relevantes são apenas numéricos → um gráfico comunica melhor.
Validações
A aba List tem 1 validação específica:
_check_columns_sequence_unique
Garante que não há duplicatas de sequence em list_column_ids dentro do mesmo item. Sequências duplicadas causariam ordem indefinida na renderização — a validação evita o problema.
Pronto para drill
Com a aba List configurada, o próximo passo é a aba Drill down — onde você define o que acontece quando o usuário clica num bucket do gráfico ou numa linha da tabela.
Agora que você domina a aba List, vamos para a aba Drill down — onde os gráficos e listas ganham interatividade multinível.
Detalhe da aba List: list_type (plain vs grouped), page_size, sort, list_column_ids, measure_ids, tipos de campo excluídos e quando usar / não usar.
Por enquanto não há comentários.