= Paginação =

== Classe: wf_paging ==
[[TOC(heading=Workflow,depth=1,WF/Changelog,WF/Documentacao,WF/Instalacao,WF/Links,WF/Propostas,WF/Recursos)]]

Esta classe tem a finalidade de paginar os resultados de uma busca e permitir sua ordenação.

== Métodos ==

=== configure ===

'''Descrição:''' Faz a configuração básica do paginador.

'''Parâmetros:'''

  $itensPorPagina: o número de itens por página.

  $request: a variável que conterá informações sobre a página (número da página, tipo de ordenação, etc.) que está sendo exibida. Normalmente será {{$_GET}} ou {{$_POST}} (principalmente a primeira).

'''Retorno''': <nenhum>

'''Exemplo de uso:'''

{{{
$paging = $this->factory->getInstance("wf_paging");

$paging->configure(10, $_GET);
}}}

----

=== useDatabase ===

'''Descrição:''' Indica se os resultados serão (ou não) obtidos através de um {{SELECT}} no banco de dados (BD).

'''Parâmetros:'''

  $flag: um booleano onde, {{true}} indica que será usado o BD e {{false}} que não será usado o BD.

'''Retorno''': <nenhum>

'''Exemplo de uso:'''

{{{
$paging->useDatabase(true);
}}}

----

=== enableSorting ===

'''Descrição:''' Indica se será feita ordenação dos resultados.

'''Parâmetros:'''

  $flag: um booleano onde, {{true}} indica que será feita ordenação e {{false}} que a ordenação não será feita.

'''Retorno''': <nenhum>

'''Exemplo de uso:'''

{{{
$paging->enableSorting(true);
}}}

----

=== setSortingTitles ===

'''Descrição:''' Define os campos possíveis para ordenação dos resultados. Deve ser utilizado caso a paginação tenha sido configurada para utilizar ordenação.

'''Parâmetros:'''

  $titulos: uma array de arrays associativas. Cada array associativa possui o seguinte formato:

{{{
$titulo['name'] = 'Nome do Campo';
$titulo['id'] = 1;
}}}

Onde, o elemento {{id}} representa:

1.quando se usa BD: o número da ordem da coluna no {{SELECT}}. Exemplo, no comando SQL {{SELECT uid, sobrenome FROM usuario}}, para a coluna {{uid}} deve ser utilizado o valor 1, já para a coluna {{sobrenome}} deve ser utilizado o valor 2. Como pode ser percebido, no caso do BD, a primeira coluna possui valor 1 (e não zero).

1.quando não se usa BD: ('''AINDA NÃO ESTÁ IMPLEMENTADO''') a ordem do elemento na "linha". Exemplo, supondo que se tenha a variável $item com os valores:

{{{
   $itens[] = array('nome' => 'José', 'uid' => 1);
   $itens[] = array('nome' => 'João', 'uid' => 2);
}}}

  Para ordenar a variável $itens pelo nome, é necessário se passar o id com valor 0 (zero), e com valor 1 (um) para ordenar pelo uid. Como pode ser observado, neste caso, a primeira coluna inicia-se em 0 (zero).

'''Retorno''': <nenhum>

'''Exemplo de uso:'''

{{{
$titulos = array();
$titulos[] = array('name' => 'UID', 'id' => 1);
$titulos[] = array('name' => 'Nome', 'id' => 2);
$titulos[] = array('name' => 'Telefone', 'id' => 3);
$titulos[] = array('name' => 'Endereco', 'id' => 4);

$paging->setSortingTitles($titulos);
}}}

----

=== restrictDBItems ===

'''Descrição:''' Pagina os resultados a partir de uma query.

'''Parâmetros:'''

  $db: link para a base de dados do projeto.

  $query: {{SELECT}} que buscará os registros no BD.

'''Retorno''': uma array com os itens que deverão ser exibidos.

'''Exemplo de uso:'''

{{{
$db = $this->factory->getInstance("wf_db");
$itens = $paging->restrictDBItems($db, "SELECT uid, nome, telefone FROM usuario");
}}}

----

=== getSortingTitles ===

