# Customizando ūüďĚ

ūüáļūüáł English version

Aqui estamos considerando que voc√™ j√° tem um deploy criado a partir do Storefront Starter (opens new window) e usando nosso template padr√£o @ecomplus/storefront-template. Se voc√™ √© um lojista E-Com Plus n√≥s j√° fizemos isto por voc√™ ūüėČ

H√° v√°rias formas de customizar o Storefront:

Antes de come√ßar, pode ser √ļtil rodar o seu deploy do Storefront em localhost (v√≠deo tutorial (opens new window)):

  1. Certifique-se que o Node.js (opens new window) est√° instalado;
  2. Clone seu repositório no GitHub;
  3. Instale as dependências do npm;
  4. Rode o script serve;
git clone https://github.com/ecomplus-stores/my-store
cd my-store
npm i
npm run serve

# Construir p√°ginas no CMS

Acesse a parte administrativa (powered by Netlify CMS (opens new window) ‚̧ԳŹ) do seu deploy do Storefront em https://www.seudominio.com.br/admin/, depois do login voc√™ poder√°:

  • Editar informa√ß√Ķes e configura√ß√Ķes gerais como contatos, endere√ßo e logo:
CMS config
CMS info
  • Inserir as cores da identidade da loja:
CMS colors
  • Organizar todas as p√°ginas adicionando, movendo ou removendo se√ß√Ķes (arraste e solte):
CMS drag'n drop
  • Adicionar c√≥digo HTML, JS ou CSS extra para cada p√°gina ou todo o site:
CMS custom HTML section
CMS insert code
  • Criar ou editar p√°ginas extra e posts de blog;
  • Plugar e customizar widgets adicionais;

# Criar/sobrescrever tema

Estamos usando o @ecomplus/storefront-twbs (baseado em Bootstrap 4 (opens new window)) como base CSS/JS, para detalhes cheque a referência de uso da UI base. Você também pode querer checar os seletores de elementos mais importantes do template.

  • Se voc√™ quer apenas adicionar poucos trechos de CSS, fa√ßa isto no CMS em Layout > Inserir c√≥digo > CSS customizado;
  • Se voc√™ planeja fazer altera√ß√Ķes maiores n√≥s recomendamos editar os arquivos SCSS (voc√™ pode utilizar o Sass (opens new window) ou apenas CSS padr√£o) diretamente no GitHub ou usando seu editor de c√≥digo preferido:
    1. Adicione ou sobrescreva estilos em /template/scss/custom-css/_styles.scss;
    2. Para substituir os estilos padrão do template você pode tentar usar variáveis SCSS do Bootstrap (opens new window) em /template/scss/_variables.scss;
    3. Finalmente, voc√™ tamb√©m pode editar from scratch em /template/scss/_main.scss se n√£o quiser importar todos os estilos do Storefront Template (opens new window), e optar por criar do zero por exemplo os estilos do rodap√©, tamb√©m √© poss√≠vel. Inclusive indicamos isso para evitar duplicidade, caso saiba o que esteja fazendo. (perf optim ūüöÄ, n√£o t√£o f√°cil quanto as op√ß√Ķes anteriores);

DICA

Encorajamos a utilização de CSS vars sempre que possível, para tornar seu código adicional facilmente customizável e extensível.

Exemplo usando CSS vars
.top-bar {
  background-color: var(--secondary);
}
CSS vars example

Como exemplo você também pode analisar o SCSS aplicado por alguns dos nossos temas adicionais, como Clean Gray (opens new window) e Niche Baby (opens new window).

# Editar views pré-renderizadas

No CMS é possível incluir snippets HTML adicionais, mas para editar as views padrão você deve editar os arquivos EJS (opens new window) na pasta /template/pages/:

  • /template/pages/@/meta.ejs para customizar meta tags (especialmente para SEO):
EJS meta tags
  • /template/pages/@/sections/ para editar v√°rios componentes reutiliz√°veis ūüďĆ, estes renderizam o conte√ļdo principal das p√°ginas e s√£o configurados no arraste e solte do CMS:
EJS info bar
  • /template/pages/@/layout/ para editar organismos comuns do layout (rodap√©, cabe√ßalho e menu);
  • /template/pages/app/ para customizar carrinho e checkout, de forma superficial como contadores, banners e vitrines por exemplo;

