Sintaxe de galho

Os complementos mestres Construtor de widgets renderiza o HTML, CSS e JavaScript do seu widget por meio de um Mecanismo de modelo de sintaxe dupla. Se você tocou no Twig in Timber ou no Craft CMS, a sintaxe parecerá familiar: {{ tokens }} imprima valores de campo, {% if %} os blocos mostram ou ocultam a marcação e {% for %} os loops passam pelas linhas repetidoras.

Este é um subconjunto seguro incorporado no plugin, não a biblioteca completa do Twig Não há eval e nenhum PHP compilado por trás dele, e cada valor impresso é escapado com base em seu tipo de campo Você obtém as partes do Twig que importam para modelos de widget, sem as partes que poderiam transformar um construtor de páginas em um problema de segurança.

Onde você escreve o código do modelo #

O editor Widget Builder possui três guias de código e o mecanismo é executado em todas elas:

• HTML: a marcação do seu widget Tokens, condições e loops vivem aqui.
• CSS: os estilos do seu widget Os tokens funcionam dentro dos valores das propriedades, para que um campo Color possa ser alimentado background: diretamente.
• JS: javascript opcional. Tokens funcionam aqui também, o que é útil para passar valores de campo em um script.

Cada controle que você adiciona ao painel de opções do widget se torna uma variável de modelo com o nome do campo Nome configuração. Adicionar um Campo texto nomeado title e {{ title }} imprime o que quer que o usuário digitou A barra lateral Documentação ao lado do editor de código lista o token para cada campo como você adicioná-lo, para que você nunca tenha que adivinhar a ortografia.

Nota: o modelo HTML é renderizado em todas as compilações, mas a saída CSS e JS é fornecida com Complementos mestres Pro, igual ao próprio Widget Builder completo.

Imprimindo valores com tokens #

O modelo mais simples é o markup plus tokens:

<div class="hero">
  <h2>{{ title }}</h2>
  <p>{{ description }}</p>
  <a href="{{ button_link }}">{{ button_text }}</a>
</div>

Algumas regras que vale a pena conhecer:

• Caminhos pontilhados alcance valores estruturados: {{ item.name }} dentro de um loop, ou {{ tabs.tab_1.person }} para um controle Tabs.
• Os campos de mídia imprimem seu URL. Quando um token contém uma matriz de imagem ou vídeo, o mecanismo emite o url parte automaticamente, então <img src="{{ photo }}"> só funciona.
• Escapar segue o tipo de campo. Os campos URL passam por escape de URL, os campos WYSIWYG e Code permitem HTML seguro e todo o resto é ignorado pelo HTML Você não precisa higienizar nada sozinho.

Filtros #

Anexe um filtro a um token com o caractere pipe O motor suporta cinco:

• {{ title|upper }} imprime o valor em UPPERCASE.
• {{ title|lower }} imprime em minúsculas.
• {{ title|trim }} retira espaços em branco de ambas as extremidades.
• {{ content|raw }} pula escapar e imprime o valor como está.
• {{ content|e }} (ou |escape) forças escapando de volta depois de a raw.

Tratar |raw como uma ferramenta afiada Ele existe para casos em que um campo intencionalmente mantém marcação, e usá-lo em um campo de texto simples significa o que quer que um editor de página digite terras em sua página sem escape Se o campo é um WYSIWYG ou tipo de Código que você raramente precisa raw de todo, uma vez que esses tipos já permitem tags HTML seguras.

Marcação condicional com blocos if #

Um {% if %} block renderiza seu conteúdo somente quando a condição passa Este é o parceiro front-end da opção Condições do lado do painel: As condições ocultam o controle no painel Elementor e o if block remove a marcação correspondente da página.

{% if show_badge %}
  <span class="badge">{{ badge_text }}</span>
{% endif %}

Uma variável simples é verificada quanto à veracidade, estilo Twig: strings vazias, 0, listas vazias e valores não definidos contam como falsos. Desde a Campo alternador lojas yes quando ligado e um valor vazio quando desligado, {% if show_badge %} é tudo que você precisa para alternar.

A ramificação completa também funciona:

{% if layout == "card" %}
  <div class="item item--card">...</div>
{% elseif layout == "list" %}
  <div class="item item--list">...</div>
{% else %}
  <div class="item">...</div>
{% endif %}

Operadores que você pode usar em condições #

• Comparações: ==, !=, >, <, >=, <=. Os valores são comparados como números quando ambos os lados são numéricos, caso contrário, como texto.
• Lógica: and, or, not, escrito em palavras minúsculas.
• Literais: strings citadas ("card" ou 'card'), números, true, false, e null.

Combine-os livremente: {% if show_price and price > 0 %}, ou {% if not hide_footer %}, ou {% if plan == "pro" or plan == "agency" %}.

Percorrendo linhas repetidoras #

O Campo repetidor é onde {% for %} ganha sua torre de menagem. Um repetidor nomeado menu_items com subcampos dish, price, e photo renderiza assim:

