Modelos de servidor
Parciais prontas do SEMEC Design System para PHP, Laravel, Symfony, Django e Flask: a tela sai com o mesmo HTML, o mesmo visual e a mesma acessibilidade dos componentes React.
O @semec/ds-css traz, além das classes, a pasta templates/ com onze parciais em quatro linguagens: PHP puro, Jinja2, Twig e Blade. Os nomes e os parâmetros são os mesmos nas quatro, e todas geram o HTML recomendado nas instruções para usar sem React, com rótulo, dica, erro e aria-* já ligados. Você passa os dados; a parcial cuida da marcação e do escape.
Parciais
| Parcial | O que gera |
|---|---|
pagina | Layout base: lang pt-BR, CSS, fontes, script do @semec/ds-elements, pular para o conteúdo, cabeçalho, <main id="conteudo"> e rodapé. |
pular-para-o-conteudo | Link "Pular para o conteúdo principal", primeiro elemento focável. |
cabecalho | Marca, órgão, serviço e menu, com aria-current="page" no item atual. |
rodape | Seções de links e a linha final. |
campo | input, textarea ou select com rótulo, obrigatório, dica, erro, aria-describedby e aria-invalid. |
combobox | Campo de escolha com filtro: um <select> dentro do <semec-combobox>, com rótulo, dica e erro. |
radio-grupo | Grupo de rádios em <fieldset> com <legend>, dica e erro. |
checkbox | Uma caixa de marcação (declaração, aceite) ou um grupo delas em <fieldset>. |
resumo-de-erros | Lista de links para os campos com erro, focada quando a página volta do envio. |
alerta | Aviso info, success, warning ou danger, com o ícone e o role do Alert do kit. |
botao | <button> ou link com aparência de botão, nas variantes e tamanhos do Button; aceita os gatilhos do @semec/ds-elements em atributos. |
Instalação
npm install @semec/ds-css @semec/ds-elementsOs modelos ficam em node_modules/@semec/ds-css/templates/. Copie a pasta da sua linguagem para o projeto e publique na pasta pública o dist/semec-ds.css do @semec/ds-css, o dist/fonts.css com a pasta dist/fonts/ do @semec/ds-tokens e o dist/semec-elements.js do @semec/ds-elements. O layout procura esses arquivos em /css/semec-ds.css, /css/fonts.css e /js/semec-elements.js; mude com os parâmetros css_href, fontes_href e elements_src.
| Sistema | Pasta | Chamada |
|---|---|---|
| PHP puro | templates/php | semec_render('campo', [...]) |
| Django (django-jinja) e Flask | templates/jinja | {{ campo(id="cpf", ...) }} |
| Symfony, Slim (Twig) | templates/twig | {% include '@semec/campo.html.twig' with {...} only %} |
| Laravel (Blade) | templates/blade | @include('semec::campo', [...]) |
Ao atualizar o pacote, copie a pasta de novo: os modelos acompanham as classes da mesma versão do CSS.
PHP puro
Inclua o semec.php uma vez. semec_render() devolve o HTML da parcial; o conteúdo da página é uma função que imprime o HTML do seu app. Os exemplos desta página usam um único mapa campo → mensagem ($erros) para o resumo e para cada campo: vazio, nada aparece. Os quatro exemplos rodam como estão no teste dos modelos.
<?php
require __DIR__ . '/semec/semec.php'; // templates/php copiado para ./semec
// Um só mapa campo => mensagem serve ao resumo e a cada campo.
$dados = $_POST;
$erros = [];
if ($_SERVER['REQUEST_METHOD'] === 'POST' && trim($dados['cpf'] ?? '') === '') {
$erros['cpf'] = 'Informe o CPF.';
}
echo semec_render('pagina', [
'titulo' => 'Transferência escolar — SEMEC',
'cabecalho' => [
'marca_src' => '/img/marca.svg', // a marca oficial, servida pelo seu app
'servico' => 'Matrícula e transferência',
'nav' => [['href' => '/transferencia', 'texto' => 'Transferência', 'atual' => true]],
],
'conteudo' => function () use ($erros, $dados) {
echo '<h1 class="semec-heading semec-heading--1">Solicitar transferência</h1>';
echo semec_render('resumo-de-erros', ['erros' => $erros]);
echo '<form method="post" novalidate>';
echo semec_render('campo', [
'id' => 'cpf', 'rotulo' => 'CPF', 'obrigatorio' => true,
'valor' => $dados['cpf'] ?? '', 'erro' => $erros['cpf'] ?? null,
'dica' => 'Somente números.',
'atributos' => ['inputmode' => 'numeric', 'maxlength' => 11],
]);
echo semec_render('botao', ['texto' => 'Enviar', 'tipo' => 'submit']);
echo '</form>';
},
]);A função do conteudo só enxerga as variáveis do use (...); se faltar uma, o PHP não avisa por causa do ??. O resumo também aceita a lista [['campo' => 'cpf', 'mensagem' => '…']]; item sem campo ou sem mensagem não vira link.
Django e Flask (Jinja2)
Copie templates/jinja para uma pasta semec/ dentro do diretório de templates. No Django, use o django-jinja (os arquivos .jinja vão para o motor Jinja2); no Flask, a pasta templates/, com o autoescape configurado (abaixo).
{% extends "semec/pagina.jinja" %}
{% from "semec/campo.jinja" import campo %}
{% from "semec/botao.jinja" import botao %}
{% from "semec/resumo-de-erros.jinja" import resumo_de_erros %}
{% block conteudo %}
<h1 class="semec-heading semec-heading--1">Solicitar transferência</h1>
{{ resumo_de_erros(erros=erros) }}
<form method="post" novalidate>
{{ campo(id="cpf", rotulo="CPF", obrigatorio=true, valor=dados.get("cpf"), erro=erros.get("cpf"), dica="Somente números.", atributos={"inputmode": "numeric", "maxlength": 11}) }}
{{ botao(texto="Enviar", tipo="submit") }}
</form>
{% endblock %}A view passa erros (o mapa, vazio quando não há erro), dados ({} no primeiro acesso) e os parâmetros do layout, por exemplo render(request, "transferencia.jinja", {"titulo": …, "cabecalho": {…}, "erros": erros, "dados": dados}). No Django, ponha {{ csrf_input }} dentro do <form>. As macros têm o nome da parcial com _ no lugar de -. Funciona com StrictUndefined (use .get() para chave que pode faltar).
from jinja2 import select_autoescape
app.jinja_env.autoescape = select_autoescape(["html", "htm", "xml", "xhtml", "jinja"])No Django com django-jinja, a extensão .jinja precisa estar no match_extension e o motor com "autoescape": True (o padrão do django-jinja).
Symfony e Slim (Twig)
Registre a pasta com o namespace semec: no Symfony, twig.paths no config/packages/twig.yaml; no Twig puro, $loader->addPath($pasta, 'semec').
{% extends '@semec/pagina.html.twig' %}
{% block conteudo %}
<h1 class="semec-heading semec-heading--1">Solicitar transferência</h1>
{% include '@semec/resumo-de-erros.html.twig' with {erros: erros} only %}
<form method="post" novalidate>
{% include '@semec/campo.html.twig' with {id: 'cpf', rotulo: 'CPF', obrigatorio: true, valor: dados.cpf|default(null), erro: erros.cpf|default(null), dica: 'Somente números.', atributos: {inputmode: 'numeric', maxlength: 11}} only %}
{% include '@semec/botao.html.twig' with {texto: 'Enviar', tipo: 'submit'} only %}
</form>
{% endblock %}Use sempre only, para a parcial não receber as variáveis da página. As parciais funcionam com strict_variables ligado.
Laravel (Blade)
Copie templates/blade para resources/views/vendor/semec e registre o namespace no AppServiceProvider: View::addNamespace('semec', resource_path('views/vendor/semec')).
@extends('semec::pagina')
@section('conteudo')
<h1 class="semec-heading semec-heading--1">Solicitar transferência</h1>
{!! view('semec::resumo-de-erros', ['erros' => array_map(fn ($m) => $m[0], $errors->getMessages())])->render() !!}
<form method="post" novalidate>
@csrf
{!! view('semec::campo', ['id' => 'cpf', 'rotulo' => 'CPF', 'obrigatorio' => true, 'valor' => old('cpf'), 'erro' => $errors->first('cpf') ?: null, 'dica' => 'Somente números.', 'atributos' => ['inputmode' => 'numeric', 'maxlength' => 11]])->render() !!}
{!! view('semec::botao', ['texto' => 'Enviar', 'tipo' => 'submit'])->render() !!}
</form>
@endsection{!! view('semec::…', [...])->render() !!} renderiza a parcial isolada; o {!! !!} só imprime o HTML que a parcial já escapou. Não use @include com as parciais: ele passa todas as variáveis da view, e o $titulo do layout viraria o título do resumo de erros; um $id, $tipo ou $erro mudaria o campo.
Combobox, rádios e checkbox
combobox: o<semec-combobox>envolve só o<select>, então a lista abre colada ao campo, não depois da dica ou do erro. Sem JavaScript, o select funciona sozinho; com o@semec/ds-elements, vira campo com filtro e o campo de busca assume oid(o link do resumo é#id).radio-grupoecheckboxcomopcoes:<fieldset>com<legend>, dica e erro ligados ao grupo. O primeiro controle leva oid(o link do resumo é#id); os outros,id-2,id-3…checkboxsemopcoes: uma caixa só, com o rótulo ao lado (declaração, aceite dos termos).
Atributos extras
campo e botao aceitam atributos, um mapa nome → valor: os gatilhos do @semec/ds-elements (data-semec-dialog-open, data-semec-menu-trigger…), aria-describedby e form num botão, inputmode, maxlength, pattern e rows num campo. Só valem nomes data-*, aria-* e uma lista de atributos de formulário; outros (on*, style, class, href) são ignorados, e o valor sai escapado. true gera o atributo sem valor.
Parâmetros
Os parâmetros são os mesmos nas quatro linguagens. Ausente, nulo ou vazio usa o padrão. Valor fora da lista (variante, tamanho, tipo) também volta ao padrão, então nenhum parâmetro vira classe ou atributo arbitrário. Os parâmetros do campo:
| Parâmetro | O que faz |
|---|---|
id | id do controle. A dica vira <id>-hint e o erro, <id>-error. |
rotulo | Texto do <label>. |
tipo | text (padrão), email, tel, number, date, password, url, search, textarea ou select. |
valor | Valor atual: value, conteúdo do textarea ou opção selecionada. |
obrigatorio | required no controle e * visual (aria-hidden) no rótulo. |
dica | Dica ligada por aria-describedby. Com erro, a dica sai, como no FormField do kit. |
erro | Mensagem de erro: marca aria-invalid="true" e entra no aria-describedby. |
opcoes, opcao_vazia | Opções do select ({valor, texto}) e a primeira opção vazia ("Selecione"). |
nome, autocomplete, desabilitado | name (padrão: o id), autocomplete e disabled. |
atributos | Mapa de atributos extras: inputmode, maxlength, pattern, rows, placeholder, data-* e aria-*. Outros nomes (on*, style, class, href) são ignorados; o valor sai escapado. |
A tabela completa, com todas as parciais, tipos e padrões, está no README dos modelos.
Segurança
- Toda saída é escapada:
htmlspecialcharscomENT_QUOTESno PHP, autoescape de HTML no Jinja, no Twig e no Blade. O Jinja e o Twig ligam o autoescape dentro de cada parcial, mesmo que o projeto o tenha desligado. Isso não protege a sua tela: no Flask, configure o autoescape para.jinja(veja acima). - Nenhum parâmetro aceita HTML. O conteúdo da página entra pelo bloco do template, escrito por você.
- Endereços (
href,marca_src) são escapados, mas não filtrados. Não use como link uma URL digitada pelo usuário sem validar o esquema.
Comportamento e acessibilidade
- O resumo de erros recebe
autofocus: quando o formulário volta do servidor com erros, o foco vai para ele, como noErrorSummarydo kit. Em envio por JavaScript, chamefocus()no resumo depois de inseri-lo. - Com erro, a mensagem substitui a dica e o campo recebe
aria-invalid="true". Mostre os erros no envio, não enquanto a pessoa digita (veja Mensagens de erro). - O layout carrega o
@semec/ds-elementscomo módulo. Os elementos<semec-*>(diálogo, abas, combobox, menu e acordeão) funcionam dentro do conteúdo sem outra configuração.
Como é testado
Cada parcial é renderizada nas quatro linguagens com os mesmos dados e comparada com um único HTML de referência. O mesmo teste roda o axe-core no Chromium (zero violações), confere cada classe contra a lista oficial do @semec/ds-css, injeta <script> e aspas em todos os textos e confere a tabela de parâmetros. Os exemplos desta página rodam como estão (com e sem erro), e um app Flask de verdade confirma a configuração de autoescape. Para rodar no monorepo:
npm run build:pacotes
npm run test:modelosO teste usa PHP 8.2+, Composer e Python 3 da máquina ou, sem eles, o Docker.
Para saber mais
- README dos modelos, com a tabela de parâmetros.
- Decisão: ADR-030 (modelos oficiais de servidor no
@semec/ds-css). - Usar sem React: pacotes, CDN e as classes
.semec-*.