DEV Community: Lucas Teixeira dos Santos Santana

Como criar um template de email personalizado no Magento 2

Lucas Teixeira dos Santos Santana — Wed, 25 Mar 2026 11:57:21 +0000

Contextualizando

O Magento inclui um template de e-mail padrão para o corpo de cada mensagem enviada pelo sistema. Este template de conteúdo é combinado com templates de cabeçalho (header) e rodapé (footer) para criar a mensagem completa.

A customização pelo painel administrativo é a maneira mais fácil e tem precedência sobre os templates padrão do sistema e aqueles baseados em temas.

Carregar o Template Padrão

No painel administrador acesse: Marketing > Communications > Email Templates > Add New Template. Na seção Load default template, selecione o template que se deseja customizar no seletor Template. O código HTML e as variáveis do template aparecerão no formulário, após clicar no botão Load Template.

Após o carregamento do conteúdo do template, é possível modificar o conteúdo do template:

Template Name: nome do template para identificação;
Template Subject: assunto do e-mail, que pode ser usado para organizar, classificar e filtrar os templates;
Template Content: responsável por gerar o HTML conforme a necessidade. Deve-se ter cuidado ao remover, editar e acrescentar chaves duplas;
Template Styles: responsável por declarações de estilo CSS necessárias para formatar o template.

Para inserir uma variável, posicione o cursor no código onde a variável deve ser inserida e clique em Insert Variable. Uma tag de marcação para a variável será inserida no código. A seleção de variáveis varia por template. Variáveis de Contato da Loja (Store Contact Information) estão disponíveis em todos os templates.

É possível pré-visualizar o e-mail através do botão Preview Template.

Criar um Template de E-mail Personalizado

Criar templates como arquivos físicos no sistema de arquivos do módulo ou tema é a abordagem recomendada para desenvolvedores. Isso permite o controle de versão e facilita a implantação.

email_templates.xml

Para criar um template de e-mail é necessário criar um arquivo chamado email_templates.xml que deve seguir a estrutura de pasta \{Vendor}{Module}\etc\email_templates.xml.xml.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Email:etc/email_templates.xsd">
    <template id="{template_id}"
              label="{Email Template Label}"
              file="{path}/{file_name}.html"
              type="html"
              module="{Vendor}_{Module}"
              area="{area}"/>
</config>

Atributos template

Atributo	Descrição	Obrigatório
id	Um identificador único para o template	`true`
label	O nome visível no painel administrador	`true`
file	O caminho e nome do arquivo HTML do template	`true`
type	Tipo de arquivo	`true`
module	Nome do módulo no qual será procurado o arquivo de template.	`true`
area	Área responsável onde será procurado o arquivo de template (`frontend` ou `adminhtml`).	`true`

template.html

No arquivo de template deve seguir a estrutura de pastas \{Vendor}\{Module}\view\{area}\email\{path}\{file_name}.html.

<!--@subject {Email Subject} @-->
{{template config_path="design/email/header_template"}}
    <p>{{trans "Olá, %var_name," var_name=$var_name}}</p>
    <p>{{var var_name}}</p>
{{template config_path="design/email/footer_template"}}

Disparo de E-mail

E-mails podem ser disparados utilizando a classe \Magento\Framework\Mail\Template\TransportBuilder. Esta classe pode ser instanciada através de injeção de dependência no construtor.

Para disparar um e-mail é utilizado o método getTransport() da classe de gerenciador de e-mails, mas antes é necessário configurar os dados de remetente, recebedor e configurar as variáveis do e-mail.

<?php

namespace {Vendor}\{Module}\{Directory};

use Magento\Framework\Mail\Template\TransportBuilder;
use Magento\Framework\Translate\Inline\StateInterface;

class {ClassName}
{
    private TransportBuilder $transportBuilder;
    private StateInterface $inlineTranslation;

    public function __construct(
        TransportBuilder $transportBuilder,
        StateInterface $inlineTranslation
    ) {
        $this->transportBuilder = $transportBuilder;
        $this->inlineTranslation = $inlineTranslation;
    }

    ...
    public function {methodName}() {
        $templateOptions = [
            'area' => \Magento\Framework\App\Area::AREA_FRONTEND,
            'store' => $this->storeManager->getStore()->getId()
        ];
        $templateVars = [
            '{var_name}' => '{var value}',
        ];

        $from = ['email' => $emailSender, 'name' => $senderName];
        $to = [$recipientEmail];

        $this->inlineTranslation->suspend();
        $transport = $this->transportBuilder->setTemplateIdentifier('{template_id}')
            ->setTemplateOptions($templateOptions)
            ->setTemplateVars($templateVars)
            ->setFrom($from)
            ->addTo($to)
            ->getTransport();

        $transport->sendMessage();
        $this->inlineTranslation->resume();
    }
}

Estilização e Variáveis de Template

{{template config_path="..."}}: Estas diretivas carregam o header, footer e outros templates de e-mail padrões.
: Define o assunto do e-mail.
{{var ...}}: Permite a inserção de variáveis passadas pelo código PHP.

Estilização (CSS)

A estilização de e-mails é um desafio no frontend devido ao suporte limitado de clientes de e-mail para tags <style> ou folhas de estilo externas.

Estilos Inline: A maioria dos estilos de e-mail deve ser aplicada como estilos inline (no atributo style das tags HTML). O Magento utiliza a biblioteca Emogrifier para converter os estilos CSS em estilos inline.
- A diretiva {{inlinecss file="css/email-inline.css"}} no header.html informa ao Magento quais arquivos less/css devem ser aplicados como estilos inline.
Tag Style: Estilos que não podem ser aplicados inline (como media queries ou pseudo-classes :hover) devem estar dentro de uma tag <style type="text/css"></style>.
- A diretiva {{css file="css/email.css"}} no header.html compila e insere esses estilos não-inline.
Estilos Customizados: Estilos adicionados no campo Template Styles do painel administrador ou em blocos de comentários  em arquivos HTML de template são incluídos na variável {{var template_styles|raw}}.

Variáveis e Localização

Variáveis do Sistema: São placeholders (como {{config path="..."}} ou {{var store_email}}) que são substituídos por valores de configuração da loja no momento da geração do e-mail.
Variáveis Customizadas: Podem ser criadas e ter seus valores definidos no painel administrador em System > Other Settings > Custom Variables. Elas podem ser inseridas no template usando comandos como {{var custom_variable}} ou {{customVar code=custom_variable}}.
Localização (Localization): Para suportar a tradução de conteúdo, todas as strings nos e-mails devem usar a diretiva {{trans ...}}. O Magento traduzirá as strings para o locale configurado para a store view que está enviando o e-mail.
- A diretiva trans suporta múltiplos parâmetros nomeados. Exemplo: {{trans "Dear %first_name %last_name," first_name=$first_name last_name=$last_name}}.

Finalizando

Valores entre chaves ({test}) devem ser alterados na implementação do código.

Habilitando as alterações

Execute o comando PHP para limpar todos os caches de armazenamento em cache do processos.

php bin/magento cache:clean
php bin/magento flush

Diretórios e Arquivos

Segue a a lista de diretórios e arquivos que devem ser criados para a criaçãod e tradução em um módulo.

- app/
  - code/
    - {Vendor}/
        - {Module}/
          - etc/
            - module.xml
            - email_templates.xml
          - view/
              - {area}/
                  - email/
                  - {fileName}.html
          - registration.php
          - composer.json

Como funcionam Bindings de Eventos de Formulário no KnockoutJs

Lucas Teixeira dos Santos Santana — Mon, 25 Nov 2024 17:02:31 +0000

Este conteúdo é basicamente uma tradução dos materiais originais. A intenção é adquirir aprendizado sobre o KnockoutJs para Magento 2 e criar conteúdo em português sobre KnockouJs.

Documentação

Bindings

No KnockoutJs, bindings são a maneira de conectar a lógica do ViewModel (os dados e a lógica de negócios) com a View (HTML). Em resumo, é através dos bindings que é realizada a interface de usuário refletir automaticamente as mudanças nos seus dados, sem a necessidade de manipular diretamente o DOM.

Os bindings no KnockoutJs funcionam através do atributo data-bind em elementos HTML. Esse atributo é onde você especifica o binding que deseja usar e os valores associados.

Eventos de Formulário

Click

O binding click adiciona um manipulador de eventos para que a função JavaScript escolhida seja invocada quando o elemento DOM associado for clicado. Isso é mais comumente usado em elementos com tag <button>, <input> e <a>, mas na verdade funciona com qualquer elemento DOM visível. O KnockoutJs fornecerá o valor atual do modelo como o primeiro parâmetro.

Cada vez que for clicado no elemento, isso invocará o método que foi passado na ViewModel, que por sua vez altera o estado da ViewModel, o que faz com que a IU seja atualizada.

<div>
    You've clicked <span data-bind="text: numberOfClicks"></span> times
    <button data-bind="click: incrementClickCounter">Click me</button>
</div>

<script type="text/javascript">
        ko.applyBindings({
        numberOfClicks : ko.observable(0),
        incrementClickCounter : function() {
            var previousCount = this.numberOfClicks();
            this.numberOfClicks(previousCount + 1);
        }
    });
</script>

Por padrão, o KnockoutJs impedirá que o evento click execute qualquer ação padrão. Isso significa que ao usar o binding click em uma tag <a>, o navegador apenas chamará a função e não navegará até o href do link. A vinculação de clique é normalmente utilizada quando está usando o link como parte de uma UI que manipula a ViewModel, não como um hiperlink normal para outra página da web. Caso seja necessário que a ação de clique padrão continue, basta retornar true na função.

Event

O binding event permite adicionar um manipulador de eventos para um evento especificado para que a função JavaScript escolhida seja invocada quando esse evento for acionado para o elemento DOM associado. Isso pode ser usado para vincular a qualquer evento, como pressionamento de tecla, passagem do mouse ou saída do mouse.

<div>
    <div data-bind="event: { mouseover: enableDetails, mouseout: disableDetails }">
        Mouse over me
    </div>
    <div data-bind="visible: detailsEnabled">
        Details
    </div>
</div>

<script type="text/javascript">
        ko.applyBindings({
        detailsEnabled: ko.observable(false),
        enableDetails: function() {
            this.detailsEnabled(true);
        },
        disableDetails: function() {
            this.detailsEnabled(false);
        }
    });
</script>

Submit

O binding submit *é uma diretiva de vinculação de envio em um formulário impedirá a ação de envio padrão do navegador para esse formulário, em outras palavras, o navegador chamará a função de manipulador, mas não enviará o formulário ao servidor. A vinculação de *submit é normalmente utilizada quando está sendo usado o formulário como uma interface para a ViewModel, não como um formulário HTML normal. Caso seja necessário que o formulário seja enviado como um formulário HTML normal, basta retornar true do seu manipulador de envio.

<form data-bind="submit: doSomething">
    <button type="submit">Submit</button>
</form>

<script type="text/javascript">
        ko.applyBindings({
        this.doSomething = function(formElement) {
            // ... now do something
        }
    });
</script>

Enable/Disable

O binding enable faz com que o elemento DOM associado seja habilitado quando seu valor de parâmetro for verdadeiro. O binding disable funciona de forma oposta, fazendo com que o elemento DOM associado seja desabilitado quando seu valor for verdadeiro.

<p>
    <input type='checkbox' data-bind="checked: hasCellphone" />
    I have a cellphone
</p>
<p>
    Your cellphone number:
    <input type='text' data-bind="value: cellphoneNumber, enable: hasCellphone" />
</p>

<script type="text/javascript">
        ko.applyBindings({
        hasCellphone : ko.observable(false),
        cellphoneNumber: ""
    });