<ul class="menu">
{% for item in menu_items %}
  <li class="menu__row">
    <img src="{{ item.photo }}" alt="{{ item.dish }}">
    <span class="menu__dish">{{ item.dish }}</span>
    <span class="menu__price">{{ item.price }}</span>
  </li>
{% endfor %}
</ul>

A variável de loop (aqui item(mas qualquer palavra funciona) mantém uma linha de cada vez, e cada sub-campo está disponível através de um caminho pontilhado sob o nome que você deu a ele As condições funcionam dentro de loops, então as alternâncias por linha estão a um bloco aninhado de distância:

{% for member in team %}
  <div class="member">
    <h3>{{ member.name }}</h3>
    {% if member.role %}<p class="role">{{ member.role }}</p>{% endif %}
  </div>
{% endfor %}

Leitura de guias e campos Popover #

Dois controles estruturais expõem seus valores filhos por meio de formatos de token especiais:

• Guias: as crianças são lidas com um caminho de três partes: {{ tabs_name.tab_name.field_name }}. Um controle de guias nomeado tabs com a tab_1 aba segurando um person impressões de campo como {{ tabs.tab_1.person }}. Nenhum loop necessário.
• Alternar Popover: cada campo dentro do popover recebe um token combinado: o nome do toggle, um sublinhado e, em seguida, o nome do campo Um popover nomeado overlay com um opacity campo dentro das impressões como {{ overlay_opacity }}.

Tokens em CSS #

A guia CSS é executada pelo mesmo mecanismo, portanto, os campos de estilo são conectados diretamente aos valores das propriedades:

.hero {
  background: {{ bg_color }};
  color: {{ text_color }};
}

{% if enable_shadow %}
.hero {
  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.18);
}
{% endif %}

Um if bloquear em torno de uma regra inteira é uma maneira limpa de enviar um estilo opcional: a regra só existe na saída quando a alternância está ativada. Um campo de mídia também funciona aqui, por exemplo background-image: url("{{ hero_image }}");, uma vez que o token é resolvido para o URL do arquivo.

Tokens em JavaScript #

A guia JS permite passar valores de painel para um script. Citar valores de string e confiar na veracidade para alternâncias:

var speed = {{ slide_speed }};
var autoplay = "{{ autoplay }}" === "yes";

if (autoplay) {
  startSlider(speed);
}

Os valores impressos no JS são escapados como qualquer outro token, portanto, um usuário não pode sair do seu script digitando aspas em um campo de texto.

Receitas práticas #

Alguns padrões que surgem em quase todos os widgets:

• Segundo botão opcional: envolva toda a âncora {% if second_button_text %} assim, o botão desaparece quando o campo de texto está vazio Nenhum switcher necessário.
• Classe de layout de um Select: imprima o campo diretamente no atributo de classe: <div class="pricing pricing--{{ layout }}">, então estilo cada variante em CSS.
• Conteúdo de fallback: {% if caption %}{{ caption }}{% else %}Untitled{% endif %} evita que a marcação renderize elementos vazios.
• Níveis de preços numerados: {% if price >= 100 %}<span class="premium-tag">Premium</span>{% endif %} reage ao valor de um campo Número.
• Etiquetas maiúsculas: {{ eyebrow|upper }} deixa o CSS ficar livre de text-transform quando o design exige tampas em apenas um ponto.
• Galerias, menus, cronogramas e depoimentos orientados por repetidores: uma {% for %} loop mais um repetidor substitui um número fixo de blocos colados.

O que o motor não suporta #

Conhecer as bordas economiza tempo de depuração. Este é um subconjunto deliberado, portanto, alguns recursos do Twig completo estão ausentes:

• Não {% set %}, macros, inclui ou herança de modelo.
• Nenhuma matemática dentro das expressões: compare valores, mas calcule em CSS calc() ou na guia JS.
• Sem filtros além raw, escape/e, upper, lower, e trim.
• Não loop.index ou outros metadados de loop internos {% for %}.
• Sem parênteses para lógica de agrupamento Encomende o seu and/or cadeias para que leiam corretamente ou se dividam em aninhadas if blocos.

Se um modelo precisar de uma lógica mais pesada do que esta, isso geralmente é um sinal para mover a decisão para o painel, por exemplo, um campo Selecionar cujas opções carregam os valores que você estava tentando calcular.

Perguntas frequentes #

Embrulhando #

O mecanismo de sintaxe Twig é o que conecta os campos do Widget Builder à sua marcação: {{ tokens }} valores do painel de impressão, {% if %} remove a marcação opcional quando ela é desligada e {% for %} deixa um bloco de HTML servir um repetidor ilimitado Comece com tokens simples, adicione um bloco if para sua primeira alternância, depois gradue para loops quando um design se repetir A partir daí, o Repetidor, Selecione, e Comutador os campos cobrem a maioria dos widgets dinâmicos que você precisará construir. Novo para o próprio construtor? O Visão geral do Widget Builder caminha pelo editor e pelo página preços mostra o que cada plano inclui.