Componente 1.5 MVC - Funcionalidade admin

Índice do Artigo
Componente 1.5 MVC - Funcionalidade admin
Controlador Ola
Vista e Modelo Ola
Formulário Ola
Todas as páginas

O esqueleto da interface administrativa do componente Olá Pessoal está pronta. Agora falta colocar um pouco de tempero para poder "pilotar" o componente através dos botões da barra de ferramentas. Neste tutorial veremos como implementar as funções básicas de um componente para poder adicionar, editar e deletar registros na sua tabela de dados.

No estágio em que está nosso componente, a seção administrativa não serve para grandes coisas - mostra apenas os registros existentes na base de dados. Para torná-la um pouco mais funcional será preciso adicionar alguns botões e links.

A barra de ferramentas

Já colocamos um título e alguns botões na barra de ferramentas do nosso componente. Como se trata de elementos de tela, o código que faz esta proeza não poderia estar em outro arquivo a não ser o views/olas/view.html.php. Só para relembrar:

JToolBarHelper::title( JText::_( 'Administrar OlÃ¡s' ), 'generic.png' );
JToolBarHelper::deleteList();
JToolBarHelper::editListX();
JToolBarHelper::addNewX();

O método JText::_( ) facilita a tradução do componente. Se houver um arquivo de idioma para o componente, esta função procura a string passada como argumento no arquivo da linguagem: se for encontrada, usa a tradução correspondente; se não for encontrada, mantém a string passada como parâmetro.

Usamos também três métodos da classe JToolBarHelper (o ajudante da barra de ferramentas) para criar os botões. O método deleteList( ) pode ter até três parâmetros opcionais: o primeiro é uma string que será mostrada para o usuário para confirmar a eliminação do(s) registro(s); o segundo é a tarefa que deve ser enviada com a query (a default é 'remove') e o terceiro é o texto que deve aparecer em baixo do botão.

Os métodos editListX e addNewX podem ter dois parâmetros, também opcionais. O primeiro é a tarefa (a default é 'edit' e 'add', respectivamente) e o segundo é o texto que deve ser mostrado em baixo do botão.

Checkboxes e Links

Agora temos botões. Dois deles atuam sobre registros. Como saber sobre quais registros atuar? Só há uma maneira: fazer com que o usuário os indique. Para isto precisamos colocar um checkbox ao lado de cada um dos registros para que o usuário possa fazer a sua escolha e um checkbox que marca todos eles.

Checkboxes são elementos de tela, portanto fazem parte da visão e devem entrar no código do template. Modifique o arquivo /views/olas/tmpl/default.php conforme mostrado a seguir:

<?php defined('_JEXEC') or die('Acesso restrito'); ?>
<form action="index.php" method="post" name="adminForm">
<div id="editcell">
    <table class="adminlist">
    <thead>
        <tr>
            <th width="5">
                <?php echo JText::_( 'ID' ); ?>
            </th>

Inserir (1) - Aqui colocamos algumas linhas de código para gerar um checkbox que marca todos os checkboxes da lista de saudações. Não se preocupe com a Javascript. A função checkall( ) faz parte do framework do Joomla e faz exatamente o que precisamos.

            <th width="20">
              <input type="checkbox" name="toggle" value=""
                     onclick="checkAll(<?php echo count( $this->itens ); ?>);" />
            </th>

            <th>
                <?php echo JText::_( 'Mensagem' ); ?>
            </th>
        </tr>            
    </thead>
    <?php
    $k = 0;
    for ($i=0, $n=count( $this->itens ); $i < $n; $i++)
    {
        $row =& $this->itens[$i];

Inserir (2) - Aqui colocamos um checkbox em cada linha. Desta vez não será preciso criar o checkbox na unha porque podemos usar o método JHTML::_( ) da classe JHTML.

        $checado = JHTML::_( 'grid.id', $i, $row->id );

Inserir (3) - É meio chato marcar um registro e depois ter que subir com o cursor do mouse para clicar no botão Editar. Para facilitar as coisas, podemos colocar um link na mensagem que nos leva diretamente até a tela de edição. Criamos o link usando o método JRoute::_( ) da seguinte forma:

        $link = JRoute::_( 'index.php?option=com_ola&controller=ola&task=edit&cid[]='. $row->id );

        ?>
        <tr class="<?php echo "row$k"; ?>">
            <td>
                <?php echo $row->id; ?>
            </td>

Inserir (4) - Adicionamos uma célula com o checkbox criado em Inserir(2) entre as duas que já existem:

            <td>
                <?php echo $checado; ?>
            </td>
            <td>

Alterar - Aqui usamos o link criado em Inserir(3). Observe que este link aponta para o nosso novo controlador que vai administrar a manipulação de dados das nossas mensagens.

                <a href="<?php echo $link; ?>"><?php echo $row->mensagem; ?></a>

            </td>
        </tr>
        <?php
        $k = 1 - $k;
    }
    ?>
    </table>