</script>

Value

O binding value *vincula o valor do elemento DOM associado a uma propriedade na *ViewModel. Isso normalmente é útil com elementos de formulário como <input>, <select> e <textarea>.

Quando o usuário editar o valor no controle de formulário associado, o valor será atualizado na ViewModel. Da mesma forma, quando a ViewModel atualiza o valor, isso atualizará o valor do controle de formulário na tela.

<p>Login name: <input data-bind="value: userName" /></p>
<p>Password: <input type="password" data-bind="value: userPassword" /></p>

<script type="text/javascript">
        ko.applyBindings({
        userName: ko.observable(""),        // Initially blank
        userPassword: ko.observable("abc"), // Prepopulate
    });
</script>

O binding value funciona em conjunto com a vinculação de <options> para permitir a leitura e gravação de valores que são objetos JavaScript arbitrários, e não apenas valores de string.

TextInput

O binding textInput vincula um campo (<input> ou <textarea>) a uma propriedade ViewModel, fornecendo atualizações bidirecionais entre a propriedade ViewModel e o valor do elemento. O binding textInput fornece atualizações instantâneas do DOM para todos os tipos de entrada do usuário, incluindo preenchimento automático, arrastar e soltar e eventos da área de transferência.

<p>Login name: <input data-bind="textInput: userName" /></p>
<p>Password: <input type="password" data-bind="textInput: userPassword" /></p>

ViewModel:
<pre data-bind="text: ko.toJSON($root, null, 2)"></pre>

<script type="text/javascript">
    ko.applyBindings({
        userName: ko.observable(""),        // Initially blank
        userPassword: ko.observable("abc"), // Prepopulate
    });
</script>

O binding textInput, por padrão, só atualiza seu modelo quando o usuário move o foco para fora da caixa de texto. O binding textInput atualiza seu modelo imediatamente a cada pressionamento de tecla ou outro mecanismo de entrada de texto.

HasFocus

O binding hasFocus vincula o estado de foco de um elemento DOM a uma propriedade ViewModel. É uma ligação bidirecional que ao ser definida a propriedade ViewModel como true ou false, o elemento associado ficará focado ou desfocado.

<input data-bind="hasFocus: isSelected" />
<button data-bind="click: setIsSelected">Focus programmatically</button>
<span data-bind="visible: isSelected">The textbox has focus</span>

<script type="text/javascript">
        ko.applyBindings({
            isSelected: ko.observable(false),
            setIsSelected: function() { this.isSelected(true) }
        });
</script>

Checked

O binding checked vincula um controle de formulário verificável, ou seja, uma caixa de seleção (<input type='checkbox'>) ou um botão de opção (<input type='radio'>) com uma propriedade na ViewModel.

<p>Check 1 (checked): <input type="checkbox" data-bind="checked: checkYes" /></p>
<p>Check 2 (unchecked): <input type="checkbox" data-bind="checked: checkNo" /></p> 

<script type="text/javascript">
    ko.applyBindings({
        checkYes: ko.observable(true),
        checkNo: ko.observable(false)
    });
</script>

Options

O binding options controla quais opções devem aparecer em uma lista suspensa (<select>) ou lista de seleção múltipla (<select size='6'>). Esta ligação não pode ser usada com nada além de elementos <select>.

O valor atribuído deve ser um array (ou Observable Array). O elemento <select> exibirá então um item para cada item do seu array.

<p>
    Destination country:
    <select data-bind="options: availableCountries"></select>
    <input data-bind="value: newCountry"/>
    <button data-bind="click: addCountry">Add country</button>
</p>

<script type="text/javascript">
    ko.applyBindings({
        addCountry: function() {
            this.availableCountries.push(this.newCountry());
        },
        newCountry: ko.observable(),        
        availableCountries: ko.observableArray(['Argentina', 'Brazil', 'Chile'])
    });
</script>

SelectedOptions

O binding selectedOptions controla quais elementos em uma lista de seleção múltipla estão selecionados no momento. Destina-se a ser usado em conjunto com um elemento <select> e a ligação de opções.

Quando o usuário seleciona ou desmarca um item na lista de seleção múltipla, isso adiciona ou remove o valor correspondente a uma matriz na ViewModel. Da mesma forma, supondo que seja um Observable Array na ViewModel, sempre que adicionar ou remover itens desse array, os itens correspondentes na UI serão selecionados ou desmarcados. É uma ligação bidirecional.

<p>Choose some countries you'd like to visit:</p>
<select data-bind="options: availableCountries, selectedOptions: chosenCountries" size="5" multiple="true"></select>

<script type="text/javascript">
    ko.applyBindings({
        availableCountries : ko.observableArray(['France', 'Germany', 'Spain']),
        chosenCountries : ko.observableArray(['Germany']) // Initially, only Germany is selected
    });
</script>

UniqueName

O binding uniqueName garante que o elemento DOM associado tenha um atributo de nome não vazio. Se o elemento DOM não tiver um atributo name, essa ligação fornecerá um e o definirá como algum valor de string exclusivo.

<input data-bind="value: someModelProperty, uniqueName: true" />

Como funcionam Bindings de Fluxo de Controle no KnockoutJs

Lucas Teixeira dos Santos Santana — Mon, 18 Nov 2024 13:48:04 +0000

Este conteúdo é basicamente uma tradução dos materiais originais. A intenção é adquirir aprendizado sobre o KnockoutJs para Magento 2 e criar conteúdo em português sobre KnockouJs.

Documentação

Bindings

Os bindings no KnockoutJs funcionam através do atributo data-bind em elementos HTML. Esse atributo é onde você especifica o binding que deseja usar e os valores associados.

Fluxo de Controle

foreach

O binding foreach é usado para criar repetições em elementos HTML, gerando cópias do mesmo elemento para cada item em uma coleção (como um array ou um observable array) no seu modelo de visualização. Isso permite que seja criado facilmente listas ou tabelas dinâmicas que exibem dados do seu modelo.

Quando é modificado o conteúdo do array de modelo (adicionando, movendo ou excluindo suas entradas), o binding do foreach usa um algoritmo eficiente para descobrir o que mudou, para que possa atualizar o DOM conforme o array. Isso significa que ele pode lidar com combinações arbitrárias de alterações simuladas.

Quando é adicionado algo no array, o foreach irá renderizar novas cópias do seu modelo e inseri-las no DOM existente;
Quando é excluído algo no array, o foreach simplesmente removerá os elementos DOM correspondentes;
Quando é reordenado algo no array (mantendo as mesmas instâncias do objeto), o foreach normalmente apenas moverá os elementos DOM correspondentes para sua nova posição.

<div>
  <ul data-bind="foreach: items">
    <li data-bind="text: $data"></li>
  </ul>

  <ul data-bind="foreach: getItems()">
    <li>
        <span data-bind="text: name"></span> - <span data-bind="text: age"></span>
    </li>
  </ul>

  <ul data-bind="foreach: { data: people, as: 'person' }"></ul>
</div>

Neste caso, a variável $data faz referência ao item atual que está sendo processado no loop. Isso permite acessar as propriedades ou valores desse item dentro do loop.

A diretiva as permite que seja definido um nome personalizado para a variável que representa o item atual no ciclo de iteração do foreach. Isso pode tornar o código mais legível e significativo.

Às vezes é necessário que um item do array não seja excluído, mas sim ocultado, sem realmente perder o registro de sua existência. Isso é conhecido como exclusão não destrutiva. Caso seja necessário ocultar entradas destruídas, defina a opção includeDestroyed como false.

<div data-bind='foreach: { data: myArray, includeDestroyed: false }'>
    ...
</div>

Caso seja necessário executar alguma lógica personalizada adicional nos elementos DOM gerados, é possível usar qualquer um dos seguintes retornos de chamada:

afterRender: é invocado cada vez que o bloco foreach é duplicado e inserido no documento, tanto quando foreach é inicializado pela primeira vez quanto quando novas entradas são adicionadas posteriormente ao array associado;
afterAdd: é como afterRender, exceto que é invocado apenas quando novas entradas são adicionadas ao array (e não quando foreach itera pela primeira vez sobre o conteúdo inicial do array);
beforeRemove: é invocado quando um item do array é removido, mas antes que os nós DOM correspondentes sejam removidos. Se for especificado um retorno de chamada beforeRemove, será necessário remover os nós DOM manualmente, ou seja, o KnockoutJs não pode saber quando será permitido remover fisicamente os nós DOM;
beforeMove: é invocado quando um item do array mudou de posição no array, mas antes que os nós DOM correspondentes tenham sido movidos. Observe que beforeMove se aplica a todos os elementos do array cujos índices foram alterados, portanto, se for inserido um novo item no início de um array, o retorno de chamada (se especificado) será acionado para todos os outros elementos, já que sua posição de índice aumentou em um. É possível usar o beforeMove para armazenar as coordenadas originais da tela dos elementos afetados para poder animar seus movimentos no retorno de chamada afterMove;
afterMove: é invocado depois que um item do array mudou de posição no array e depois que foreach atualizou o DOM para corresponder. Observe que afterMove se aplica a todos os elementos do array cujos índices foram alterados, portanto, se for inserido um novo item no início de um array, o retorno de chamada (se especificado) será acionado para todos os outros elementos, já que sua posição de índice aumentou em um.

if e ifnot

O binding do if faz com que uma seção de marcação apareça em seu documento (e tenha seus atributos de ligação de dados aplicados), somente se uma expressão especificada for avaliada como verdadeira (ou um valor verdadeiro, como um objeto não nulo ou uma string não vazia).

O binding do ifnot funciona exatamente como a ligação if, exceto que inverte o resultado de qualquer expressão que seja passado para ela.

if e ifnot desempenham um papel semelhante aos bindings vivsible e hidden. A diferença é que, com visible, a marcação contida sempre permanece no DOM e sempre tem seus data-bind de dados aplicados – o binding visible apenas usa CSS para alternar a visibilidade do elemento contêiner. A ligação if, entretanto, adiciona ou remove fisicamente a marcação contida em seu DOM e só aplica ligações aos descendentes se a expressão for verdadeira. Se a expressão envolver algum valor observável, a expressão será reavaliada sempre que o valor dele mudar.

<div data-bind="if: exibirMensagem">
    <p>Esta mensagem será exibida se 'exibirMensagem' for verdadeiro.</p>
</div>

<div data-bind="ifnot: exibirMensagem">
    <p>Esta mensagem será exibida se 'exibirMensagem' for falso.</p>
</div>

with e using

Os bindings with e using criam um novo contexto de ligação, para que os elementos descendentes sejam vinculados no contexto de um objeto especificado.

O binding with adicionará ou removerá dinamicamente elementos descendentes dependendo se o valor associado for falsy.

A opção as permite definir um alias para o novo objeto de contexto. Embora seja possível se referir ao objeto usando a variável de contexto $data.

<form data-bind="submit: getTweets">
    Twitter account:
    <input data-bind="value: twitterName" />
    <button type="submit">Get tweets</button>
</form>

<div data-bind="with: resultData">
    <h3>Recent tweets fetched at <span data-bind="text: retrievalDate"> </span></h3>
    <ol data-bind="foreach: topTweets">
        <li data-bind="text: text"></li>
    </ol>

    <button data-bind="click: $parent.clearResults">Clear tweets</button>
</div>

<script type="text/javascript">
  function AppViewModel() {
    var self = this;
    self.twitterName = ko.observable('@example');
    self.resultData = ko.observable(); // No initial value

    self.getTweets = function() {
        var name = self.twitterName(),
            simulatedResults = [
                { text: name + ' What a nice day.' },
                { text: name + ' Building some cool apps.' },
                { text: name + ' Just saw a famous celebrity eating lard. Yum.' }
            ];

        self.resultData({ retrievalDate: new Date(), topTweets: simulatedResults });
    }

    self.clearResults = function() {
        self.resultData(undefined);
    }
  }

  ko.applyBindings(new AppViewModel());
