Tecnologias - Yampi Developer Portal

O Tema Rocket é construído sobre três tecnologias que trabalham em camadas complementares. Entender o papel de cada uma é fundamental para fazer qualquer personalização no Editor de Código.

Twig
Vue.js
SASS

Twig é uma linguagem de templates server-side: você escreve HTML com marcações especiais ({{ }}, {% %}) e o servidor as substitui pelos dados reais antes de entregar a página ao navegador.

Acessando dados da loja

Os objetos mais comuns disponíveis nos templates são:

{{ merchantData.manifest.name }}  {# Nome da loja #}
{{ merchantData.domain }}         {# Domínio principal da loja #}
{{ product.name }}                {# Nome do produto (páginas de produto) #}
{{ pageConfig.page }}             {# Identificador da página atual (ex: 'product') #}

Algumas propriedades só existem em determinadas páginas. Use default para evitar erros quando o dado não está disponível:

{{ product.texts.description | default('') }}  {# Descrição pode estar vazia #}
{{ product.brand.logo_url | default('') }}     {# Marca pode não ter logo #}

Consulte a referência completa em Objetos.

Compondo páginas com seções e elementos

Os templates do Tema Rocket montam cada página incluindo seções e elementos reutilizáveis:

{% include 'elements/header.twig' %}
{% include 'sections/banner.twig' %}
{% include 'sections/product-list.twig' %}

Iterando sobre dados da loja

Exibindo categorias disponíveis na loja:

<ul class="category-list">
    {% for category in categories %}
        <li>
            <a href="{{ category.url_path }}">{{ category.name }}</a>
        </li>
    {% endfor %}
</ul>

Exibindo produtos de uma listagem (páginas de categoria, busca ou promoção):

{% for item in content.data %}
    <div class="product-item">
        <h3>{{ item.name }}</h3>
        <p>{{ item.prices.price_formated }}</p>
    </div>
{% endfor %}

Usando configurações do Editor de Temas

Os parâmetros configurados pelo merchant no Editor de Temas ficam disponíveis em pageConfig.theme.params (parâmetros gerais do tema) e em section.params (parâmetros específicos de cada seção):

{% if pageConfig.theme.params.show_banner %}
    <div class="banner">
        <img src="{{ pageConfig.theme.params.banner_image }}" alt="Banner">
    </div>
{% endif %}

{% if section.params.show_title %}
    <h2>{{ section.params.title }}</h2>
{% endif %}

Passando dados para componentes Vue

O padrão do Tema Rocket é passar dados da loja como props para componentes Vue diretamente nos atributos Twig:

<product-info
    :name="{{ product.name }}"
    :has-promotion="{{ product.prices.has_promotion | bool_text }}">
</product-info>

Filtros específicos da Yampi

Filtro	O que faz
`vendor_url`	Gera URL completa para um arquivo estático do tema
`assets_url`	Gera link completo para um asset (imagem, JS, etc.)
`thumborize`	Gera thumbnail redimensionada para uma imagem
`mask`	Formata um texto seguindo uma máscara (ex: CEP, telefone)
`json_decode`	Converte uma string JSON em array
`font_link`	Gera link do Google Fonts para a fonte especificada

Consulte a lista completa em Filtros e Funções.

Boas práticas

Proteja acessos que podem ser nulos. Algumas propriedades só existem em determinadas páginas. Use default para evitar erros de renderização:

{# ✅ Correto #}
{{ product.texts.description | default('') }}

{# ❌ Pode quebrar se a propriedade não existir #}
{{ product.texts.description }}

Use bool_text para booleanos em props Vue. Evita ternários e mantém o template legível:

{# ✅ Correto #}
:has-promotion="{{ product.prices.has_promotion | bool_text }}"

{# ❌ Evite #}
:has-promotion="{{ product.prices.has_promotion ? 'true' : 'false' }}"

Mantenha a lógica no Vue. O Twig é para estrutura e dados — lógica complexa pertence ao componente:

{# ✅ Twig entrega dados, Vue decide o que fazer #}
<product-price
    :price="{{ product.prices.price }}"
    :has-promotion="{{ product.prices.has_promotion | bool_text }}">
</product-price>

{# ❌ Lógica de apresentação no Twig — difícil de manter #}
{% if product.prices.has_promotion %}
    <span class="price--promo">{{ product.prices.price_formated }}</span>
{% else %}
    <span class="price">{{ product.prices.price_formated }}</span>
{% endif %}

Vue.js é um framework JavaScript progressivo para construir interfaces interativas. Com ele, você cria componentes reativos que respondem em tempo real às ações do usuário, sem recarregar a página.

O editor utiliza Vue 2. Consulte a documentação oficial do Vue 2 para referências completas.

Usando um componente em um template Twig

A tag HTML do componente no Twig é definida pela propriedade name do componente Vue — convertida automaticamente para kebab-case:

<!-- components/MeuComponente.vue -->
<script>
export default {
    name: 'MeuComponente',
};
</script>

{# Em qualquer arquivo .twig #}
<meu-componente :product-id="{{ product.id }}"></meu-componente>

Acessando dados da loja no componente

O backend injeta os dados da loja em variáveis globais acessíveis dentro de qualquer componente Vue:

window.merchant      // Configurações da loja, frete, redes sociais
window.product       // Dados do produto atual (somente em páginas de produto)
window.Yampi         // Dados da sessão: carrinho, UTM e informações do cliente

Consulte todos os dados disponíveis em Variáveis JavaScript.

Padrão de componente do Tema Rocket

O Tema Rocket usa esse padrão em todos os componentes nativos — siga-o ao criar os seus:

<template>
    <div class="free-shipping" v-if="remaining > 0">
        Faltam <strong>{{ $formatMoney(remaining) }}</strong> para frete grátis
    </div>
</template>

<script>
export default {
    name: 'FreeShipping',
    props: {
        cartTotal: {
            type: Number,
            required: true,
        },
    },
    computed: {
        remaining() {
            const minimum = window.merchant?.shipping?.[0]?.min || 0;
            return Math.max(0, minimum - this.cartTotal);
        },
    },
};
</script>

<style lang="scss" scoped>
.free-shipping {
    color: var(--color-general-primary);
    font-size: 14px;
    padding: 8px 0;
}
</style>

Recebendo dados do Twig via props

O padrão mais comum no Tema Rocket é o Twig passar dados da loja para o componente Vue via props:

{# sections/product-info.twig #}
<product-price
    :price="{{ product.prices.price }}"
    :price-formated="{{ product.prices.price_formated }}"
    :has-promotion="{{ product.prices.has_promotion | bool_text }}">
</product-price>

<!-- components/ProductPrice.vue -->
<script>
export default {
    props: {
        price: { type: Number, required: true },
        priceFormated: { type: String, default: '' },
        hasPromotion: { type: Boolean, default: false },
    },
};
</script>

Boas práticas

Sempre defina a propriedade name. O name define a tag HTML usada nos templates Twig. Sem ele, o componente pode não ser registrado corretamente:

<script>
export default {
    name: 'ProductPrice', // → <product-price> no Twig
};
</script>

Declare todas as props com tipo e valor padrão. Props sem validação geram erros silenciosos difíceis de depurar:

<script>
export default {
    name: 'ProductPrice',
    props: {
        // ✅ Correto
        price: { type: Number, required: true },
        hasPromotion: { type: Boolean, default: false },

        // ❌ Evite — sem validação
        price: Number,
        hasPromotion: Boolean,
    },
};
</script>

Use scoped no bloco <style>. Garante que os estilos do componente não vazem para outros elementos da página:

{# ✅ Correto #}
<style lang="scss" scoped>
.product-price { ... }
</style>

{# ❌ Estilos vazam para o resto da página #}
<style lang="scss">
.product-price { ... }
</style>

Acesse dados globais com optional chaining. As variáveis globais (window.merchant, window.product) podem não estar disponíveis em todas as páginas:

computed: {
    // ✅ Correto
    storeName() {
        return window.merchant?.manifest?.name || '';
    },

    // ❌ Quebra se window.merchant for undefined
    storeName() {
        return window.merchant.manifest.name;
    },
},

SASS (e sua sintaxe SCSS) é um pré-processador CSS que adiciona variáveis, aninhamento e funções ao CSS padrão. Os arquivos .scss são compilados automaticamente em CSS pelo build do tema.

Design tokens do Tema Rocket

Sempre use as variáveis CSS do tema em vez de valores fixos. Isso garante que suas customizações acompanhem o tema configurado pelo merchant no Editor de Temas:

.meu-componente {
    color: var(--color-general-primary);
    background-color: var(--color-general-background);
    font-family: var(--font-family-primary);
    border-radius: var(--border-radius-base);

    &:hover {
        background-color: var(--color-general-primary);
        color: var(--color-general-white);
    }
}

Consulte todos os tokens disponíveis em Variáveis CSS.

Customizando componentes do tema

Para sobrescrever o estilo de um componente existente do Tema Rocket, crie um arquivo SCSS em assets/styles/ usando o mesmo seletor do componente:

// assets/styles/product-card.scss

.product-card {
    border-radius: 12px;
    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);

    .product-card__title {
        font-size: 16px;
        color: var(--color-general-primary-text);
    }

    .product-card__price {
        font-weight: var(--font-bold);
        color: var(--color-general-primary);
    }
}

Adicionando estilos a um componente Vue

Para estilos exclusivos de um componente Vue, use lang="scss" scoped diretamente no arquivo .vue:

<style lang="scss" scoped>
.free-shipping-bar {
    padding: 12px 16px;
    background-color: var(--color-general-background-secondary);
    border-radius: var(--border-radius-base);

    &__value {
        color: var(--color-general-primary);
        font-weight: var(--font-bold);
    }
}
</style>

Boas práticas

Use design tokens em vez de valores fixos. Valores fixos quebram quando o merchant altera o tema no Editor de Temas:

// ✅ Correto — acompanha o tema
.btn {
    background-color: var(--color-general-primary);
    font-family: var(--font-family-primary);
    border-radius: var(--border-radius-base);
}

// ❌ Valor fixo — não acompanha o tema
.btn {
    background-color: #A85DEE;
    font-family: 'Inter', sans-serif;
    border-radius: 4px;
}

Organize os arquivos por contexto em assets/styles/. Cada subpasta tem uma responsabilidade específica:

assets/styles/
├── elements/        # Estilos de componentes e elementos individuais
├── global/          # Estilos que afetam múltiplas páginas
├── pages/           # Estilos de cada página
│   └── mobile/      # Estilos responsivos por página
└── sections/        # Estilos de cada seção

Limite o aninhamento a 3 níveis. Aninhamentos profundos aumentam a especificidade e dificultam a sobrescrita:

// ✅ Até 3 níveis — legível e fácil de sobrescrever
.product-card {
    .content {
        .price { ... }
    }
}

// ❌ Aninhamento excessivo
.product-card {
    .content {
        .info {
            .price {
                span { ... }
            }
        }
    }
}

​Acessando dados da loja

​Compondo páginas com seções e elementos

​Iterando sobre dados da loja

​Usando configurações do Editor de Temas

​Passando dados para componentes Vue

​Filtros específicos da Yampi

​Boas práticas

​Usando um componente em um template Twig

​Acessando dados da loja no componente

​Padrão de componente do Tema Rocket

​Recebendo dados do Twig via props

​Boas práticas

​Design tokens do Tema Rocket

​Customizando componentes do tema

​Adicionando estilos a um componente Vue

​Boas práticas

Acessando dados da loja

Compondo páginas com seções e elementos

Iterando sobre dados da loja

Usando configurações do Editor de Temas

Passando dados para componentes Vue

Filtros específicos da Yampi

Boas práticas

Usando um componente em um template Twig

Acessando dados da loja no componente

Padrão de componente do Tema Rocket

Recebendo dados do Twig via props

Boas práticas

Design tokens do Tema Rocket

Customizando componentes do tema

Adicionando estilos a um componente Vue

Boas práticas