View Cells (Células de Visualização)¶

Quando usar Cells¶

Cells são ideais para construir componentes de páginas reutilizáveis que requerem interação com modelos, lógica de visualização, e lógica de renderizaço. Um exemplo simples seria o carinho em uma loja online, ou um menu de navegação data-driven em um CMS.

Para criar uma cell, defina uma classe em src/View/Cell e um template em src/Template/Cell/. Nesse exemplo, nós estaremos fazendo uma cell para exibir o número de mensagens em uma caixa de notificações do usuário. Primeiro, crie o arquivo da classe. O seu conteúdo deve se parecer com:

namespace App\View\Cell;

use Cake\View\Cell;

class InboxCell extends Cell
{

    public function display()
    {
    }

}

Salve esse arquivo dentro de src/View/Cell/InboxCell.php. Como você pode ver, como em outras classes no CakePHP, Cells tem algumas convenções:

• As Cells ficam no namespace App\View\Cell. Se você está fazendo uma cell em um plugin, o namespace seria NomeDoPlugin\View\Cell.

• Os nomes das classes devem terminar com Cell.

• Classes devem herdar de Cake\View\Cell.

Nós adicionamos um método display() vazio para nossa cell; esse é o método padrão convencional quando a cell é renderizada. Nós vamos abordar o uso de outros métodos mais tarde na documentação. Agora, crie o arquivo src/Template/Cell/Inbox/display.ctp. Esse será nosso template para a nossa nova cell.

Vocẽ pode gerar este esboço de código rapidamente usando o bake:

bin/cake bake cell Inbox

Gera o código que digitamos acima.

namespace App\View\Cell;

use Cake\View\Cell;

class InboxCell extends Cell
{

    public function display()
    {
        $this->loadModel('Messages');
        $unread = $this->Messages->find('unread');
        $this->set('unread_count', $unread->count());
    }

}

<!-- src/Template/Cell/Inbox/display.ctp -->
<div class="notification-icon">
    Você tem <?= $unread_count ?> mensagen não lidas.
</div>

Carregando Cells¶

Cells podem ser carregadas nas views usando o método cell() e funciona da mesma forma em ambos os contextos:

// Carrega uma *cell* da aplicação
$cell = $this->cell('Inbox');

// Carrega uma *cell* de um plugin
$cell = $this->cell('Messaging.Inbox');

O código acima irá carregar a célula nomeada e executar o método display(). Você pode executar outros métodos usando o seguinte:

// Executa o método *Run* na *cell* *Inbox*
$cell = $this->cell('Inbox::expanded');

Se você precisa de lógica no controller para decidir quais cells serão carregadas em uma requisição, você pode usar o CellTrait no seu controller para habilitar o método cell() lá:

namespace App\Controller;

use App\Controller\AppController;
use Cake\View\CellTrait;

class DashboardsController extends AppController
{
    use CellTrait;

    // More code.
}

$cell = $this->cell('Inbox::recent', ['-3 days']);

public function recent($since)
{
}

Renderizando uma Cell¶

Uma vez a célula carregada e executada, você provavelmente vai querer renderizá-la. A maneira mais fácil para renderizar uma cell é dando um echo:

<?= $cell ?>

Isso irá renderizar o template correspondente a versão minuscula e separada com underscore do nome da nossa action, e.g. display.ctp.

Porque as cells usam View para renderizar templates, você pode carregar cells adicionais dentro do template da cell se necessário.

// Chamando render() explicitamente
echo $this->cell('Inbox::recent', ['-3 days'])->render('messages');

// Especificando o template antes de executar *echo* da *cell*
$cell = $this->cell('Inbox');
$cell->template = 'messages';
echo $cell;

// Faz cache usando a configuração padrão e uma chave gerada
$cell = $this->cell('Inbox', [], ['cache' => true]);

// Faz cache usando uma configuração especifica a uma chave gerada
$cell = $this->cell('Inbox', [], ['cache' => ['config' => 'cell_cache']]);

// Especificando a chave e a configuração utilizada
$cell = $this->cell('Inbox', [], [
    'cache' => ['config' => 'cell_cache', 'key' => 'inbox_' . $user->id]
]);