</script>

A ligação using foi introduzida no KnockoutJs 3.5 como um substituto para o with quando a renderização de elementos descendentes não é desejada. Como o using reavalia as ligações descendentes em vez de renderizar novamente, cada ligação descendente incluirá uma dependência adicional no contexto do using.

let

O binding let permite definir propriedades de contexto de ligação personalizadas que é possível referenciar nas ligações de todos os elementos descendentes.

<!--ko let: {inventory: {suppliers: suppliers, bins: bins}, calculatedDisplay: someCalculation}-->
    <div data-bind="foreach: {data: inventory.suppliers, as: 'supplier'}">
        <div data-bind="foreach: {data: inventory.bins, as: 'bin'}">
            <span data-bind="text: calculatedDisplay(supplier, bin)">
        </div>
    </div>
<!--/ko-->

<script type="text/javascript">
    ko.applyBindings({
        suppliers: [...],
        bins: [...],
        someCalculation: function (supplier, bin) {
            /* return some calculated value based on parameters */
        }
    });
</script>

Como funcionam Bindings de Texto e Aparência no KnockoutJs

Lucas Teixeira dos Santos Santana — Mon, 11 Nov 2024 21:03:05 +0000

Este conteúdo é basicamente uma tradução dos materiais originais. A intenção é adquirir aprendizado sobre o KnockoutJs para Magento 2 e criar conteúdo em português sobre KnockouJs.

Documentação

Bindings

Os bindings no KnockoutJs funcionam através do atributo data-bind em elementos HTML. Esse atributo é onde você especifica o binding que deseja usar e os valores associados.

Controlando Texto e Aparência

Visible

O binding visible é usado para controlar a visibilidade de elementos HTML com base no valor de um observable da sua ViewModel. Ele permite mostrar ou ocultar elementos com base em uma condição específica definida na sua ViewModel.

<div>
  <p data-bind="visible: isContentVisible">Este parágrafo está visível se isContentVisible for true.</p>
</div>

Quando acondição é um valor semelhante a false (false, 0, null ou undefined), a vinculação visible define o estilo como none, fazendo com que ele fique oculto. Isso tem prioridade sobre qualquer estilo de exibição que se pode definir usando CSS.

Hidden

O binding hidden é usado para ocultar elementos HTML com base no valor de um observable da sua ViewModel. Ao contrário do binding *visible*, que controla a visibilidade dos elementos, o binding *hidden* oculta os elementos da interface do usuário quando a condição especificada é atendida.

<div>
  <p data-bind="hidden: isContentHidden">Este parágrafo está oculto se isContentHidden for true.</p>
</div>

Text

O binding text é usado para atualizar o conteúdo de elementos HTML com o valor de um observable da sua ViewModel. Ele permite que seja insirido o texto de um observable diretamente no elemento HTML, garantindo que qualquer alteração no valor do observable seja refletida automaticamente no texto exibido.

<div>
  <p data-bind="text: message">Este parágrafo exibirá o conteúdo do observable 'message'.</p>
    <p data-bind="text: 'Total: $' + totalAmount() + ' USD'">Este parágrafo exibirá o total formatado com base no valor do observable 'totalAmount'.</p>
    <p data-bind="text: 'Olá, ' + userName()">Este parágrafo saudará o usuário com base no valor do observable 'userName'.</p>
</div>

Se este parâmetro for um valor observable, a vinculação atualizará o texto do elemento sempre que o valor for alterado. Se o parâmetro não for observable, ele definirá o texto do elemento apenas uma vez e não o atualizará novamente posteriormente.

Se o valor fornecido for algo diferente de um número ou uma string, o texto exibido será equivalente a yourParameter.toString().

Como essa ligação define seu valor de texto usando um nó de texto, é seguro definir qualquer valor de string sem arriscar HTML ou injeção de script.

HTML

O binding html é usado para inserir conteúdo HTML dinâmico em elementos da sua interface do usuário. Ele permite que seja atualizado o conteúdo de um elemento com o HTML gerado a partir de um observable ou de uma expressão da sua ViewModel.

<div>
  <p data-bind="html: dynamicHtml">Este parágrafo exibirá o conteúdo HTML do observable 'dynamicHtml'.</p>
</div>

O KnockoutJs limpa o conteúdo anterior e, em seguida, define o conteúdo do elemento para o valor do parâmetro usando a função html do jQuery ou analisando a string em nós HTML e anexando cada nó como um filho do elemento, se o jQuery não estiver disponível.

Se este parâmetro for um observable, a ligação atualizará o conteúdo do elemento sempre que o valor for alterado. Se o parâmetro não for observable, ele definirá o conteúdo do elemento apenas uma vez e não o atualizará novamente posteriormente.

Se o valor fornecido for algo diferente de um número ou uma string, o texto exibido será equivalente a yourParameter.toString().

Class

O binding class é usado para controlar as classes CSS aplicadas a elementos HTML com base no valor de um observable ou de uma expressão da sua ViewModel. Isso permite que seja alterado dinamicamente as classes CSS de um elemento com base em diferentes condições ou estados do seu aplicativo. Uma classe não é um nome de identificador legal, o correto para atribuir uma classe a um elemento HTML é colocar o nome do identificador entre aspas para que se torne uma string literal.

<div>
  <p data-bind="class: { 'active': isActive, 'highlight': shouldHighlight }">Este parágrafo terá as classes 'active' e 'highlight' com base nos valores dos observables 'isActive' e 'shouldHighlight'.</p>
    <p data-bind="class: { 'error': hasError(), 'warning': hasWarning() }">Este parágrafo terá a classe 'error' se hasError() for true, e terá a classe 'warning' se hasWarning() for true.</p>
    <p data-bind="class: 'static-class dynamic-class'">Este parágrafo terá a classe 'static-class' e 'dynamic-class' aplicadas a ele.</p>
</div>

O valor do parâmetro deve ser uma string que corresponda à classe(s) CSS que seria desejado adicionar ao elemento. Se o parâmetro fizer referência a um observable, a associação atualizará as classes sempre que o valor for alterado, removendo quaisquer classes adicionadas anteriormente e adicionando a classe ou classes do novo valor.

CSS

O binding css é usado para aplicar estilos CSS dinamicamente a elementos HTML com base no valor de um observable ou de uma expressão da sua ViewModel. Isso permite que seja alterado os estilos visuais de um elemento com base em diferentes condições ou estados do seu aplicativo. É possível definir várias classes CSS com base na mesma condição colocando os nomes entre aspas.

<div>
  <p data-bind="css: { 'active': isActive, 'highlight': shouldHighlight }">Este parágrafo terá os estilos CSS 'active' e 'highlight' com base nos valores dos observables 'isActive' e 'shouldHighlight'.</p>
    <p data-bind="css: { 'error': hasError(), 'warning': hasWarning() }">Este parágrafo terá o estilo 'error' se hasError() for true, e terá o estilo 'warning' se hasWarning() for true.</p>
    <p data-bind="css: 'static-style dynamic-style'">Este parágrafo terá o estilo 'static-style' e 'dynamic-style' aplicados a ele.</p>
</div>

Deve ser passado um objeto JavaScript no qual os nomes das propriedades são suas classes CSS e seus valores são avaliados como true ou false, dependendo se a classe deve ser aplicada no momento.

Se o parâmetro fizer referência a um valor observable, a ligação adicionará ou removerá a classe CSS sempre que o observable for alterado. Se o parâmetro não fizer referência a um observable, ele adicionará ou removerá a classe apenas uma vez e não o fará novamente posteriormente.

Style

O binding style é usado para aplicar estilos CSS inline a elementos HTML com base no valor de um observable ou de uma expressão da sua ViewModel. Isso permite que seja alterado os estilos visuais de um elemento diretamente em linha, com base em diferentes condições ou estados do seu aplicativo.

<div>
  <p data-bind="style: { 'color': textColor(), 'font-size': fontSize() + 'px' }">Este parágrafo terá cores e tamanhos de fonte diferentes com base nos valores dos observables 'textColor' e 'fontSize'.</p>
    <p data-bind="style: { 'color': textColor(), 'font-size': fontSize() + 'px' }">Este parágrafo terá cores e tamanhos de fonte diferentes com base nos valores dos observables 'textColor' e 'fontSize'.</p>
    <p data-bind="style: { 'width': width() + 'px', 'height': height() + 'px' }">Este parágrafo terá largura e altura diferentes com base nos valores dos observables 'width' e 'height'.</p>
    <p data-bind="style: 'color: red; background-color: ' + bgColor()">Este parágrafo terá cor de texto vermelha e cor de fundo dinâmica com base no valor do observable 'bgColor'.</p>
</div>

Deve ser passado um objeto JavaScript no qual os nomes das propriedades correspondem aos nomes dos estilos e os valores correspondem aos valores dos estilos que é desejado aplicar.

Se o parâmetro fizer referência a um observable, a ligação atualizará os estilos sempre que o observable for alterado. Se o parâmetro não fizer referência a um observable, ele definirá os estilos apenas uma vez e não os atualizará posteriormente.

Se é desejado aplicar um estilo cujo nome não é um identificador JavaScript legal (porque contém um hífen ou algo do genêro), é possível colocá-lo entre aspas ou usar o nome com o estilo camelCase.

{ 'font-weight': someValue }
{ fontWeight: someValue }

Se aplicar um valor numérico simples a um estilo que requer uma unidade, o KnockoutJs acrescentará px ao valor antes de definir o estilo.

Attr

O binding attr é usado para definir ou atualizar atributos HTML em elementos com base no valor de um observable ou de uma expressão da ViewModel. Isso permite que seja alterado os atributos de elementos HTML de forma dinâmica, com base em diferentes condições ou estados do seu aplicativo.

<div>
  <input type="text" data-bind="attr: { 'disabled': isDisabled(), 'placeholder': inputPlaceholder }" />
    <img data-bind="attr: { 'src': 'images/' + imageName(), 'alt': 'Imagem ' + imageIndex() }" />
    <a data-bind="attr: { 'href': 'https://www.exemplo.com/' + pageLink() }">Clique aqui</a>
    <div data-bind="attr: { 'data-something': someValue }">...</div>
</div>

Deve ser passado um objeto JavaScript no qual os nomes das propriedades correspondem aos nomes dos atributos e os valores correspondem aos valores dos atributos que seja desejado aplicar.

Se o parâmetro fizer referência a um observable, a ligação atualizará o atributo sempre que o observable for alterado. Se o parâmetro não fizer referência a um observable, ele definirá o atributo apenas uma vez e não o atualizará posteriormente.

Como funcionam Bindings no KnockoutJs

Lucas Teixeira dos Santos Santana — Mon, 04 Nov 2024 12:12:39 +0000

Este conteúdo é basicamente uma tradução dos materiais originais. A intenção é adquirir aprendizado sobre o KnockoutJs para Magento 2 e criar conteúdo em português sobre KnockouJs.

Documentação

Bindings

Os bindings no KnockoutJs funcionam através do atributo data-bind em elementos HTML. Esse atributo é onde você especifica o binding que deseja usar e os valores associados.