</div>
 
<input type="hidden" name="option" value="com_ola" />
<input type="hidden" name="task" value="" />
<input type="hidden" name="boxchecked" value="0" />
<input type="hidden" name="controller" value="ola" />
 
</form>

Testando as alterações

Se você instalou o componente "Olá Pessoal" versão 1.3 e quiser testar estas alterações, modifique o arquivo default.php como indicado, faça o login na área administrativa e chame o componente clicando em Componentes - Olá Pessoal. A nova tela deve mostrar o seguinte:

Fig. 1 - Backend com checkboxes

Neste ponto terminou o "lifting" do template. Pois prepare-se, porque agora é que começa o trabalho realmente pesado.

O controlador Ola

Para os olás na área administrativa já temos um controlador, mas este consegue apenas mostrar a lista das mensagens existentes na base de dados. Agora precisamos de um novo controlador que mostre um olá específico indicado pelo usuário e que coordene as ações de adicionar novos olás além de editar e remover olás existentes.

Adicionar e editar olás são tarefas muito parecidas - ambas apresentam uma tela com um formulário de edição. A diferença é que um novo olá precisa de um formulário em branco e um olá existente que esteja sendo editado mostre o mesmo formulário preenchido. Como as duas tarefas são semelhantes, vamos mapear a tarefa adicionar (novo) para o manipulador de edição. Isto será especificado no construtor do nosso controlador que vai se chamar ola.php e será uma extensão do controlador principal, o OlasController. Crie um novo diretório, /administrator/com_ola/controllers e coloque neste diretório o novo controlador:

<?php
/**
 * @package    Joomla.Tutoriais
 * @subpackage Componentes
 * administrator/components/com_ola/controllers/ola.php
 * @link       http://www.numaboa.com/
 * @license    Creative Commons by-nc-sa
*/
 
// evitar acesso direto
defined( '_JEXEC' ) or die( 'Acesso restrito' );
 
jimport('joomla.application.component.controller');
 
/**
 * Controlador do Componente Ola
 */
class OlasControllerOla extends OlasController
{
  /**
   * constructor (registra tarefas adicionais em métodos existentes)
   * @return void
   */
   function __construct()
   {
      parent::__construct();
 
      // Registrar tarefas extras
      $this->registerTask( 'add', 'edit' );
   }

   /**
   * Método para mostrar a vista
   *
   * @access    public
   */
   function display()
   {
      parent::display();
   }
 
