Views

1Apresentação

A view é a camada de software responsável por formatar os dados retornados pelo servidor após o processamento.

Por padrão, o Temma usa o motor de templates Smarty, que facilita muito a geração de páginas HTML a partir dos dados exportados pelos controladores.

O Temma também oferece nativamente uma view usada para gerar feeds JSON, o que pode ser muito prático no contexto de comunicações AJAX, além de views que oferecem exportações CSV, RSS, INI e iCal.

2Usando uma view com template

Algumas views usam templates para processar os dados e gerar os fluxos de saída. Como visto na introdução, o Temma procurará um arquivo cujo nome corresponda ao da ação solicitada (com a extensão ".tpl"), localizado em um diretório cujo nome é o do controlador em execução; tudo isso dentro do diretório templates/ do projeto.

Para contornar esse comportamento automático, uma ação pode especificar o template a ser usado:

class User extends \Temma\Web\Controller {
    public function list($type=null) {
        // processamentos...

        // redefinindo o template em um caso particular
        if ($type == 'all')
            $this->_template('user/listAll.tpl');
        // nos demais casos, o template será "user/list.tpl"
    }
}

3Definição da view

É possível especificar a view a ser usada, individualmente para cada ação.

Aqui está um exemplo de uma ação cujos dados são exportados no formato JSON:

class User extends \Temma\Web\Controller {
    public function get($id) {
        // processamentos...

        // define os dados que serão enviados
        // no fluxo JSON
        $this['json'] = $data;

        // definição da view usada
        $this->_view('\Temma\Views\Json');
    }
}

Quando a view usada é uma view padrão (fornecida pelo Temma), é possível abreviar sua escrita usando o caractere til (~) para substituir o prefixo \Temma\Views\:

class User extends \Temma\Web\Controller {
    public function get($id) {
        // processamentos...
        $this->_view('~Json');
    }
}

O Temma também oferece o atributo \Temma\Attributes\View, que facilita a definição da view a ser usada para todas as ações de um controlador e/ou para ações específicas:

use \Temma\Attributes\View as TµView;

// controlador que usa a view JSON por padrão
#[TµView('~Json')]
class User extends \Temma\Web\Controller {
    // ação que usa a view JSON definida no nível do controlador
    public function get($id) {
        // processamentos...
    }

    // ação que usa especificamente a view RSS
    #[TµView('~Rss')]
    public function stream() {
        // processamentos...
    }
}

4Transmitindo dados para a view

Para transmitir dados para a view, existem dois comportamentos básicos:

Para views baseadas em template (Smarty e PHP), todas as variáveis de template previamente definidas (com $this['variable'] = $value;) são passadas para o template, desde que o nome da variável não comece com um sublinhado (com a notável exceção das variáveis flash, cujo nome começa com dois sublinhados).
Outras views esperam uma ou mais variáveis de template específicas da view (json, csv, data, ical).

Exemplos:

class User extends \Temma\Web\Controller {
    // usando a view Smarty padrão
    public function get(int $id) {
        // processamentos...

        // usando variáveis de template separadas
        $this['user'] = $user;
        $this['activity'] = $activity;
    }

    // usando a view JSON
    #[TµView('~Json')]
    public function getActivity(int $id) {
        // processamentos...

        // usando a variável de template "json"
        $this['json'] = $activity;
    }
}

Também é possível definir os dados a serem transmitidos para a view atribuindo-os à variável de template @output. Se essa variável estiver definida, a view a usa em prioridade em vez da variável específica da view.
Para views baseadas em template (Smarty e PHP), se @output estiver definido, ele deve conter um array associativo cujos pares chave-valor serão usados como variáveis de template. Se @output não estiver definido, o comportamento usual é preservado.

Exemplos:

class User extends \Temma\Web\Controller {
    // usando a view Smarty padrão
    public function get($id) {
        // processamentos...

        // definindo variáveis de template via @output
        $this['@output'] = [
            'user'     => $user,
            'activity' => $activity,
        ];
    }

    // usando a view JSON
    #[TµView('~Json')]
    public function getActivity(int $id) {
        // processamentos...

        // os dados são transmitidos para a view via @output
        $this['@output'] = $activity;
    }
}

5Configuração da view padrão

Você tem a possibilidade de alterar a view padrão, modificando o arquivo de configuração etc/temma.php.

Por exemplo, se você criar um webservice, nunca enviará HTML, mas sempre JSON. Você então vai querer usar a view \Temma\Views\Json em vez da view Smarty usual; para isso, é preciso adicionar a diretiva defaultView no arquivo etc/temma.php:

<?php

return [
    'application' => [
        // configuração usual (dsn, defaultController, ...)

        // configuração da view padrão
        'defaultView' => '\Temma\Views\Json'
    ]
];

Como visto acima, é possível substituir o prefixo \Temma\Views\ pelo caractere til (~):

<?php

return [
    'application' => [
        // configuração da view padrão
        'defaultView' => '~Json'
    ]
];

6Definindo cabeçalhos HTTP padrão

No arquivo de configuração etc/temma.php, você pode especificar os cabeçalhos HTTP a serem enviados com cada resposta, listando-os com a chave default na configuração estendida x-headers. Eles podem ser escritos como pares chave-valor ou como strings contendo o nome do cabeçalho e seu valor:

<?php

return [
    'x-headers' => [
        // cabeçalhos HTTP padrão
        'default' => [
            'Cache-Control' => 'no-cache',
            'Sec-Purpose: prefetch',
        ]
    ]
];