Aprender sobre sintaxe e código

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:

Implementar corretamente os manipuladores de ações do controlador, as funções auxiliares e chamar as funções auxiliares a partir do código do controlador.
Explicar as diferenças entre expressões vinculadas e não vinculadas.
Explicar como as variáveis globais do Visualforce e os provedores de valor global dos componentes do Aura são diferentes.
Meta ampliada: Explicar a diferença entre “c.”, “c.” e “c:”. (Não, nós não digitamos errado.)

Sintaxe do controlador

Abordamos isto conceitualmente no módulo Conceitos fundamentais dos componentes do Aura , mas queremos reforçar alguns detalhes da sintaxe referentes aos controladores JavaScript do lado do cliente. Este é um exemplo de controlador.

({
    myAction : function(component, event, helper) {
        // add code for the action
    },
    anotherAction : function(component, event, helper) {
        // more code
    },
})

Queremos que você entenda três coisas específicas sobre a sintaxe aqui. Tudo isso é diferente do que você está acostumado com seus controladores do Apex.

Isto não é uma classe. É um objeto JSON que contém um mapa de pares name:value. Ele pode conter apenas manipuladores de ações, que você nunca invoca diretamente.
Seus manipuladores de ações são declarados como funções anônimas atribuídas ao nome da ação (aqui, myAction e anotherAction). Suas funções podem aceitar até três parâmetros e, somente estes parâmetros (componente, evento e auxiliar; embora você possa nomeá-los de outra forma). A estrutura os fornece quando ela chama o manipulador.
O mais importante é que você separa seus pares name:value com uma vírgula, destacada nesta versão gráfica do mesmo código. Uma característica da sintaxe do JavaScript diz que a primeira vírgula neste exemplo é obrigatória, mas a segunda, que parece um erro, é permitida, mas opcional. É uma boa prática sempre incluir a vírgula opcional após seu último manipulador de ações, mesmo ela não sendo necessária e podendo provocar o TOC de algumas pessoas. O motivo para isto é porque, mais tarde, você provavelmente adicionará outro manipulador de ações e esquecerá da vírgula. (Seu humilde autor fez isso tantas vezes que não o admite em público.) E então você receberá um erro críptico e gastará algum tempo tentando descobri-lo. Isto é um desperdício de tempo e é totalmente evitável.

Sintaxe do auxiliar

Coloque funções que queira reutilizar no auxiliar do componente. As funções auxiliares também permitem a especialização de tarefas, como o processamento de dados e o acionamento de ações no lado do servidor. Chame as funções auxiliares referenciando-as por meio do parâmetro helper passado para sua função de ação.

myAction : function(component, event, helper) {
    helper.aHelperFunction(component, 42);
},

Os auxiliares do componente são declarados com uma sintaxe semelhante à dos controladores, como um objeto que contém um mapa de pares name:value. (E, adivinhe: são separados por vírgulas, como o controlador.)

({
    aHelperFunction : function(component, value) {
        // helper code here
    },
})

Porém, há algumas diferenças sobre as quais você precisa saber.

Funções auxiliares podem ser declaradas para pegar qualquer parâmetro que você queira. Você chama os auxiliares, não a estrutura.
Por convenção, passe uma referência do componente que chama o auxiliar como o primeiro parâmetro para o auxiliar.
Auxiliares são singletons e compartilhados por todas as instâncias de componentes. Não mantenha o estado do componente em um auxiliar. Pense nos auxiliares mais como métodos estáticos em seus controladores do Apex.
Você pode adicionar não funções a um auxiliar e ter os valores disponíveis para os manipuladores de ações de seu controlador, por exemplo, uma credencial de API que você deseja carregar apenas uma vez. Mas tenha em mente que ela é uma variável compartilhada, e não há nada que a proteja contra acesso inadequado. Pense cuidadosamente antes de usar essa estratégia.

Controladores vs. Auxiliares

Então, o que você coloca em uma função de manipulador de ações do controlador e o que você coloca em um auxiliar?

Muitas pessoas consideram como melhores práticas manter os manipuladores de ações o mais simples e claros possível e concentrar os detalhes no auxiliar. Está é uma abordagem sensata, mas há outras.

Nosso conselho é colocar código que você quer reutilizar entre os manipuladores de ações no auxiliar. Além disso, é uma questão de gosto e estilo, e dos padrões de codificação de sua organização.

Expressões

A sintaxe das expressões nas marcações do Visualforce e componentes do Aura é semelhante. Veja aqui um exemplo.

The message: {! messageText }

Esta é uma marcação do Visualforce ou de componentes do Aura? É do Visualforce. A mesma marcação lança um erro se for usada em um componente do Aura. ^*

Como é possível distingui-las? A expressão cita messageText, que presumivelmente é um método de propriedade ou de getter no controlador da página, ou talvez em uma extensão do controlador. O valor vem “de algum lugar”, mas há diversas possibilidades. Você realmente não pode distingui-los com o Visualforce.

Os componentes do Aura não permitem que você obtenha um valor de “algum lugar”. Aqui está a marcação correspondente mais provável para o componente do Aura.

The message: {! v.messageText }

A principal diferença, o “v.”, é sutil quando você tem seu primeiro contato com os componentes do Aura. É o provedor de valor para o view, que é o próprio componente, e é a forma como você se refere aos atributos de um componente. Abordaremos os provedores de valor na próxima seção. Por enquanto, saiba apenas que você receberá um erro se deixar o provedor de valor desativado.