'''Descrição:''' Pega os links de ordenação.

'''Parâmetros:''' <nenhum>

'''Retorno''': uma array de arrays associativas. Cada array associativa possui o seguinte formato:

{{{
$titulo['id'] = #id_da_coluna; //ex: 1
$titulo['name'] = 'Título + Seta de Ordenação'; //ex: "Telefone + <Seta>"
$titulo['original_name'] = 'Título'; //ex: "Telefone"
$titulo['link'] = "http://link_para_a_página_com_ordenacao/"; //ex:

"http://localhost/index.php?menuaction=workflow.cel_run_activity.go&activity_id=116&s_co=1&s_so=1"
}}}

'''Exemplo de uso:'''

{{{
$linksOrdenacao = $paging->getSortingTitles();
}}}

----

=== autoLinks ===

'''Descrição:''' Gera o código em HTML dos links de paginação.

'''Parâmetros:'''

  $numeroLinksPaginacao: número máximo de links de paginação que serão exibidos ao mesmo tempo (semelhante ao [http://www.google.com.br/ Google]). Este parâmetro é opicional e possui valor padrão igual a 10.

  $formatoLink: formato do link (HTML). São utilizadas algumas meta-tags (ver abaixo) para especificar o formato do link. Este parâmetro é opicional. Valor padrão: <a href="%link%">%name%</a>

  $formatoSelecionado: formato do link para a página atual (HTML). São utilizadas algumas meta-tags (ver abaixo) para especificar este formato. Este parâmetro é opicional. Valor padrão: <strong>%name%</strong>

  $separador: o separador dos links. Por padrão é o caractere ' ' (espaço).

'''Retorno''': código em HTML dos links de paginação.

'''Meta-tags''':

  %name%: nome do link. Normalmente assume os valores: próximo, anterior, 1, 2, 3, etc.

  %link%: link da página.

  %pageNumber%: número da página (na paginação). Inicia em 1 (um).

  %p_page%: equivale a %pageNumber%-1.

  %start%: número do primeiro item da página.

  %end%: número do último item da página.

'''Exemplo de uso:'''

{{{
$linksPaginacao = $paging->autoLinks(10);
}}}

'''Exemplo de uso (2):'''

{{{
$linksPaginacao = $paging->autoLinks(20, '<button on_click="paginar(%p_page%);[[BR]]
return false;">%name%</button>', '<font color="red">%name%</font>', '<br>');
}}}

----

== Exemplo de uso - Completo ==

No arquivo PHP:

{{{
$titulosOrdenacao = array();
$titulosOrdenacao[] = array('name' => 'Matrícula', 'id' => "1");
$titulosOrdenacao[] = array('name' => 'Nome', 'id' => "2");
$titulosOrdenacao[] = array('name' => 'Telefone', 'id' => "3");

$paging = $this->factory->getInstance("wf_paging");
$paging->configure(10, $_GET);
$paging->useDatabase(true);
$paging->enableSorting(true);
$paging->setSortingTitles($titulosOrdenacao);

$db = $this->factory->getInstance("wf_db");
$itens = $paging->restrictDBItems($db, "SELECT uid, nome, telefone FROM usuario");
$db->disconnect();

$smarty->assign('titulosOrdenacao', $paging->getSortingTitles());
$smarty->assign('linksPaginacao', $paging->autoLinks());
$smarty->assign('itens', $itens);
}}}

No arquivo TPL:

{{{
{$linksPaginacao}
{if count($itens) == 0}
	<center><strong>nenhum registro encontrado</strong></center>
	<br/><br/>
{else}
	<table>
	<tbody>
		<tr>
		{foreach from=$titulosOrdenacao item=tituloOrdenacao}
			<th><a href="{$tituloOrdenacao.link}">{$tituloOrdenacao.name}</a></th>
		{/foreach}
		</tr>
		{foreach name="feItens" from=$itens item=item}
        		<tr>
				<td>{$item.uid}</td>
				<td>{$item.nome}</td>
				<td>{$item.telefone}</td>
			</tr>
    		{/foreach}
    	</tbody>
    	</table>

{/if}

{$linksPaginacao}
}}}