   /**
    * mostrar o formulário de edição
    * @return void
    */
   function edit()
   {
      JRequest::setVar( 'view', 'ola' );
      JRequest::setVar( 'layout', 'formulario' );
      JRequest::setVar( 'hidemainmenu', 1);
 
      parent::display();
   }
?>

Este construtor registra tarefas adicionais em métodos existentes. O primeiro parâmetro de JController::registerTask( ) é a tarefa que deve ser mapeada, o segundo é o método para o qual deve ser mapeado.

Começamos apenas com a tarefa edit e por isso o trabalho do controlador é bastante simples. Tudo o que ele precisa fazer é especificar a vista e o template que devem ser carregados (a vista ola e o layout do formulário que ainda precisamos fazer). Também dizemos ao Joomla que desative o menu principal enquanto estivermos editando. Isto é para evitar que o usuário saia da tela de edição sem salvar alterações que possa ter feito.

Trazendo o novo controlador para a cena

Antes de criarmos o novo controlador ola.php, nosso componente possuía apenas um controlador (o principal). Quem chama os controladores é o script de entrada do nosso componente (administration/components/com_ola/admin.ola.php). Acontece que, como está no momento, ele desconhece a presença de outros controladores além do principal. Precisamos informá-lo de que existe um segundo, o ola.php que acabamos de produzir. Veja como fazer isto:

<?php
/**
 * @package    Joomla.Tutoriais
 * @subpackage Components
 * administration/components/com_ola/admin.ola.php
 * @link       http://www.numaboa.com/
 * @license    Creative Commons by-nc-sa
*/
 
// evitar acesso direto
defined( '_JEXEC' ) or die( 'Acesso restrito' );
 
// Requer o controlador base
require_once( JPATH_COMPONENT.DS.'controlador.php' );

Inserir - Quando houver mais controladores, basta obter seus nomes através do método JRquest::getVar('controller'). Se nenhum 'controller' for especificado na URL, então o principal será acionado. Caso seja especificado outro controlador, então precisamos obter sua localização com:

// Requerer controlador específico se solicitado
if($controlador = JRequest::getVar('controller')) {
  require_once (JPATH_COMPONENT.DS.'controllers'.DS.$controlador.'.php');
}

Alterar - Caso exista outro controlador estendendo o controlador principal, buscar o nome da classe para depois acioná-la:

// Criar o controlador
$nomeclasse  = 'OlasController'.$controlador;

$controlador = new $nomeclasse( );
 
// Obtém a tarefa solicitada
$controlador->execute( JRequest::getVar( 'task' ) );
 
// Redireciona de acordo com a tarefa
$controlador->redirect();
 
?>

A vista Ola

Já temos uma vista para listar todas as mensagens - falta uma vista para mostrar um formulário com apenas uma das mensagens. O propósito desta vista é:

buscar os dados no modelo,
criar a barra de ferramentas,
passar os dados para o template e
chamar o método display( ) para mostrar o template.

Como esta vista será usada tanto para inserir mensagens novas quanto para editar uma existente, a coisa fica um pouco mais complicada. Queremos que o usuário saiba se está adicionando ou editando através da barra de ferramentas. Por este motivo precisamos saber qual foi a tarefa solicitada.

Como estamos buscando o registro no modelo, podemos usar estes dados para determinar a tarefa. Se a tarefa for editar, o campo id do registro possui um valor; se a tarefa for adicionar, o campo id do registro é null.

Vamos adicionar dois botões à barra de ferramentas: salvar e cancelar. Se a tarefa for adicionar, o texto do botão cancelar será 'Cancelar'; se for editar, o mesmo botão (com a mesma funcionalidade) terá o texto 'Fechar'.

O código de /views/ola/view.html.php é o seguinte:

<?php
/**
 * @package    Joomla.Tutoriais
 * @subpackage Componentes
 * administrator/components/com_ola/views/ola/view.html.php
 * @link       http://www.numaboa.com/
 * @license    Creative Commons by-nc-sa
*/
 
// evitar acesso direto
defined( '_JEXEC' ) or die( 'Acesso restrito' );
 
jimport( 'joomla.application.component.view');
 
class OlasViewOla extends JView
{
   /**
    * Método para apresentar a vista Ola
    * @return void
    */
   function display($tmp = null)
   {
      // pegar a mensagem
      $ola  =& $this->get('Dados');
      $novo =  ($ola->id < 1);
 
      $texto = $novo ? JText::_( 'Novo' ) : JText::_( 'Editar' );
      JToolBarHelper::title( JText::_( 'OlÃ¡' ).': [ ' . $texto.' ]' );
      JToolBarHelper::save();
      if ($novo)  {
         JToolBarHelper::cancel();
      } else {
         // para itens existentes o botão é renomeado para 'fechar'
         JToolBarHelper::cancel( 'cancel', 'Fechar' );
      }
 
      $this->assignRef('ola', $ola);
      parent::display($tpl);
   }
}
?>

O modelo Ola

A vista Ola precisa de dados. Isto significa que precisamos criar um modelo que os forneça.

Nosso modelo terá duas propriedades: _id e _dados.

<?php
/**
 * @package    Joomla.Tutoriais
 * @subpackage Componentes
 * administrator/components/com_ola/models/ola.php
 * @link       http://www.numaboa.com/
 * @license    Creative Commons by-nc-sa
*/
 
// evitar acesso direto
defined( '_JEXEC' ) or die( 'Acesso restrito' ); 
 
jimport( 'joomla.application.component.model' );
 
/**
 * Modelo Ola
 */
class OlasModelOla extends JModel
   {
   /**
    * Construtor que obtém a ID de uma solicitação
    *
    * @access    public
    * @return    void
    */
   function __construct()
   {
      parent::__construct();
 
      $array = JRequest::getVar('cid',  0, '', 'array');
      $this->setId((int)$array[0]);
   }
 