Isso é especialmente importante de se lembrar ao converter marcação Visualforce para componentes do Aura. A marcação parece semelhante e é fácil copiar e colar no lugar. Não se esqueça de adicionar o provedor de valor em toda a expressão.

Há dois outros pontos que queremos destacar sobre as expressões dos componentes do Aura e a sintaxe da expressão. Primeiro, na verdade, há dois tipos diferentes de expressões nos componentes do Aura: vinculadas e não vinculadas, que usam delimitadores de expressões diferentes.

Expressão vinculada: {! v.messageText }
Expressão não vinculada: {# v.messageText }

A diferença na sintaxe é de apenas um caractere: o ponto de exclamação versus o hash. A diferença de comportamento pode ser irrelevante ou profunda, dependendo do contexto. A versão não vinculada atua de forma mais parecida com uma expressão do Visualforce. A sintaxe diferente oferece comportamento semelhante; intuitivo, não?

Expressões vinculadas adicionam alguma da magia dos componentes do Aura, criando uma vinculação de duas vias entre todos os usos do valor. Se você muda o valor em um lugar, você o muda em todos os lugares. Você pode ler sobre os detalhes em Vinculação de dados entre componentes.

Segundo, no exemplo a seguir há duas expressões.

<aura:component ...>
    ...
    The message: {!v.message}
    <lightning:button label="Acknowledge"
        onclick="{!c.acknowledgeMessage}"/>
    ...
</aura:component>

A diferença mais óbvia é o provedor de valor, “v.” ou “c.”. “v.” é a visualização, como já vimos. “c.” é o controlador. O “c.” é usado para referenciar ações no controlador. Aqui, vinculamos uma ação ao evento de clique de um botão.

Embora você possa usar um atributo de componente diretamente, como fizemos aqui com o atributo de string {!v.message}, você referencia funções no controlado. Isto é, você não pode chamar tais funções diretamente. O resultado de avaliar a expressão {!c.acknowledgeMessage} é uma referência a uma função, não um valor de resultado que possa ser usado diretamente. Adicionar o provedor de valor não muda isso.

____________________

^* Há uma exceção, se messageText for uma variável local <aura:iteration>, mas vamos manter isso simples.

Provedores de valor

Após a última seção, o que falta dizer sobre os provedores de valor? Muita coisa. Mas agora vamos chamar a atenção para outra possível fonte de confusão. Outro escorregador.

Alguns recursos importantes dos componentes do Aura são implementados usando provedores de valor. Nos exemplos anteriores de expressões, usamos v. e c. inúmeras vezes. Estes são os provedores de valor que autoconectam a marcação, os atributos e o controlador do componente. Além de usá-los na marcação, você pode usá-los no código do controlador. Aqui estão algumas linhas de um manipulador de ações, que usa os provedores de valor “v.” e “c.”.

({
    "echo" : function(cmp) {
        // ...
        var action = cmp.get("c.serverEcho");
        action.setParams({ echoString : cmp.get("v.message") });
        // ...
    }
})

Há dois aspectos a serem notados. O primeiro é o método usado para acessar o provedor de valor. Você deve chamar o get() com o nome do atributo que quer acessar, incluindo o provedor de valor. Então, cmp.get("v.message").

O segundo é o deslizador. Observe novamente a primeira linha da função. O que cmp.get("c.serverEcho") está obtendo? Ele está obtendo uma referência para a ação no lado do servidor. Na marcação de um componente, “c.” representa o controlador do lado do cliente. No JavaScript do mesmo componente (manipulador de ações ou auxiliar), “c.” representa o controlador do lado do servidor.

Confuso? Vai piorar. Você também verá “c:” em marcação e em JavaScript. É o “c dois pontos”, em vez de “c ponto”. “c:” é o namespace padrão. Ele representa o código do componente do Aura que você adicionou a sua organização.

Reconhecemos que há uma oportunidade para a confusão, e é por isso que chamamos a atenção aqui. Fique atento ao “c” em todas as suas formas: “c.”, “c.” e “c:”.

Provedores de valor global

Há um tipo de provedor de valor de componente do Aura (provedores de valor global) que se parecem com as variáveis globais do Visualforce. Por exemplo, tanto o Visualforce quanto os componentes do Aura têm $Label e $Resource. Há dois escorregadores possíveis aqui.

Nem toda variável global disponível no Visualforce está disponível como provedor de valor global nos componentes do Aura.
Algumas variáveis globais e provedores de valor global têm o mesmo nome. Mesmo assim, eles se comportam de forma diferente. (Se você não consegue imaginar motivos para isso, volte aos Conceitos fundamentais dos componentes do Aura para se lembrar. Antes que você aceite o desafio. Dica, dica!)

Não tente usar um provedor de valor global sem antes ler a documentação pertinente no Guia do desenvolvedor de Componentes do Aura do Lightning.

Recursos

Administrar eventos usando controladores do lado do cliente
Como compartilhar código JavaScript em um pacote de componentes com auxiliares
Como usar expressões
Vinculação de dados entre componentes
Vinculação de dados nas Melhores práticas de desempenho para os componentes do Lightning
Provedores de valor

Tópicos