Biblioteca modelo.php

Caminho no Gestor bibliotecas/modelo.php

modelo.php é a biblioteca de templates do Gestor. Tudo o que o Conn2Flow desenha no servidor passa por ela: páginas, layouts, componentes e respostas de widgets são strings HTML em que o código troca marcadores por valores e recorta, repete ou remove blocos. Não há engine de templates, AST nem escape automático; são funções puras de string.

A biblioteca é carregada no bootstrap do Gestor e registra a própria versão em $_GESTOR['biblioteca-modelo'] (atualmente 1.1.0).

Os dois tipos de marcador

As funções não impõem formato. Elas procuram exatamente a string recebida. A convenção dos comentários de bloco é seguida pelos módulos do core e pelos widgets.

Substituir variáveis

Quando a variável não é encontrada, o modelo volta inalterado; não há erro nem aviso.

modelo_var_troca() e modelo_var_troca_tudo() também aceitam um array associativo no lugar de $var. Cada chave é usada literalmente como marcador; o # não é acrescentado, apesar do que diz o docblock da função:

$html = modelo_var_troca_tudo($html, [
    '#titulo#' => $titulo,
    '#url#'    => $url,
]);

modelo_var_troca_tudo() usa str_ireplace() de propósito. A versão antiga com preg_replace() tratava $19 no valor como referência de grupo e corrompia preços como $19.97.

Trabalhar com blocos

O padrão de repetição ("célula")

É assim que os módulos do core montam listas no servidor: extraem o bloco como modelo, deixam um marcador no lugar e inserem cada linha antes do marcador.

$cel_nome = 'linha';
// 1. Guarda o modelo e deixa um marcador no lugar do bloco.
$cel = modelo_tag_val($_GESTOR['pagina'], '<!-- '.$cel_nome.' < -->', '<!-- '.$cel_nome.' > -->');
$_GESTOR['pagina'] = modelo_tag_in($_GESTOR['pagina'], '<!-- '.$cel_nome.' < -->', '<!-- '.$cel_nome.' > -->', '<!-- '.$cel_nome.' -->');
// 2. Para cada registro, preenche uma cópia e a insere antes do marcador (a ordem se mantém).
foreach ($registros as $r) {
    $linha = modelo_var_troca_tudo($cel, '#nome#', htmlspecialchars($r['nome']));
    $_GESTOR['pagina'] = modelo_var_in($_GESTOR['pagina'], '<!-- '.$cel_nome.' -->', $linha);
}
// 3. Remove o marcador.
$_GESTOR['pagina'] = modelo_var_troca($_GESTOR['pagina'], '<!-- '.$cel_nome.' -->', '');

O mesmo par de funções resolve blocos condicionais: modelo_tag_del() apaga a seção quando a condição é falsa. É o que faz, por exemplo, o módulo publisher com as mensagens templates-todos-linkados-msg.

Funções legadas

• modelo_abrir($modelo_local) lê um arquivo e remove o bloco de desenvolvimento <!--!#del#(#!--> … <!--!#del#)#!-->. Não tem chamadores no core: templates vivem no banco e em resources/, não em arquivos lidos em runtime. Também só remove o primeiro bloco.

• modelo_input_in($modelo, $in, $out, $valor) chama paginaTrocaVarValor(), que não existe no core. Chamá-la causa erro fatal. Não tem chamadores; não use.

Veja também

• Módulo menus: um widget que usa blocos <!-- item < --> com regras próprias.

• Como escrever documentação

Funções

modelo_input_in(string $modelo, string $name_input_in, string $name_input_out, string $valor): string

modelo_var_troca(string $modelo, string|array $var, string $valor = null): string

modelo_var_troca_fim(string $modelo, string $var, string $valor): string

modelo_var_troca_tudo(string $modelo, string|array $var, string $valor = null): string

modelo_var_in(string $modelo, string $var, string $valor): string

modelo_tag_val(string $modelo, string $tag_in, string $tag_out): string

modelo_tag_in(string $modelo, string $tag_in, string $tag_out, string $valor): string

modelo_tag_del(string $modelo, string $tag_in, string $tag_out): string

modelo_tag_troca_val(string $modelo, string $tag_in, string $tag_out, string $valor): string

modelo_abrir(string $modelo_local): string