Sorry, this entry is only available in Português.

No contexto de desenvolvimento web a paginação de dados é um processo em que uma larga quantidade de dados é sub-dividida em fragmentos denominados páginas para permitir uma utilização mais eficiente da memória do servidor.

Os maiores desafios de um algoritmo para paginação é tratar o início, o fim, a divisão de páginas, o total de registros e a movimentação entre páginas. Em resumo, criar uma paginação é sinônimo de chatice e trabalho pesado… mas não para nós desenvolvedores Ext (:

Ext.PagingToolbar

O Ext implementa uma especialização de Toolbar chamado PagingToolbar. Em resumo é um toolbar com botões de movimentação no início e um texto, geralmente indicando o número de registros mostrados e o total, no final.

Primeiramente vamos configurá-lo da forma mais fácil possível, sem nenhuma personalização somente com os valores padrões do Ext. Após isso vamos nos aprofundar um pouquinho nas suas configurações.

O básico

Tudo começa com o servidor. Quando utilizamos o PagingToolbar o Ext requisita dados do servidor enviando junto na requisição os parâmetros start e limit.

Cabe ao servidor receber esses dados e realizar a paginação. Segue exemplo de paginação bem básica com PHP e MySQL:

//busca parâmetros de paginação informados pelo Ext
//caso seja vazio (1ª requisição) coloca valores default
$start = isset($_GET["start"]) ? (int)$_GET["start"]:0;
$limit = isset($_GET["limit"]) ? (int)$_GET["limit"]:20;

//busca total
$sql = "SELECT companyId FROM companies";
$rs = mysql_query($sql,$conn);
$num_total_registos = mysql_num_rows($rs);

//realiza consulta
$sql = "SELECT company,price,change,changePct,lastUpdate FROM companies LIMIT $start,$limit";
$rs = mysql_query($sql,$conn);

$arrJson = array();

//transfere pro arrJson
while ($registro = mysql_fetch_object($rs))
{
    $arrJson[] = array(
        "company"   => $registro->company,
        "price"     => $registro->price,
        "change"    => $registro->change,
        "changePct" => $registro->changePct,
        "lastUpdate"=> $registro->lastUpdate
    );
}

//responde
echo json_encode(array(
    "rows"  => $arrJson,
    "total" => $num_total_registos
));

Tudo começa com o servidor. Uma típica resposta do servidor está exemplificada abaixo. Repare que temos o array com 20 registros e um “total” indicando quantos registros existem no meu banco de dados. Esse total é necessário para que os cálculos de paginação sejam feitos corretamente. Já que o Ext vai receber somente 20 registros, ele precisa ter a informação do total.

{
    "rows":[
        {"company":"3m Co","price":71.72,"change":0.02,"changePct":0.03,"lastUpdate":"9/1 12:00am"},
        {"company":"Alcoa Inc","price":29.01,"change":0.42,"changePct":1.47,"lastUpdate":"9/1 12:00am"}
        //...restante dos 20 registros...//
    ],
    "total":29
}

IMPORTANTE: O pagingToolbar não realiza a paginação! Você tem que realizar a paginação no servidor através de SQL ou qualquer outra técnica.

Feito toda a rotina do servidor temos que criar DataStore para receber e gerenciar esses dados. O DataStore serve como meio-de-campo entre os dados do servidor e os componentes Ext. Abaixo tenho um JsonStore que pega a resposta JSON exemplificada acima e converte em registros Ext (record)

var dsEmpresas = new Ext.data.JsonStore({
    root : "rows",
    totalProperty : "total",
    remoteSort : true,
    sortInfo : {field: "company" ,direction: "ASC"},
    proxy : new Ext.data.HttpProxy({url: "ajax.php" ,method: "GET" }),
    fields : [
        {name: "company" ,type: "string" },
        {name: "price" ,type: "float" },
        {name: "change" ,type: "float" },
        {name: "changePct" ,type: "float" },
        {name: "lastUpdate",type: "date" ,dateFormat:'n/j h:ia'}
    ]
});

IMPORTANTE: O DataStore precisa ter declarado um valor para totalProperty. Essa é a propriedade servirá para extrair o total real de registros presentes no servidor.

Em seguida podemos criar um PagingToolbar bem básico. Importante notar que ele possui o número de registros por páginas (pageSize) e está associado ao store. O uso mais comum é colocar o toolbar num Grid, mas ele pode ser usado em um ComboBox paginado, ou até mesmo associado a um formulário configurado para mostrar 1 registro por página!

var pagingToolbar = new Ext.PagingToolbar({
    store : dsEmpresas,
    pageSize : 20,
    displayInfo : true
});

Este exemplo completo com o código está disponível na seção exemplos do portal. Ao fim desse artigo disponibilizo o link para acesso.

O avançado

Vamos ver agora algumas formas de personalizar o PagingToolbar e fazer algumas coisinhas a mais que o seu simples uso básico.

É possível alterar todos os textos e descrições padrões do PagingToolbar. Não vou comentar todas as propriedades (afterPageText, beforePageText,..) mas vou logo a mais importante que é displayMsg. Essa é a mensagem que aparece no final do Toolbar, e somente quando a propriedade displayInfo está setada como true. As vezes queremos dar ao usuário uma informação extra, que colocamos junto no JSON mas não sabemos como extrair para colocar no Toolbar. Podemos extrair a informação e concatenar ao displayMsg para apresentar ao usuário junto no toolbar. Seguindo o meu grid de empresas e cotações, segue um exemplo de como isso pode ser feito.

//Carrega o store
dsEmpresas.load({
    callback: function()
    {
        //quando o store terminar de carregar extrai a informação da
        //cotação da ibovespa e coloca junto no pagingToolbar

        pagingToolbar.displayMsg = "Índice Ibovespa:" +
        dsEmpresas.reader.jsonData.indiceBovespa +
        " - " + pagingToolbar.displayMsg;

        pagingToolbar.updateInfo();
    }
})

Essa é uma solução rápida. Uma mais profissional seria adicionar um item ao toolbar e usar esse item para mostrar a informação. Sendo assim levanto outra questão: como adicionar mais itens ao toolbar?

A partir da versão 3.0 o toolbar respeita a propriedade items. Basta ir adicionando itens e eles serão colocados no toolbar logo após os botões de navegação e antes da mensagem final (ou seja, no meio). É possível fazer eles serem adicionados no início atribuindo prependButtons como true. Então vamos adicionar um novo item, colocar um id nele e fazer com que nosso índice da bovespa apareca nesse item, ao invés de concatenar ao displayMsg.

var pagingToolbar = new Ext.PagingToolbar({
    store : dsEmpresas,
    pageSize : 20,
    displayInfo : true,
    beforePageText :"Página",
    afterPageText : " de {0}",
    items : [{
        xtype : "tbtext",
        id : "info-bovespa"
    }]
});

//..grid e etc...

//Carrega o store
dsEmpresas.load({
    callback: function()
    {
        Ext.getCmp("info-bovespa").setText( "Índice Ibovespa:" + dsEmpresas.reader.jsonData.indiceBovespa );
    }
});

Resumo

Espero com esse post ter deixado bem claro como realizar paginação de dados do Ext, e ainda configurar o PagingToolbar de uma maneira mais personalizada. Para não restar dúvida, segue checklist dos passos para criar uma paginação sem problemas:

1. Servidor recebe start e limit e realiza a paginação. Retornando os dados mais o total de registros
2. O DataStore que vai receber os dados está configurado corretamente. A configuração totalProperty não pode ser esquecida. Além disso, a ordenação para funcionar corretamente deve ser remota.
3. O PagingToolbar está associado ao store. Se quiser informações mais detalhadas use displayMsg:true.

Agora basta associar o PaginToolbar a um grid, combo, formulário, etc…e sair usufruindo dessa excelente implementação do Ext.

Forte abraço e até a próxima!

Código Completo

Demo Online