O atributo data-bind não é nativo do HTML, embora seja perfeitamente aceitável (é estritamente compatível com HTML 5 e não causa problemas com HTML 4. Mas como o navegador não reconhece esse atributo por padrão, é preciso ativar o Knockout para que ele tenha efeito.

Binding syntax

O sistema de vinculação declarativa do KnockoutJs fornece uma maneira concisa e poderosa de vincular dados à IU. Geralmente é fácil e óbvio vincular-se a propriedades de dados simples ou usar uma ligação única. Para ligações mais complexas, ajuda a compreender melhor o comportamento e a sintaxe do sistema de ligação do KnockoutJs.

Today's message is: <span data-bind="text: myMessage"></span>

<!-- related bindings: valueUpdate is a parameter for value -->
Your value: <input data-bind="value: someValue, valueUpdate: 'afterkeydown'" />
 
<!-- unrelated bindings -->
Cellphone: <input data-bind="value: cellphoneNumber, enable: hasCellphone" />

Uma ligação consiste em dois itens, o nome e o valor da ligação, separados por dois pontos. Um elemento pode incluir múltiplas ligações (relacionadas ou não), com cada ligação separada por uma vírgula. Os dados que estão sendo usados nas ligações atuais podem ser referenciados por um objeto. Este objeto é chamado de contexto de ligação (binding context).

O valor de ligação pode ser um único valor, variável ou literal ou quase qualquer expressão JavaScript válida.

As vinculações podem incluir qualquer quantidade de espaços em branco (espaços, tabulações e novas linhas), então é possível usá-los para organizar suas vinculações como desejar.

As ligações podem incluir comentários no estilo JavaScript (//... e /*...*/). Por exemplo:

Caso seja especificado uma vinculação sem um valor, o KnockoutJs dará à vinculação o valor undefined.

A hierarquia de contexto é criada e gerenciada automaticamente pelo KnockoutJS. A lista a seguir lista os diferentes tipos de contextos de ligação fornecidos pelo KO.

Variável de Contexto	Descrição
`$root`	Esta propriedade sempre se refere ao ViewModel de nível superior. Isso torna possível acessar métodos de nível superior para manipular ViewModel. Geralmente esse é o objeto passado para `ko.applyBindings`.
`$data`	Esta propriedade é muito parecida com a palavra-chave `this` do Javascript. A propriedade `$data` em um contexto de ligação refere-se ao objeto ViewModel para o contexto atual.
`$index`	Esta propriedade contém o índice de um item atual de um array dentro de um loop foreach. O valor de `$index` mudará automaticamente conforme e quando a matriz Observable subjacente for atualizada. Obviamente, este contexto está disponível apenas para ligações foreach.
`$parent`	Esta propriedade refere-se ao objeto ViewModel pai. Isso é útil quando se deseja acessar propriedades externas do ViewModel de dentro de um loop aninhado.
`$parentContext`	Esta propriedade é diferente da `$parent`, pois a `$parent` refere-se a dados. Considerando que `$parentContext` refere-se ao contexto de ligação.
`$rawdata`	Este contexto contém o valor bruto do ViewModel na situação atual. Esta propriedade se assemelha a `$data`, mas a diferença é que, se o ViewModel for agrupado em Observable, então `$data` será apenas desembrulhado. O ViewModel e `$rawdata` tornam-se dados observáveis reais.
`$component`	Este contexto é usado para se referir ao ViewModel daquele componente, quando está dentro de um determinado componente.
`$componentTemplateNodes`	É uma representação de uma matriz de nós DOM passados para esse componente específico quando se está dentro de um modelo de componente específico.

O nome da ligação geralmente deve corresponder a uma ligação registrada (integrada ou personalizada) ou ser um parâmetro para outra ligação. Se o nome não corresponder a nenhum deles, o KnockoutJs irá ignorá-lo (sem qualquer erro ou aviso). Portanto, se uma ligação não funcionar, primeiro verifique se o nome está correto.

O valor de ligação pode ser um único valor, variável ou literal ou quase qualquer expressão JavaScript válida. Aqui estão exemplos de vários valores de ligação:

<!-- variable (usually a property of the current view model -->
<div data-bind="visible: shouldShowMessage">...</div>
 
<!-- comparison and conditional, template literals -->
The item is <span data-bind="text: price() > 50 ? `expensive` : `cheap`"></span>.
 
<!-- function call and comparison -->
<button data-bind="enable: parseAreaCode(cellphoneNumber()) != '555'">...</button>
 
<!-- function expression -->
<div data-bind="click: function (data) { myFunction('param1', data) }">...</div>
 
<!-- object literal (with unquoted and quoted property names) -->
<div data-bind="with: {emotion: 'happy', 'facial-expression': 'smile'}">...</div>

Como funcionam Observables no KnockoutJs

Lucas Teixeira dos Santos Santana — Mon, 28 Oct 2024 11:47:05 +0000

Este conteúdo é basicamente uma tradução dos materiais originais. A intenção é adquirir aprendizado sobre o KnockoutJs para Magento 2 e criar conteúdo em português sobre KnockouJs.

Documentação

Observables

O KnockoutJs introduz o conceito de observables, que são propriedades que podem ser monitoradas e atualizadas automaticamente quando seus valores mudam. Essa funcionalidade permite que a interface do usuário reaja dinamicamente a alterações nos dados do Model.

Para criar um observable no KnockoutJs, é possível utilizar a função ko.observable() e atribuir um valor inicial a ela. Para acessar o valor atual de um observable, é possível tratá-lo como uma função. Para só observar algo sem um valor inicial, basta chamar a propriedade Observable sem parâmetros.

let myObservable = ko.observable('Inicial');

console.log(myObservable()); // Irá imprimir 'Inicial'

myObservable('Novo valor');
console.log(myObservable()); // Irá imprimir 'Novo valor'

ko.isObservable: retorna true para observables, observables arrays e todos os computed observables;
ko.isWritableObservable: retorna true para observables, observable arrays e writable computed observables.

Subscriptions

As subscriptions em observables são mecanismos que permitem que seja notificado sempre que o valor de um observable é alterado. Elas são essenciais para acompanhar as mudanças nos observables e reagir a essas mudanças, atualizando a interface do usuário ou executando outras ações quando necessário.

O método subscribe() ***recebe uma função de *callback que será executada sempre que o valor do observable for modificado. A função de callback recebe como argumento o novo valor do observable. Esta função aceita três parâmetros: callback é a função que é chamada sempre que a notificação acontece, target (opcional) define o valor disso na função callback e event (opcional; o padrão é change) é o nome do evento para receber notificação.

let myObservable = ko.observable(0);

// Criando uma subscription no observable
myObservable.subscribe(function (newValue) {
  console.log('Novo valor do observable:', newValue);
}, scope, event);

change: Esse é o evento padrão que aciona a subscription sempre que o valor do observable é alterado. É o evento mais comum e é usado quando nenhum outro evento é especificado explicitamente;
beforeChange: Esse evento é acionado antes que o valor do observable seja alterado. A função de callback receberá dois argumentos: o valor atual do observable e o valor proposto (novo) que será atribuído ao observable. Isso permite que seja executado ações com base no valor atual antes de ser alterado;
afterChange: Esse evento é acionado após o valor do observable ser alterado. A função de callback receberá dois argumentos: o valor anterior do observable (antes da alteração) e o novo valor que foi atribuído ao observable. É útil quando você precisa reagir a uma mudança específica após ela ter ocorrido.
arrayChange: Esse evento é específico para Observables Arrays. Ele é acionado quando há uma alteração em um array observable, como adição, remoção ou substituição de itens no array. A função de callback recebe quatro argumentos: os itens afetados (added, deleted, status e index).

Outro ponto importante e que é possível armazenar a subscription em uma variável e, se necessário cancelar a inscrição usando o método dispose(). Isso é útil quando se deseja desativar temporariamente ou permanentemente a atualização da interface do usuário em resposta a alterações nos observables.

const myObservable = ko.observable();
const subscription = myObservable.subscribe(function (newValue) {
  console.log('Novo valor do observable:', newValue);
});

myObservable(42); // A subscription será acionada e imprimirá "Novo valor do observable: 42" no console.

// Cancelando a subscription
subscription.dispose();

myObservable(100); // Nada será impresso no console, pois a subscription foi cancelada.

Métodos para determinar tipos de observables

isObservable(): Este método é usado para verificar se um valor é um observable. Ele retorna true se o valor for um observable (observable, observableArray, computed ou writable computed), e false caso contrário.
isWritableObservable(): Este método verifica se um valor é um observable gravável (writable observable). Ele retorna true se o valor for um writable observable e false caso contrário;
isComputed(): Este método é usado para verificar se um valor é um Computed Observable. Ele retorna true se o valor for um Computed Observable e false caso contrário;
isPureComputed(): Este método verifica se um valor é um Pure Computed Observable. Um Pure Computed Observable é aquele que depende apenas de outros pure observables e não possui lógica interna de gravação. Ele retorna true se o valor for um Pure Computed Observable e false caso contrário.

Observables Arrays

Observables Arrays são uma extensão dos observables e são usados para lidar com listas de dados que precisam ser observáveis. Ao contrário de um array JavaScript padrão, um Observable Array permite que se acompanhe automaticamente as mudanças nos dados da lista e atualize a interface do usuário de forma reativa.

let myObservableArray = ko.observableArray(['Maçã', 'Banana', 'Laranja']);

myObservable.push('Limão');

Os Observables Arrays possuem métodos específicos que permitem adicionar, remover e manipular itens de forma reativa. Alguns desses métodos são:

indexOf(value): Retorna o índice do primeiro item do array que é igual ao seu parâmetro, ou o valor -1 se nenhum valor correspondente for encontrado.
push(item): Adiciona um novo item ao final do array;
pop(): Remove e retorna o último item do array;
shift(): Remove e retorna o primeiro item do array;
unshift(item): Adiciona um novo item ao início do array;
remove(item): Remove um item específico do array;
removeAll([parametro]): Remove todos os itens do array, podendo receber um parametro em forma de array que removera os itens dentro do(s) parametro(s) passados;
replace(oldItem, newItem): Substitui o item passado no primeiro parâmetro pelo segundo parâmetro;
reverse(): Altera a ordem dos itens do array original e atualiza a interface do usuário para refletir a nova ordem;
reversed(): Retorna uma cópia do array revertida;
splice(index, count, items): Permite adicionar ou remover itens em uma posição específica do array;
slice(): Retorna uma cópia de um subconjunto do array, começando no índice start e indo até o índice end-1. Os valores de start e end são opcionais, e se não forem fornecidos;
sort(): Determina a ordem dos itens. Se a função não for fornecida, o método ordena os itens em ordem alfabética crescente (para strings) ou em ordem numérica crescente (para números);
sorted(): Retorna uma cópia do array ordenado. É preferível ao método sort(), caso seja necessário não alterar o observable array original, mas precisa exibi-lo em uma ordem específica;

Para funções que modificam o conteúdo da matriz, como push e splice, os métodos de KO acionam automaticamente o mecanismo de rastreamento de dependência para que todos os ouvintes registrados sejam notificados da alteração e sua interface seja atualizada automaticamente, o que significa que há uma diferença significativa entre usar Métodos de KO (observableArray.push(...), etc) e métodos de array nativos de JavaScript (observableArray().push(...)), já que os últimos não enviam nenhuma notificação aos assinantes do array de que seu conteúdo foi mudado.

Embora seja possível utilizar subscribe e acessar um observableArray como qualquer outro observável, o KnockoutJs também fornece um método super rápido para descobrir como um array observável foi alterado (quais itens acabaram de ser adicionados, excluídos ou movidos). É possível se inscrever nas alterações de array da seguinte maneira:

const obsArray = ko.observableArray(['Maçã', 'Banana', 'Laranja']);
obsArray.subscribe(fn, thisArg, "arrayChange");

Computed Observables

Computed Observables são funções que dependem de um ou mais observables e serão atualizadas automaticamente sempre que qualquer uma dessas dependências alterar. A função será chamada uma vez a cada vez que qualquer uma de suas dependências alterar, e qualquer valor que retornar será passado para os observables, como elementos de interface do usuário ou outros computed observables.

A principal diferença entre os Computed Observables e os Observables é que os Computed Observables não armazenam diretamente um valor; em vez disso, eles dependem de outros observables para calcular seu valor. Isso significa que o valor de um Computed Observable é sempre atualizado automaticamente quando qualquer um dos observables de que ele depende é modificado.

function AppViewModel() {
    this.firstName = ko.observable('Bob');
    this.lastName = ko.observable('Smith');

        this.fullName = ko.computed(function() {
        return this.firstName() + " " + this.lastName();
    }, scope);
}

Métodos de um Computed Observable

dispose(): Este método é usado para descartar (limpar) um Computed Observable quando ele não é mais necessário. Ele remove todas as assinaturas e dependências associadas ao Computed Observable;
extend(): Este método permite adicionar extensores personalizados a um Computed Observable. Os extensores são funções que podem modificar o comportamento do Computed Observable;
getDependenciesCount(): Este método retorna o número de observables dependentes do Computed Observable;
getDependencies(): Este método retorna uma matriz contendo os observables que são dependências do Computed Observable;
getSubscriptionsCount(): Este método retorna o número de assinaturas atuais do Computed Observable;
isActive(): Este método retorna um valor booleano que indica se o Computed Observable está atualmente ativo (um Computed Observable está ativo se estiver em processo de avaliação devido a uma mudança em suas dependências);
peek(): Este método é semelhante ao operador de parênteses () usado para acessar o valor atual de um Computed Observable. No entanto, o método peek não cria uma dependência entre o Computed Observable e o local em que é chamado;
subscribe(): Este método permite a inscrição para receber notificações sempre que o valor do Computed Observable for alterado.

this

O segundo parâmetro para ko.computed define o valor this ao avaliar o observable calculado. Sem passá-lo, não seria possível fazer referência a this.firstName() ou this.lastName().

Há uma convenção que evita a necessidade de rastrear isso completamente: se o construtor do seu viewmodel copiar uma referência a this em uma variável diferente (tradicionalmente chamada de self), será possível usar self em todo o seu viewmodel e não precisa se preocupar com isso redefinido para se referir a outra coisa.

function AppViewModel() {
    var self = this;
    self.firstName = ko.observable('Bob');
    self.lastName = ko.observable('Smith');

    self.fullName = ko.computed(function() {
        return this.firstName() + " " + this.lastName();
    }, this);

    self.fullName = ko.computed(function() {
        return self.firstName() + " " + self.lastName();
    });
}

Como self é capturado no fechamento da função, ele permanece disponível e consistente em qualquer função aninhada, como o avaliador do computed observable. Essa convenção é ainda mais útil quando se trata de manipuladores de eventos.

Pure computed observables

Caso um computed observable simplesmente calcule e retorne um valor com base em algumas dependências observáveis, é melhor declará-lo como ko.pureComputed em vez de ko.computed.

this.fullName = ko.pureComputed(function() {
    return this.firstName() + " " + this.lastName();
}, scope);

Quando um computed observable é declarado como pure, seu avaliador não modifica diretamente outros objetos ou estado, o KnockoutJs pode gerenciar com mais eficiência sua reavaliação e uso de memória. O KnockoutJs irá suspendê-lo ou liberá-lo automaticamente se nenhum outro código tiver uma dependência ativa dele.

Writable Computed Observables

Os Writable Computed Observables são uma extensão dos Computed Observables que permitem a criação de computed observables que podem ser atualizados tanto por meio da leitura quanto da gravação. Diferente dos Computed Observables convencionais, que apenas calculam seu valor com base em outros observables e não armazenam diretamente um valor, os Writable Computed Observables podem armazenar um valor e também fornecem uma função para atualizar esse valor quando necessário.

Para criar um Writable Computed Observable, é necessário utilizar a função ko.computed com um objeto de configuração que contém duas propriedades principais: read e write. A propriedade read contém a função de cálculo para determinar o valor do observable, enquanto a propriedade write contém a função que é chamada quando deseja-se atualizar o valor do observable.

Introdução ao KnockoutJs

Lucas Teixeira dos Santos Santana — Mon, 21 Oct 2024 14:17:13 +0000

Este conteúdo é basicamente uma tradução dos materiais originais. A intenção é adquirir aprendizado sobre o KnockoutJs para Magento 2 e criar conteúdo em português sobre KnockouJs.

Documentação

Padrão MVVM

A arquitetura MVVM (Model-View-ViewModel) é um padrão de design de software amplamente utilizado em aplicações de interface de usuário. O MVVM é particularmente útil em aplicações com interfaces de usuário complexas e interativas, pois separa claramente a lógica de negócio do comportamento da interface. Isso facilita a manutenção, testabilidade e escalabilidade do código.

Quando o usuário interage com a View, o ViewModel captura essas ações e atualiza os dados correspondentes no Model. Quando o Model é atualizado, o ViewModel recebe essas alterações e atualiza automaticamente a View, refletindo as mudanças na interface do usuário. O ViewModel também pode realizar ações específicas, como enviar requisições ao servidor para buscar ou enviar dados.

Model (Modelo): O Model representa a camada de dados da aplicação. Ele lida com a lógica de negócio, regras de validação, armazenamento e recuperação de dados. O Model geralmente consiste em objetos de dados que representam as entidades e funcionalidades específicas do domínio da aplicação.

View (Visualização): A View é a camada de apresentação da aplicação, responsável por exibir os dados do Model e interagir com o usuário. Ela representa a interface gráfica com a qual o usuário interage para visualizar e manipular os dados. Na arquitetura MVVM, a View é mantida o mais desacoplada possível da lógica de negócio, tornando-a fácil de ser atualizada e substituída.

ViewModel: O ViewModel é a parte central do padrão MVVM. Ele atua como um intermediário entre a View e o Model, realizando a comunicação e a ligação de dados bidirecional entre eles. O ViewModel contém a lógica de apresentação, transformando os dados do Model em uma forma adequada para exibição na View. Além disso, o ViewModel gerencia eventos e respostas do usuário, interagindo com o Model conforme necessário.

KnockoutJs

O Knockout.js é uma biblioteca JavaScript de código aberto que permite a criação de interfaces de usuário dinâmicas e reativas. Ele é especialmente útil para desenvolver aplicações web com interface de usuário complexa e interativa. O KnockoutJs é baseado no padrão de design MVVM (Model-View-ViewModel), que separa a lógica de negócios (Model) da apresentação (View) através de uma camada intermediária chamada ViewModel. É independente de qualquer outra estrutura.

O KnockoutJs foi desenvolvido e é mantido como um projeto de código aberto por Steve Sanderson, um funcionário da Microsoft em 5 de julho de 2010.

KnockoutJs suporta todos os navegadores convencionais - IE 6+, Firefox 3.5+, Chrome, Opera, Safari (desktop/mobile). O atributo data-bind não é nativo do HTML, embora seja um atributo aceitável (é estritamente compatível com o HTML 5 e não causa problemas com o HTML 4, embora um validador indique que é um atributo não reconhecido). Mas como o navegador não sabe o que isso significa, é necessário ativar o KnockoutJs para fazer efeito.

Ao usar KnockoutJs, sua camada de view é simplesmente seu documento HTML com ligações declarativas para vinculá-lo a camada de view-model. Como alternativa, é possível utilizar models que geram HTML usando dados de um modelo da camada de view-model.

Basta colocar o bloco de script na parte inferior de um documento HTML ou colocá-lo na parte superior e agrupar o conteúdo em um manipulador pronto para DOM, como a função $ do jQuery.

ko.applyBindings(myViewModel): é um método usado para aplicar o data binding no KnockoutJs e vincular um ViewModel (ou Model) à interface do usuário (View). Ele conecta o ViewModel aos elementos HTML no DOM, permitindo que os dados do ViewModel sejam refletidos automaticamente na interface do usuário e vice-versa. Ao chamar este método, o KnockoutJs percorre o DOM em busca de elementos que possuam as diretivas de data binding do KnockoutJs e cria as ligações entre esses elementos e as propriedades do ViewModel especificadas nas diretivas.

Opcionalmente, é possível passar um segundo parâmetro para definir em qual parte do documento é desejado pesquisar atributos de vinculação de dados. Por exemplo, ko.applyBindings(myViewModel, document.getElementById('someElementId')). Isso restringe a ativação ao elemento com ID someElementId e seus descendentes, o que é útil caso seja desejável ter vários modelos de exibição e associar cada um a uma região diferente da página.

Instalação

Basta referenciar o arquivo JavaScript usando uma tag <script> em algum lugar de suas páginas HTML.

<script type='text/javascript' src='knockout-3.5.1.js'></script>

Obviamente é necessário atualizar o atributo src para corresponder ao local foi colocado o arquivo baixado.

CDN

Para oferecer as velocidades de download mais rápidas, é preferirível referenciar KnockoutJs em um dos seguintes CDNs de terceiros no site oficial do KnockoutJs da guia de instalação.

Como fazer traduções no Magento 2

Lucas Teixeira dos Santos Santana — Mon, 08 May 2023 12:24:12 +0000

Contextualizando

O que é i18n?

i18n é um acrônimo que origina-se do inglês "internationalization", onde 18 é o número de letras entre o primeiro "*i" e o último "n"*. I18n é a prática de desenvolvimento de software de forma a torná-lo capaz de ser adaptado para diferentes idiomas e localidades sem necessidade de alteração do código-fonte. Isso é feito através da separação das strings de texto presentes no código em arquivos de idioma separados, que podem ser facilmente alterados sem afetar o código em si.

Como o Magento 2 trabalha com traduções?

O Magento 2 permite que a localidade (idioma) seja alterada para a loja, e através da localidade selecionada o Magento busca e aplica as traduções através dos dicionarios na seguinte sequência:

Traduções através do banco de dados (traduções localizadas no banco de dados possuem preferência e substituem as traduções armazenadas em outros locais;
Traduções através do tema:
1. Tema pai (app/design/{area}/{ParentTheme});
2. Tema atual (app/design/{area}/{CurrentTheme});
Traduções através do pacote de linguagem (app/i18n);
Traduções através do módulo (app/code/{Vendor}/{Module}/i18n ou vendor/{vendor}/module-{module}/i18n).

Código para tradução

String em arquivos PHP

Para garantir que uma string seja adicionada ao dicionário e traduzida, deve ser utilizado o método __('{string content}') ao gerar uma string em um arquivo phtml ou PHP.

<?= __('{Custom string}') ?>
<?= __('{Custom string with %1}', $var) ?>

É recomendado, mas não obrigatório, que não coloque variáveis dentro das strings que irão nas funções __() ou Phrase(). O scanner que coleta as frases do código não pode interpretar e coletar o valor da variável quando está nesses locais. Em vez disso, você deve colocar o texto completo na função __() ou Phrase(). Se você precisar especificar uma variável nesses casos, certifique-se de que ela seja traduzida corretamente sempre que for definida como uma string literal.

String em arquivos XML

Para garantir que uma string seja adicionada ao dicionário e traduzida, deve ser utilizado o atributo translate=true ao gerar uma string em um arquivo XML.

<tag name="{tag_name}" xsi:type="string" translate="true">{Custom string}</item>

As strings traduzidas que se originam de arquivos XML não serão renderizadas, a menos que sejam chamadas com um método __(${var}) em arquivos PHP.

__($this->{paramName}->getData('{tag_name}'))

String em arquivos JS

Para garantir que uma string seja adicionada ao dicionário e traduzida, deve ser importada a biblioteca mage/translate no arquivo JS e usar a função $.mage.__('{string}') ou $t('{string}').

define ([
    'jquery',
    'mage/translate'
], function ($, $t) {
    $.mage.__('{Custom string}');
    $t('{Custom string}');
    $.mage.__('{Custom string with %1}').replace('%1', {var});
    $t('{Custom string with %1}').replace('%1', {var});
});

String em arquivos de email

Caso seja necessário traduzir strings em templates de e-mail personalizados, basta adicionar as strings de no arquivo de dicionário do idioma, use a diretiva {{trans}} para idicar que é uma string a ser traduzida.

{{trans "{Custom string}"}}
{{trans "{Custom string with %var" var="{variable value}"}}

⚠️ Os templates de e-mail personalizados adicionados através do painel de admintrador não são armazenados no sistema de arquivos e suas strings não são adicionadas ao dicionário. Neste tópico está sendo abordados os arquivos criados via código.

Arquivo CSV

O Magento 2 utiliza arquivos de idioma para armazenar as strings de texto que são exibidas para os usuários. Para isso é necessário criar um arquivo CSV para cada idioma suportado que contêm o texto original e a tradução.

Um dicionário de tradução é um arquivo de valores separados por vírgula (csv) com pelo menos duas colunas: a frase original na localidade en_US e uma tradução dessa frase em outra localidade. A nome do arquivo para a localidade usada em lojas com o português brasileiro deve ser pt_BR.csv

"{Custom string}","{Custom string translated}"
"{Custom string with %1}","{Custom string with %1 translated}"

Finalizando

Valores entre chaves ({test}) devem ser alterados na implementação do código.

Habilitando as alterações

Execute o comando PHP para limpar todos os caches de armazenamento em cache do processos.

php bin/magento cache:clean
php bin/magento cache:flush

Diretórios e Arquivos

Segue a a lista de diretórios e arquivos que devem ser criados para a criaçãod e tradução em um módulo.

- app/
  - code/
    - {Vendor}/
        - {Module}/
          - etc/
            - module.xml
          - i18n/
              - pt_BR.csv
          - registration.php
          - composer.json

Como criar um indexador (indexer) personalizado no Magento 2

Lucas Teixeira dos Santos Santana — Mon, 28 Nov 2022 12:34:05 +0000

Contextualizando

O que é indíce (index)?

Índice é um recurso que o servidores de SQL disponibiliza afim de ordenar dados em uma determinada sequência, afim de retornar os resultados de maneira mais eficiente, ou seja, os índices são empregados em uma consulta para ajudar a encontrar registros com um valor específico em uma coluna de forma rápida, para aumentar o desempenho na execução de consultas.

Os índices fazem a representação dos dados originais para leitura e busca otimizadas, e também, podem conter resultados de agregações e vários cálculos. Os dados de índice sempre podem ser recriados a partir de um dicionário usando um determinado algoritmo.

O que é a indexação?

A indexação é como o Magento transforma dados (como produtos e categorias) para melhorar o desempenho da vitrine da loja. À medida que os dados mudam, os dados transformados devem ser atualizados ou reindexados.

Código para criação do indexador

indexer.xml

Este arquivo deve estar localizado na pasta \{Vendor}\{Module}\etc\indexer.xml.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Indexer/etc/indexer.xsd">
    <indexer id="{index_id}" view_id="{view_id}" class="{Vendor}\{Class}\Model\Indexer\{IndexerClassName}">
        <title translate="true">{Indexer Title}</title>
        <description translate="true">{Indexer Description}</description>

        <fieldset name="{fieldset_id}"
                  source="{Vendor}\{Class}\Model\ResourceModel\Design\Config\Scope\Collection"
                  provider="{Vendor}\{Class}\Model\Indexer\Design\Config\FieldsProvider">
            <field name="{field_id}" xsi:type="filterable" dataType="int"/>
        </fieldset>
        <saveHandler class="{Vendor}\{Class}\Indexer\SaveHandler\{GridName}"/>
        <structure class="{Vendor}\{Class}\Indexer\{GridStructureName}"/>
    </indexer>
</config>

Atributos do indexer

Atributo	Descrição	Obrigatório
id	ID único do índice.	Sim
class	A classe que processa os métodos do indexador (executeFull, executeList, executeRow).	Não
primary	O provedor de código.	Não
shared_index	Use esta opção para melhorar o desempenho se seu indexador estiver relacionado a outro indexador.	Não
view_id	O ID do elemento de visualização definido no arquivo de configuração mview.xml.	Não

Nós filhos do indexer

O nó <indexer> pode alguns nós filhos, o nó <title> (que exibirá como o título do indexador) e o nó <description> (que exibirá a descrição do indexador).

Nó	Descrição
title	O título a ser exibido na página de indexadores.
description	A descrição a ser exibida na página de indexadores.
fieldset	Descreve os campos, a origem e o provedor de dados da tabela de índices simples.
saveHandler	Um ponto de extensão. A classe para processar (excluir, salvar, atualizar) itens ao indexar.
structure	A classe que processa (cria, remove) tabelas de índice simples.

Classe Indexer

Está classe deve implementar as interfaces \Magento\Framework\Indexer\ActionInterface e \Magento\Framework\Mview\ActionInterface, onde será necessário a implementação de quatro métodos com as seguintes descrições

executeFull(): este método realiza a reindexação completa, ou seja, realiza um processamento de todas as entidades de um dicionário específico. Este método também é o realizado quando for executado pela linha de comando;
executeList(array $ids): este método realiza a reindexação de lista, ou seja, realiza o processamento de um conjunto de entradas de dicionário, onde $ids é um array dos IDs das entidades;
executeRow($id): este método realiza a reindexação de linhas, ou seja, realiza o processamento de uma única entrada de um dicionário e funciona em tempo de execução para uma única entidade usando plugins;
execute($ids): este método realiza a reindexação de processos no modo “Atualização de Agendamento” pelo arquivo mview.xml.

<?php

namespace {Vendor}\{Class}\Model\Indexer;

class {IndexerClassName} implements \Magento\Framework\Indexer\ActionInterface, \Magento\Framework\Mview\ActionInterface
{
    public function execute($ids)
    {
        //code here!
    }

    public function executeFull()
    {
        //code here!
    }

    public function executeList(array $ids)
    {
        //code here!
    }

    public function executeRow($id)
    {
        //code here!
    }
}

mview.xml

Este arquivo deve estar localizado na pasta \{Vendor}\{Module}\etc\mview.xml.

<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Mview/etc/mview.xsd">
    <view id="{view_id}" class="{Vendor}\{Class}\Model\Indexer\{IndexerClassName}" group="indexer">
        <subscriptions>
            <table name="{table_name}" entity_column="{entity_id}" />
        </subscriptions>
    </view>
</config>

Atributos do mview

Nós	Descrição	Obrigatório
id	O ID do elemento de visualização.	Sim
class	A classe que processa o método do indexador (execute).	Sim
group	Lista de opções do widget.	Sim

O nó <view> só possui apenas um tipo de nó filho, o nó <subscriptions>, este nó não possui atributos e possui também apenas um tipo de nó como filho, o nó <table>. O nó <table> não possui nenhum nó filho e possui dois atributos: o atributo name é responsável por identificar o nome da tabela que será indexada e o atributo entity_column é o atributo responsável por identificar a coluna de identificador único primário desta tabela.

Comandos

É possível verificar o status de cada indexador através do seguinte comando:

bin/magento indexer:status {index_id}

É possível utilizar o seguinte comando para reindexar todos os indexadores ou indexadores específicos.

# Reindexar um indexador específico
bin/magento indexer:reindex {index_id}

# Reindexar todos os indexadores
bin/magento indexer:reindex

É possível especificar a configuração do indexador com o seguinte comando:

bin/magento indexer:set-mode {realtime|schedule} {index_id}

realtime: Define os indexadores selecionados para atualização ao salvar;
schedule: Define os indexadores especificados a serem salvos de acordo com o cronograma do cron.

Finalizando

Valores entre chaves ({test}) devem ser alterados na implementação do código.

Habilitando as alterações

Apague os arquivos que são gerados na compilação do Magento e execute o comando PHP para gerar a configuração das injeções de dependência e todas as classes ausentes que precisam ser geradas (proxys, interceptors, etc) e para limpar todos os caches de armazenamento em cache do processos.

rm -rf var/generation/
rm -rf generated/
php bin/magento setup:di:compile
php bin/magento cache:clean
php bin/magento flush

Diretórios e Arquivos

Segue a a lista de diretórios e arquivos que devem ser criados.

- app/
  - code/
    - {Vendor}/
        - {Module}/
          - etc/
            - indexer.xml
            - mview.xml
            - module.xml
          - Model/
              - Indexer/
                  - {ClassIndexerName}.php
          - registration.php
          - composer.json

Como configurar e executar alguns tipos de testes para Magento 2

Lucas Teixeira dos Santos Santana — Mon, 14 Nov 2022 14:43:16 +0000

PHP Code Sniffer (PHPCS)

O PHP Code Sniffer (em uma tradução livre, pode ser algo como: Analisador de Código) é uma ferramenta para detectar violações nos padrões de código. Os padrões de código são formados por uma coleção de regras definidas pelos desenvolvedores, o padrão inicial do PHPCS é o PEAR. O PHPCS pode apontar para as recomendações padrões do PHP (PSRs). É necessário ter o PHPCS e o Magento Coding Standard como dependência de desenvolvimento no arquivo composer.json.

{
    ...
    "require-dev": {
        ...
        "squizlabs/php_codesniffer": "{version}",
        "magento/magento-coding-standard": "{version}",
        ...
    },
    ...
}

Para configurar a primeira vez o Magento Coding Standard no PHPCS deve ser executado o seguinte comando:

vendor/bin/phpcs --config-set installed_paths ../../magento/magento-coding-standard/

Para executar os testes deve-se chamar o comando phpcs que estará dentro de ./vendor/bin e referenciar a pasta de destino.

./vendor/bin/phpcs app/code/{Vendor}/{Module}
./vendor/bin/phpcs vendor/{vendor}/module-{module-name}

ruleset.xml

Caso seja necessário personalizar a execução de testes é possível criar um arquivo ruleset.xml (a recomendação é chamá-lo de phpcs-ruleset.xml para não entrar em conflito com os outros arquivos ruleset.xml) no próprio módulo e configurar para que os testes sejam executados de acordo com a configuração deste arquivo.

A documentação necessária explicando tudo sobre o arquivo ruleset.xml está no link PHP_CodeSniffer Ruleset.

./vendor/bin/phpcs app/code/{Vendor}/{Module}
./vendor/bin/phpcs vendor/{vendor}/{module}

PHP Mess Detector (PHPMD)

O PHP Mess Detector (em uma tradução livre, pode ser algo como: Detector de Desordem) é uma ferramenta que analisa o código de uma aplicação em PHP e detecta problemas potenciais e a qualidade. Algumas das inúmeras análises possíveis de serem executadas com o PHP Mess Detector são:

Localização de possíveis erros;
Localização de métodos, atributos e argumentos não utilizados;
Violação de convenções de nomenclatura;
Problemas potenciais relacionados ao tamanho do código;
Verifica a complexidade do código.

É necessário ter o PHPMD como dependência de desenvolvimento no arquivo composer.json.

{
    ...
    "require-dev": {
        ...
        "phpmd/phpmd": "{version}",
        ...
    },
    ...
}

Para executar os testes com o PHPMD, deve-se chamar o comando phpmd que estará dentro de ./vendor/bin, referenciar o arquivo ruleset.xml (a recomendação é chamá-lo de phpmd-ruleset.xml para não entrar em conflito com os outros arquivos ruleset.xml) e a pasta de destino.

./vendor/bin/phpmd app/code/{Vendor}/{Module} text app/code/{Vendor}/{Module}/phpmd-ruleset.xml
./vendor/bin/phpmd vendor/{vendor}/{module} text vendor/{vendor}/{module}/phpmd-ruleset.xml

O PHP Mess Detector possui alguns parâmetros que permitem adicionar filtros ao processo de análise e definir o formato de saída do resultado do teste.

ruleset.xml

Caso seja necessário personalizar a execução de testes é possível criar um arquivo ruleset.xml (a recomendação é chamá-lo de phpmd-ruleset.xml para não entrar em conflito com os outros arquivos ruleset.xml) no próprio módulo e configurar para que os testes sejam executados de acordo com a configuração deste arquivo.

A documentação necessária explicando tudo sobre o arquivo ruleset.xml está no link PHPMD doc.

PHP Copy/Paste Detector (PHPCPD)

O PHP Copy/Paste Detector (em uma tradução livre, pode ser algo como: Detector de Copia e Cola) é uma ferramenta para checagem de código duplicado nos arquivos em PHP do módulo. É necessário ter o PHPCPD como dependência de desenvolvimento no arquivo composer.json.

{
    ...
    "require-dev": {
        ...
        "sebastian/phpcpd": "{version}",
        ...
    },
    ...
}

Para executar os testes com o PHPCPD, deve-se chamar o comando phpcpd que estará dentro do diretório ./vendor/bin.

./vendor/bin/phpcpd ./app/code/{Vendor}/{Module} --exclude=./vendor/e3/$1/Test/ --fuzzy --progress --min-lines=0
./vendor/bin/phpcpd ./vendor/{vendor}/{module} --exclude=./vendor/e3/$1/Test/ --fuzzy --progress --min-lines=0

A documentação necessária explicando tudo sobre as opções para a execução do PHPCPD está no link PHPCPD Manual.

PHP Static Analysis (PHPStan)

O PHP Static Analysis (em uma tradução livre, pode ser algo como: Análise Estática) é uma ferramenta focada em encontrar erros no código sem executá-las de fato e sem que sejam feitos testes para as classes, a exatidão de cada linha do código pode ser verificada antes de executar a linha real, ou seja, a PHPStan tem a proposta de adaptar a funcionalidade de um compilador para análise estática do código. Algumas das verificações que o PHPStan realiza são:

Verifica a utilização das chamadas de classes, verificando se o código está realmente sendo utilizado;
Verifica a acessibilidade dos métodos e funções e a coesão entre os argumentos das chamadas com sua assinatura;
Verifica a tipagem do retorno dos métodos e funções;
Verifica a acessibilidade dos atributos e sua tipagem;
Verifica a existência de variáveis (respeitando o escopo e laços de repetição);
Verifica comparações estritas e tipagem de variáveis inúteis.

Para utilizar o PHPStan no Magento 2 é necessário uma extensão que permita a análise do código, é recomendável o módulo PHPStan Inviqa. Basta instalar esse módulo através do composer, é necessário ter o PHPStan como dependência de desenvolvimento no arquivo composer.json.

{
    ...
    "require-dev": {
        ...
        "phpstan/phpstan": "{version}",
        "inviqa/phpstan-magento2": "{version}",
        ...
    },
    ...
}

Para executar os testes com o PHPStan, deve-se chamar o comando analyse que estará dentro de ./vendor/bin/phpstan, referenciar o caminho do arquivo phpstan.neon que será utilizado para configuração e a pasta de destino.

./vendor/bin/phpstan analyse ./app/code/{Vendor}/{Module} --configuration=phpstan.neon
./vendor/bin/phpstan analyse ./vendor/{vendor}/{module} --configuration=phpstan.neon

phpstan.neon

O PHPStan utiliza o formato de configuração chamado neon, que é muito semelhante ao yml.

parameters:
    bootstrap: ../../../../vendor/inviqa/phpstan-magento2/phpstan-bootstrap.php
    level: 5
    paths:
        - ./
    fileExtensions:
        - php
    excludes_analyse:
        - ./etc/*
        - ./Test/*
        - ./test-reports/*
        - ./view/*
    ignoreErrors:
        - '#Call to an undefined method [a-zA-Z0-9\\_]+::(get|set|uns|has)[A-Z]#'

Caso seja necessário a customização do arquivo phpstan.neon basta consultar a documentação abaixo:

Teste Unitário no PHPUnit para aplicar em arquivos do Magento 2

Lucas Teixeira dos Santos Santana — Fri, 14 Oct 2022 12:49:18 +0000

PHPUnit

O PHPUnit é uma ferramenta de testes de unidade que disponibiliza um ecossistema necessário para realizar testes de forma automatizada em PHP. O PHPUnit está disponível para aplicações com o PHP a partir da versão 5.5.
Ele é instalado como uma dependência ao projeto e se adéqua com a estrutura do mesmo. Possui uma CLI (Interface de Linha de Comando) própria com opções de personalização para a forma de executar os testes.
O PHPUnit é baseado na ideia que o desenvolvedor deve encontrar erros no código-fonte o mais rápido possível. Semelhante a outros frameworks de teste unitário, ele usa assertions para verificar se o código-fonte está se comportando como o esperado.
Também suporta a declaração de dependências explícitas entre métodos de teste. Tais dependências não definem a ordem em que os métodos de teste devem ser executados, mas permitem o retorno de uma instância do ambiente do teste por um produtor e a passagem dele para os consumidores dependentes.

Para executar os testes com o PHPUnit, deve-se chamar o comando phpunit que estará dentro de ./vendor/bin/phpunit e referenciar o arquivo phpunit.xml com as configurações que serão utilizados para a execução dos testes.
O Magento 2 por padrão já possui um arquivo phpunit.xml que pode ser utilizado, ele se encontra no caminho ./dev/tests/unit/phpunit.xml.dist. O terceiro argumento passado no comando para a execução de testes será o caminho do módulo.

./vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist app/code/{Vendor}/{Module}
./vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist vendor/{vendor}/{module}

phpunit.xml

Caso seja necessário personalizar a execução de testes (exemplo: ignorar a pasta API do módulo) é possível criar um arquivo phpunit.xml no próprio módulo e configurar para que os testes sejam executados de acordo com a configuração deste arquivo.

./vendor/bin/phpunit -c app/code/{Vendor}/{Module}/phpunit.xml.dist app/code/{Vendor}/{Module}
./vendor/bin/phpunit -c vendor/{vendor}/{module}/phpunit.xml.dist vendor/{vendor}/{module}

O Arquivo de Configuração XML

Código base para a implantação

Para escrever testes com o PHPUnit no Magento 2 basta criar a estrutura de pastas \{Vendor}\{Module}\Test\Unit\{ClassDirectory}\{ClassName}Test estender a classe que \PHPUnit\Framework\TestCase. O PHPUnit localiza os métodos de teste pelo prefixo test no nome do método, e neste contém asserções para validar que o método retorne um valor real equivalente ao esperado.

Classe a ser testada:

<?php

namespace {Vendor}\{Module}\{ClassDirectory};

class {ClassName}
{
    public function {methodName}(): {type}
    {
        // Code here
    }
}

Classe de teste:

<?php

namespace {Vendor}\{Module}\Test\Unit\{ClassDirectory};

use PHPUnit\Framework\TestCase;

class {ClassName}Test extends TestCase
{
    public function test{MethodName}(): {type}
    {
        // Code here
    }
}

Asserções

Asserções são métodos desenvolvidos pelo PHPUnit para assegurar que o valor de um teste é um valor esperado, ou seja, sãos métodos que executam a unidade e certificam que o resultado gerado no teste é o esperado com sucesso ou falham.

Os métodos da classe \PHPUnit\Framework\TestCase que começam com o prefixo assert, são parte importante dos casos de teste e avaliam se certas condições, decisivas para determinar o sucesso ou falha do teste, geram um resultado esperado.

<?php

namespace {Vendor}\{Module}\Test\Unit\{ClassDirectory};

use PHPUnit\Framework\TestCase;

class {ClassName}Test extends TestCase
{
    public function test{MethodName}(): {type}
    {
        // Code here
        $this->assert{Name}({condition});
    }
}

É possível verificar a documentação com todas as asserções fornecidas pelo PHPUnit no link “Asserções do PHPUnit“.

Exceções

Usando o método expectException(), o PHPUnit verifica se durante a exceção do teste é lançada uma exceção dentro do código testado. Além do método expectException() os métodos expectExceptionCode(), expectExceptionMessage() e expectExceptionMessageRegExp() existem para configurar expectativas de exceções lançadas pelo código sob teste.

<?php

namespace {Vendor}\{Module}\Test\Unit\{ClassDirectory};

use PHPUnit\Framework\TestCase;

class {ClassName}Test extends TestCase
{
    public function test{MethodName}(): {type}
    {
        $this->expectException(\Exception::class);
        // Code here
    }
}

Provedor de Dados

Com um método provedor de dados (data provider) o PHPUnit permite que o um método de teste seja executado em diferentes cenários, ou seja, consiste em preparar os dados de entradas para que o teste seja executado diversas vezes com dados diferentes.

Um método provedor de dados deve ser do tipo public, possuir a anotação @dataProvider como o nome do método e retornar um array de arrays. Cada item do array de retorno, o método de teste chamara como argumento.

<?php

namespace {Vendor}\{Module}\Test\Unit\{ClassDirectory};

use PHPUnit\Framework\TestCase;

class {ClassName}Test extends TestCase
{
    /**
     * @dataProvider {dataProviderName}
     */
    public function test{MethodName}({type} $data): {type}
    {
        // Code to test here
    }

    public function {dataProviderName}(): array
    {
        // Code to provide different input data

        return [
          [$data1],
          [$data2],
          [$data3],
          ...
          [$dataN]
        ];
    }
}

Métodos setUp e tearDown

O PHPUnit suporta compartilhamento do código de configuração. Os métodos-modelo setUp() e tearDown() são executados uma vez para cada método de teste (e em novas instâncias) da classe do caso de teste. Ambos os métodos devem ser do tipo protected e não possuir nenhum dado de retorno (void).

Antes que um método seja executado, um método modelo chamado setUp() é invocado. O método setUp() é onde os objetos que serão alvo dos testes são criados.

Uma vez que o método de teste tenha terminado sua execução, seja bem-sucedido ou falho, outro método modelo é invocado tearDown(). O método tearDown() é onde os objetos que foram alvo dos testes são limpos, normalmente, implementa-se o método tearDown() ao alocar recursos externos como arquivos ou sockets no setUp().

<?php

namespace {Vendor}\{Module}\Test\Unit\{ClassDirectory};

use PHPUnit\Framework\TestCase;

class {ClassName}Test extends TestCase
{
    protected function setUp(): void
    {
        // Code to set up test objects
    }

    protected function tearDown(): void
    {
        // Code to tear down test object
    }

    public function test{MethodName}(): {type}
    {
        // Code to test here
    }
}

Dublê de Testes

É possível verificar a documentação com tudo sobre os dublês de testes do PHPUnit no link “Dublês de Testes do PHPUnit“.

Os métodos createMock($type) e getMockBuilder($type) fornecidos pelo PHPUnit podem ser usados em um teste para gerar automaticamente um objeto que possa atuar como um dublê de teste para a classe original especificada. Esse objeto de dublê de teste pode ser usado em cada contexto onde um objeto da classe original é esperado ou requerido.

$this->createMock({Class}::class): este método retorna um objeto de dublê de teste para o tipo especificado (interface ou classe). A criação desse dublê de teste é realizada usando os padrões de boas práticas (os métodos __construct() e __clone() da classe original não são executados) e os argumentos passados para um método do dublê de teste não serão clonados.

$this->getMockBuilder({Class}::class): este método serve para customizar a geração do dublê de teste usando uma interface fluente. Por padrão, todos os métodos da classe original são substituídos com uma implementação simulada que apenas retorna null (sem chamar o método original). É possível configurar essas implementações simuladas para retornar um valor quando chamadas.

setMethods(array $methods): pode ser chamado no objeto getMockBuilder() para especificar os métodos que devem ser substituídos com um dublê de teste configurável. O comportamento dos outros métodos não muda. Se você chamar setMethods(null), então nenhum dos métodos serão substituídos (utilizado até a versão 7.3.X do PHP);
onlyMethods(array $methods): pode ser chamado no objeto getMockBuilder() para especificar os métodos que devem ser substituídos por um dublê de teste configurável. O comportamento dos outros métodos não muda. Cada método deve existir na classe que está sendo criada como dublê de teste (utilizado a partir da versão 7.4.X do PHP);
addMethods(array $methods): pode ser chamado no objeto getMockBuilder() para especificar os métodos que não existem (ainda) na classe de dublê de teste. O comportamento dos outros métodos permanece o mesmo (utilizado a partir da versão 7.4.X do PHP);
setConstructorArgs(array $args): pode ser chamado para fornecer um vetor de parâmetros que é passado ao construtor da classe original (que por padrão não é substituído com uma implementação falsa);
setMockClassName($name): pode ser usado para especificar um nome de classe para a classe de dublê de teste gerada;
disableOriginalConstructor(): pode ser usado para desabilitar a chamada ao construtor da classe original;
disableOriginalClone(): pode ser usado para desabilitar a chamada ao construtor clone da classe original;
disableAutoload(): pode ser usado para desabilitar o __autoload() durante a geração da classe de dublê de teste.

$this->method('{methodName}'): o método method('{methodName}') recebe o nome do método que será testado na classe é tera um retorno void.

$this->method('{methodName}')->willReturn('{valueToReturn}'): o método method('{methodName}') recebe o nome do método que será testado na classe. O método willReturn('{valueToReturn}') retorna um valor simples para corresponder ao teste, esta sintaxe é o mesmo que $this->method('{methodName}')->will($this->returnValue($value)).

$this->method('{methodName}')->returnSelf(): este método retorna o próprio objeto de dublê de teste.

$objectMock->expects($this->once())->method('{methodName}')->with($this->equalTo('something')): verifica se um método foi chamado, e com quais argumentos foi chamado, os métodos expects() e with() são para especificar como essa interação deve se parecer.

O método with() pode receber qualquer número de argumentos, correspondendo ao número de argumentos sendo falsos. É possível especificar restrições mais avançadas do que uma simples igualdade no argumento do método.

Introdução sobre Testes de Unidade em PHP para aplicar no Magento 2

Lucas Teixeira dos Santos Santana — Mon, 03 Oct 2022 14:34:48 +0000

Teste de Unidade

O Teste de Unidade é uma verificação automatizada do funcionamento da menor unidade possível de um sistema, ou seja, consiste em validar os dados de entradas e saídas executando cada trecho de código de forma automática, normalmente, através de métodos públicos em um classe de teste.

Cada teste de unidade deve ser independente, para possibilitar que cada método de uma classe seja testado isoladamente, o que possibilita a manutenção e a escalabilidade dos testes em conjunto com o sistema. O teste de unidade é a primeira abordagem em matéria de confecção de testes mais robustos e confiáveis.

Testes Unitários são primeiramente escritos como uma boa prática para ajudar desenvolvedores a identificar e corrigir defeitos, refatorar o código e servir como documentação para uma unidade de programa sob teste. Para conseguir esses benefícios, testes unitários idealmente deveriam cobrir todos os caminhos possíveis em um programa. Um teste unitário geralmente cobre um caminho específico em uma função ou método. Porém um método de teste não é necessariamente uma entidade encapsulada e independente. Frequentemente existem dependências implícitas entre métodos de teste, escondidas no cenário de implementação de um teste.

Adrian Kuhn

Algumas técnicas de Testes

Caixa-preta

Teste de caixa-preta é um tipo de teste que verifica a saída dos dados usando entradas de vários tipos. Tais entradas não são escolhidas conforme a estrutura do programa. Este tipo de teste também é conhecido como teste funcional, já que busca garantir que os requisitos funcionais do produto estão consistentes. É comumente realizado utilizando-se da experiência do usuário, ou seja, através da interface do produto. Também conhecido como teste comportamental, este tipo de teste tenta encontrar erros nas seguintes categorias:

Funções incorretas ou omitidas;
Erros de interface;
Erros de estrutura de dados ou de acesso a base de dados externa;
Erros de comportamento ou desempenho;
Erros de iniciação e término.
Aplicado durante os últimos estágios do teste, a atenção é focada no domínio da informação.

Caixa-branca

Teste de caixa-branca é uma técnica de teste que usa a perspectiva interna do sistema para modelar os casos de testes. Difere do teste de caixa-preta em que a perspectiva interna do sistema é desconsiderada, sendo testadas e mensuradas somente as interfaces do sistema.

Classe de equivalência

Teste com base na análise de classe de equivalência é uma forma de análise de teste de caixa preta que tenta reduzir o número total de testes possíveis para um conjunto mínimo de testes que revelarão o número máximo de erros possível. Isso consiste em um método que particiona o conjunto de entradas e saídas em um número finito de classe de equivalência que permitem a seleção de um valor de teste representativo para cada classe.

O teste que resulta do valor representativo para uma classe é chamado de "equivalente" aos outros valores na mesma classe, ou seja, espera-se que o objeto testado se comporte de forma semelhante. Se nenhum erro foi localizado no teste do valor representativo, conclui-se que todos os outros valores "equivalentes" também não identificariam quaisquer erros. Essa técnica pode ser aplicada para ajudar a analisar os testes mais significativos a serem conduzidos quando houver muitos testes potenciais a serem conduzidos no tempo disponível.

Análise de valor de limite

Essa técnica complementa o particionamento de equivalência. Para usar a análise do valor limite nos testes, descobrimos os limites do campo que queremos testar, está técnica de teste é utilizada para exercitar os limites do domínio de entrada.

A técnica nos diz que devemos testar um valor imediatamente abaixo do limite, o valor limite e um valor imediatamente acima do valor limite, ou seja, os valores próximos às extremidades das classes focalizando a seleção de Casos de Teste. Focaliza o teste em um ponto propício a erros, os limites de uma classe de equivalência. Os valores esperados de entrada e saída devem ser extraídos da especificação do componente, e então agrupados em conjuntos com fronteiras identificáveis.

Cada conjunto, ou partição, contém valores que se espera que sejam processados pelo componente da mesma forma. É importante considerar ambas as partições válidas e inválidas quando se projetam casos de teste.

Matriz ortogonal

O teste de matriz ortogonal é um ponto médio para problemas com domínio de entrada relativamente pequeno, mas grande demais para testes exaustivos. Esta técnica de teste é muito útil quando há um grande número de dados de entrada, e suas combinações não são viáveis e rentáveis de serem testadas individualmente. Testes de matriz ortogonal fornece cobertura suficientemente completa de um aplicativo com o número mínimo de casos de teste.

É melhor verificar apenas as combinações de dados que são suscetíveis de causar um defeito ao invés de checar todas as variantes possíveis. Se há muitas combinações de dados complicado pode ser muito difícil de determinar as combinações que devem ser verificadas.

Este método detecta e isola todas as falhas de modo singular (pela análise da informação sobre quais testes revelam erros, pode-se identificar quais valores de parâmetro causam a falha). Detecta todas as falhas de modo duplo. A aplicação da técnica de ***análise combinatória aos casos de teste, de forma que cada combinação escolhida pelo testador seja executada pelo menos uma vez. É conhecido como *3-wise, 4-wise, n-wise — quanto maior o N, mais meticuloso é o processo.

Na combinação 1-wise, cada valor de cada item é incluido pelo menos uma vez em um teste. Numa combinação 2-wise, todos os valores de um par de itens são combinados com os outros valores pelo menos uma vez em um teste, na 3-wise todos os valores de 3 itens são combinados pelos menos uma vez em cada caso… e assim sucessivamente.

Orientado a Objetos

O teste orientado a objetos consiste em realizar sequências de envios de mensagens. Essas sequências devem ser escolhidas de maneira a explorar o maior número possível de estados que um objeto possa assumir e as transições entre eles. Pode-se aplicar os testes do tipo caixa branca e caixa preta, contudo podem surgir algumas complicações como o encapsulamento e a herança. Algumas das vantagens dos testes orientados a objetos são:

Redução no tamanho dos métodos através da utilização de heranças;
Algoritmos menos complexos, ou seja, algoritmos com poucas linhas de código, o que aumenta a legibilidade e o entendimento do mesmo;
Facilidade na localização e correção de defeitos;
Encapsulamento, que previne muitos problemas causados pelo escopo de dados sem controle.

Baseado em Erros

Na técnica do teste com base em erro são procurados erros plausíveis, particularidades da implementação quem podem ocasionar defeitos. Aqui casos de teste são projetados para exercitar o projeto ou o código. Este teste é aplicado tanto a atributos quanto a operações. A determinação de erros plausíveis deve ser feita quando funções ou métodos são invocados, o comportamento da operação deve ser examinado.

O sistema deve satisfazer aos requisitos do cliente, o planejamento preliminar para criação de testes baseados em erros começa com o modelo de análise. sendo que três tipos de erros são encontrados neste contexto:

Resultado inesperado;
Uso da operação/mensagem errada;
Invocação incorreta.

Essa técnica tem por objetivo verificar se o software está livre de erros típicos e comuns cometidos pelo desenvolvedor durante o ciclo de desenvolvimento de um software, especificamente durante a fase de implementação.

Base em cenário

O teste com base em cenário busca a validação do que o usuário precisar fazer em relação ao que o produto disponibiliza, ou seja, concentra-se no que o usuário faz, não no que o produto faz, detecta as tarefas por meio de casos de uso, que o usuário precisa realizar depois aplicá-las, bem como suas variantes, aos testes. Cenários descobrem erros de interação, mas para isto os casos de teste precisam ser mais complexos e mais realísticos do que os testes baseados em erro.

O tipo menos detalhado de documentação é o cenário de teste. Um cenário de teste é uma descrição de um objetivo que o usuário pode encontrar ao utilizar o programa. Tipicamente, um cenário de teste vai precisar de diferentes tipos de testes para garantir que o objetivo tenha sido bem testado. Já que os cenários de testes oferecem pouca informação sobre como completar o teste, os testadores tem uma grande flexibilização para buscar uma solução.

Assim como os casos de teste, a flexibilidade dos cenários oferecem prós e contras similares. O conhecimento de causa e as habilidades em testes podem facilitar os testadores a transformar os cenários em ideias concretas, escolher a abordagem mais lógica e rodar os testes que podem extrair os problemas importantes.

Mock Objects

Os mock objects (objetos simulados) são objetos que simulam o comportamento de objetos reais de forma controlada. São normalmente criados para testar o comportamento de outros objetos, ou seja, os mock objects são objetos “falsos” que simulam o comportamento de uma classe ou objeto “real” para que possamos focar o teste na unidade a ser testada.

Os mock objects são úteis quando os objetos reais são difíceis de criar ou impossíveis de serem incorporados no teste de unidade, em vez de usar o objeto real que faz a chamada, usa-se um mock object que simula o comportamento do objeto real.