Antes de come√ßar a editar HTML, deve ser √ļtil checar os componentes e classes CSS utilit√°rias dispon√≠veis por padr√£o.

DICA

EJS √© uma linguaguem de template simples baseada em JS para gerar markup HTML programaticamente, claro que voc√™ pode apenas escrever HTML padr√£o, mas para customiza√ß√Ķes avan√ßadas recomendamos que verifique como funciona a renderiza√ß√£o do Storefront com EJS.

Para manter as lojas customizadas atualizadas n√≥s continuamos tentando atualizar os arquivos EJS editados ap√≥s cada release do Storefront, preservando os snippets editados mas atualizando as partes n√£o alteradas via Git diff ūüėé

# Nota para cards de produtos

Alguns elementos HTML pré-renderizados são sobrescritos por JS no cliente pelos respectivos componentes Vue, isso acontece especialmente nos cards de produto pré-renderizados por /template/pages/@/sections/inc/product-item.ejs.

Nesses casos, você deve tentar customizar com CSS apenas ou usar o atributo data-slot para editar HTML preservando sua customização após a hidratação realizada pelo Storefront, veja um exemplo a seguir:

<div data-slot="buy-button-content">
  <i class="fas fa-shopping-bag mr-1"></i>
  Buy now
</div>

O valor do atributo data-slot deve corresponder ao nome do slot (opens new window) respectivo no componente Vue, cheque os slots do <ProductCard> aqui.

Como segunda opção, você também pode presetar as variáveis JavaScript globais window.productCardBuyHtml e window.productCardFooterHtml para apendar HTML aos cards.

DICA PRO

Se você necessita de uma customização mais profunda no componente, considere criar Webpack alias para ./html/ProductCard.html (veja substituindo componente Vue).

Voc√™ n√£o precisa saber Vue.js para customizar o Storefront, Vue incr√≠vel e bem simples de aprender, para customiza√ß√Ķes avan√ßadas te entregaria muita produtividade, mas n√£o √© um requisito ‚úĆÔłŹ

# Scripts adicionais

Por padrão, você pode utilizar jQuery 3 (slim), Vue.js 2 e algumas pequenas bibliotecas que estão disponíveis globalmente. Para mais detalhes, verifique a UI base e globais do JS.

  • Se voc√™ precisa adicionar apenas scripts pequenos, fa√ßa diretamente no CMS em Layout > Inserir C√≥digo adicionando as tags <script> antes de /body ou /head (se necess√°rio). Al√©m disso, voc√™ consegue adicionar scripts em p√°ginas espec√≠ficas utilizando blocos de C√≥digo HTML;

  • Se est√° planejando inserir bastante JS (ou ES), sugerimos fortemente que insira diretamente na pasta /template/js/custom-js/ no Github ou em seu editor de c√≥digo preferido. Voc√™ tamb√©m pode criar um novo arquivo e importar (opens new window) devidamente.

DICA

Quando editar arquivos em /template/js/, você pode utilizar ES6 sem se preocupar com suporte do navegador, os códigos inseridos serão parseados e minificados.

# Substituir componentes Vue

ALERTA

Use-o com modera√ß√£o e apenas quando realmente necess√°rio, evite utilizar para implementa√ß√Ķes diferentes das citados abaixo, especialmente se n√£o conhecer muito bem Webpack.

Quando métodos mais fáceis não são suficientes para o nível de personalização desejável, tente usar Webpack 4 aliases (opens new window).

Geralmente, recomendamos que seja utilizado apenas para substituir HTML de componentes Vue ūüďź, apesar de tamb√©m funcionar para scripts e estilos.

Você deve começar buscando o arquivo original no repositório do GitHub (opens new window), copiar o arquivo que deseja substituir e colar dentro de /template/js/custom-js/, edite o arquivo conforme desejar e crie um arquivo storefront.webpack.js no root do seu repositório, como por exemplo:

// storefront.webpack.js

const path = require('path')

module.exports = () => ({
  resolve: {
    alias: {
      './html/ProductCard.html': path.resolve(__dirname, '/template/js/custom-js/html/ProductCard.html')
    }
  }
})

Note que todos componentes do Storefront Components s√£o compostos por 4 arquivos (Vue/HTML/JS/SCSS), o arquivo Vue sempre importa HTML correspondente com ./html/{ComponentName}.html.