   /**
    * Método para definir o identificador do olá
    *
    * @access   public
    * @param    int Identificador olá
    * @return   void
    */
   function setId($id)
   {
      // Define id e limpa os dados
      $this->_id    = $id;
      $this->_dados = null;
   }
 
   /**
    * Método para obter um olá
    * @return objeto com dados
    */
 
   function &getDados()
   {
      // Carrega os dados
      if (empty( $this->_dados )) {
         $query = ' SELECT * FROM #__ola '.
                  '  WHERE id = '.$this->_id;
         $this->_db->setQuery( $query );
         $this->_dados = $this->_db->loadObject();
      }
      if (!$this->_dados) {
         $this->_dados = new stdClass();
         $this->_dados->id = 0;
         $this->_dados->mensagem = null;
         $this->_dados->published = null;
      }
      return $this->_dados;
   }
}
?>

Começamos com um construtor, function __construct( ), que vai tentar obter a id de uma query. Nesta função, o método JRequest::getVar( ) é usado para obter os dados da solicitação. O primeiro parâmetro ('cid') é o nome da variável do formulário; o segundo parâmetro ('0') é o valor default que deve ser atribuído se a variável não for encontrada; o terceiro parâmetro é o hash ('post', 'get', ect) do qual se quer obter o valor e o último ('array') é o tipo de dado que deve ser atribuído ao valor.

Nosso construtor vai pegar o primeiro valor do array cid e atribuí-lo à id. O método setId( ) pode ser usado para definir a id. Quando alteramos o valor da id igualando-o com o valor que o modelo forneceu, os dados ficam desatualizados. É por este motivo que "limpamos" os dados com $this->_dados = null.

Por fim, precisamos de um método para obter os dados. O getDados( ) checa se a propriedade _dados foi populada. Se foi, simplesmente devolve os dados; se não foi, vai buscar os dados na base de dados.

O formulário

A "máquina" está pronta. Agora só falta um formulário que contenha os dados. Como especificamos no novo controlador que o layout será 'formulario', então o script de layout /views/ola/tmpl/formulario.php será procurado. Aqui está ele:

<?php defined('_JEXEC') or die('Acesso restrito'); ?>
 
<form action="index.php" method="post" name="adminForm" id="adminForm">
<div class="col100">
    <fieldset class="adminform">
        <legend><?php echo JText::_( 'Detalhes' ); ?></legend>
        <table class="admintable">
        <tr>
            <td width="100" align="right" class="key">
                <label for="greeting">
                    <?php echo JText::_( 'Mensagem' ); ?>:
                </label>
            </td>
            <td>
                <input class="text_area" type="text" name="mensagem" id="mensagem" size="32"
            maxlength="250" value="<?php echo $this->ola->mensagem;?>" />
            </td>
        </tr>
    </table>
    </fieldset>
</div>
 
<div class="clr"></div>
 
<input type="hidden" name="option" value="com_ola" />
<input type="hidden" name="id" value="<?php echo $this->ola->id; ?>" />
<input type="hidden" name="task" value="" />
<input type="hidden" name="controller" value="ola" />
</form>

Observe que existe um campo oculto (hidden) com o valor da id. O usuário não pode editar a id (e nem deve!), por isto ela é passada no mocó pelo formulário. O valor da tarefa (task), também um campo oculto, será atribuído assim que o formulário for acionado.

Finalmentes

Estas alterações tornam possível apresentar as telas de edição e adição de novas mensagens. Se você fizer todas estas alterações "no braço", então basta se logar na área administrativa e testar o componente com estas novas funcionalidades. A tela para adicionar uma mensagem deve mostrar

Fig. 2 - Tela para adicionar mensagem

e a tela para editar uma mensagem será

Fig. 3 - Tela para editar mensagem

Mas... e sempre tem um mas, ainda não é possível atualizar a base de dados. Veja no próximo tutorial como fazer isto.

Só falta mais um tiquinho para terminar esta maratona de componentes Joomla 1.5 MVC. Se você conseguiu chegar até aqui, duvido que vá desistir antes do último tutorial da série.

Ah! Antes que me esqueça. Aqui está o arquivo zipado desta última versão. Faça o download de com_ola.1.5.zip vovo Vicki