Views, temas e widgets · Documentação do Koshkil

Temas

Um tema é uma pasta de webroot/themes/ com os templates Smarty e os recursos de uma aparência. O site público usa o definido em Templates.Theme; o painel usa inspinia (definido pelo AdminSuperController).

webroot/themes/<tema>/
├── css/  js/  img/             recursos (Koshkil::getThemePath('css/theme.css'))
└── templates/
    ├── front/                  templates do site ($templateFolder = "front")
    │   ├── main.tpl            layout
    │   ├── index/index.tpl     IndexController::index()
    │   └── cuentas/…
    ├── admin/                  templates do painel
    ├── widgets/
    │   └── front/header.tpl    widget THeader do grupo "front"
    └── error/                  error.tpl, error404.tpl, error4xx.tpl, error500.tpl

Para criar um tema novo, copie um existente (por exemplo brillare) e altere Templates.Theme na configuração do domínio.

Onde os templates são procurados

A view procura primeiro em templates/<templateFolder>/ e depois em templates/. Assim, index/index.tpl é resolvido em templates/front/index/index.tpl, e error/error404.tpl em templates/error/. Dentro de um plugin, são usados os templates de plugins/<plugin>/webroot/templates/.

Os templates compilados ficam em tmp/cache/view/<tema>/.

O layout

Controller::$templateFile (normalmente main.tpl) é a página completa. Recebe em $template o template da ação e o inclui:

{* templates/front/main.tpl *}
<!DOCTYPE html>
<html lang="pt">
<head>
  <meta charset="utf-8">
  <title>{if $webpageTitle}{$webpageTitle} · {/if}{Configure::read('Web.SiteName')}</title>
  <link rel="stylesheet" href="{Koshkil::getThemePath('css/theme.css')}">
  {foreach Configure::read('styles') as $style}<link rel="stylesheet" href="{$style}">{/foreach}
  <script src="https://code.jquery.com/jquery-1.12.4.min.js"></script>
  <script>var MAIN_URL='{Koshkil::GetLink('/')}';</script>
</head>
<body>
  {html_widget type="front.header"}
  <main{if $data_controller} data-controller="{$data_controller}"{/if}>
    {html_include file="{$template}"}
  </main>
  {html_widget type="front.footer"}
  {html_widget type="front.scripts"}
</body>
</html>

Nos templates estão disponíveis todas as variáveis definidas com $this->set(), além de $usuario (se houver sessão), $Response e $_SERVER. As classes estáticas podem ser chamadas diretamente: {Koshkil::getLink('/')}, {Configure::read('Web.SiteName')}.

Scripts e estilos por página

O controlador adiciona arquivos que o layout e o widget de scripts imprimem:

WebElements::addScript(Koshkil::getThemePath('js/productos.js'));
WebElements::addScript('https://www.google.com/recaptcha/api.js');
WebElements::addScript('/js/primeiro.js', true);   // no início da lista
WebElements::addStyle('/css/plugins/datatables.css');

Eles se acumulam em Configure::read('scripts') e Configure::read('styles') sem duplicados. Com Debug.Javascript em false, se existir arquivo.min.js, essa versão é usada.

Widgets

Um widget é um componente de interface com lógica e template próprios: cabeçalho, rodapé, menu, busca…

{html_widget type="front.header"}
{html_widget type="admin.uploads" name="galeria"}
{html_widget type="plugins.noticias.front.noticias"}   {* widget de um plugin *}

`type`	Classe	Arquivo	Template
`front.header`	`THeader`	`src/Widgets/front/THeader.php`	`templates/widgets/front/header.tpl`
`admin.uploads`	`TUploads`	`src/Widgets/admin/TUploads.php`	`templates/widgets/admin/uploads.tpl`
`plugins.noticias.front.noticias`	`TNoticias`	`plugins/noticias/src/Widgets/Front/TNoticias.php`	`plugins/noticias/webroot/templates/widgets/front/noticias.tpl`

<?php
// src/Widgets/front/TDestacados.php
Koshkil::Uses('sys.web.TWidget');
Koshkil::UsesModel('productos');

class TDestacados extends TWidget {
    public function run() {
        $quantidade = intval($this->parameters['cantidad'] ?? 4);
        $this->set([
            'destacados' => TMProductos::where('prd_destacado', '1')->take($quantidade)->get(),
        ]);
    }
}

{html_widget type="front.destacados" cantidad=6}

O widget executa create(), init() e run(); init() configura as pastas de templates, então, se sobrescrevê-lo, chame parent::init(). Os parâmetros da tag chegam em $this->parameters, e o template também recebe todas as variáveis do controlador.

Plugins de Smarty incluídos

Ficam em src/Smarty/plugins/ e são registrados automaticamente.

Tag	Tipo	Uso
`{html_include file="…"}`	função	Inclui um template relativo à pasta do tema; se não existir, exibe `error/error404.tpl`. Aceita `plugin="nome"`.
`{html_widget type="…"}`	função	Executa um widget.
`{t key="…" domain="…"}`	função	Tradução (veja Internacionalização).
`{trans}chave{/trans}`	bloco	Tradução em bloco.
`{rule_or_role roles="…" rules="…"}…{/rule_or_role}`	bloco	Exibe o conteúdo somente se o usuário tiver o papel ou a regra.
`{field_maxlength model="…" field="…"}`	função	Imprime `maxlength="N"` de acordo com o tamanho da coluna.
`{call_method name="…"}`	função	Chama um método público do controlador.
`{include_plugins folder="…"}`	função	Inclui os templates dessa pasta de todos os plugins ativos.
`{include_plugins_scripts file="…"}`	função	Imprime o `<script>` desse arquivo em todos os plugins ativos.
`\|t`	modificador	Tradução: `{'save'\|t}` (domínio `common`).
`\|formatdate:"DD/MM/YYYY"`	modificador	Formato de data com nomes em espanhol (`DDDD`, `MMMM`, `HH`, `mm`…).
`\|elapsed`	modificador	Tempo decorrido desde uma data.
`\|excerpt:120`	modificador	Resumo de um texto.
`\|slug`	modificador	Texto próprio para URL.
`\|decamelize`, `\|php_strtolower`, `\|php_ucwords`, `\|replace_str`	modificadores	Utilitários de texto.
`\|php_json_encode`, `\|php_base64_encode`	modificadores	Codificação.
`\|gravatar`	modificador	URL do avatar Gravatar de um e-mail.

Para adicionar os seus, crie src/Smarty/plugins/function.minhafuncao.php (ou modifier., block.) com a função smarty_function_minhafuncao($params, $template).

Escape o que vem do usuário

O Smarty não escapa por padrão. Use {$variavel|escape} para todo texto digitado por usuários.