JavaScript 3: funções e o botão Guardar

Hoje voltamos ao CRM! Vais juntar o código em funções e criar o botão Guardar, que lê o formulário, valida os dados e mostra uma mensagem verde ou vermelha.

🎯 No fim desta aula vais conseguir

Ligar ficheiros JavaScript a uma página com <script> e perceber porque a ordem importa.
Criar e chamar funções com parâmetros e return.
Ler o que o utilizador escreveu num campo com document.getElementById('…').value.
Fazer um botão executar uma função quando se clica nele (onclick).

🧰 Antes de começar

Abre a pasta meu-crm no VS Code (File → Open Folder…).
Hoje trabalhamos no CRM: abre o index.html com o Live Server (botão direito → Open with Live Server) e abre a Consola (F12).
Vais mexer em dois ficheiros: o index.html e o app.js.

😕 Faltaste à aula 5 ou o teu projeto não funciona? Descarrega o ponto de controlo da aula 5, descompacta-o e trabalha a partir dele.

Parte A — Ligar o JavaScript ao CRM (≈ 10 min)

1 Ligar os scripts

Tal como o <link> liga o CSS (aula 3), a etiqueta <script src="…"> liga um ficheiro JavaScript à página. O CRM vai usar dois:

dados.js → a parte que guarda e lê os dados (o “arquivo”). Por agora está vazio (só tem comentários): vamos enchê-lo na aula 8.
app.js → a parte da interface: o que acontece quando carregas nos botões.

A ordem importa: o browser lê os ficheiros de cima para baixo, e o app.js vai usar coisas que estão no dados.js. É como numa receita: primeiro compras os ingredientes, depois cozinhas. Por isso o dados.js vem primeiro.

E porque é que ficam no fim do <body>? Porque o JavaScript vai procurar os campos do formulário: se corresse antes de o browser ler o formulário, não os encontraria.

<script src="dados.js"></script>
<script src="app.js"></script>

✅ Deves ver: nada de diferente no ecrã (ainda não há código para correr) e nenhum erro vermelho na Consola.

😕 Aparece um erro vermelho na Consola

GET … 404 (Not Found) → o nome do ficheiro não coincide. Confirma que está escrito dados.js e app.js, em minúsculas, e que os ficheiros estão na pasta meu-crm.
Confirma que colaste os scripts no index.html, antes do </body>, e não no app.js.

Parte B — Funções (≈ 25 min)

2 As funções `validarCliente` e `mostrarMensagem`

Uma função é um bloco de código com um nome, que só corre quando a chamamos. Pensa numa máquina de café:

tem um nome (a máquina de café);
recebe ingredientes — os parâmetros, entre parênteses: function validarCliente(nome, email, nif);
faz o trabalho lá dentro, entre chavetas { };
e devolve um resultado com return (o café). Atenção: o return também termina a função naquele momento.

Escrever a função é como escrever uma receita: ainda não se cozinhou nada. Só quando a chamas pelo nome, com os valores entre parênteses (validarCliente('Ana', '', '')), é que ela corre.

Neste bloco há duas funções:

validarCliente → usa as regras da aula 5 e devolve a mensagem de erro, ou '' (texto vazio) se estiver tudo bem. Repara que o email e o NIF só são verificados se estiverem preenchidos (email !== '' && …): não são obrigatórios.
mostrarMensagem → vai buscar o <p id="mensagem"> da aula 2 com document.getElementById('mensagem'), escreve lá o texto (textContent) e muda-lhe a classe (className) para a mensagem ficar verde, vermelha ou azul (as cores já estão no style.css).

Abre o app.js e cola o bloco por baixo do comentário AULA 6: COLAR AQUI:

// Verifica se os dados do cliente estão corretos.
// Devolve uma mensagem de erro, ou '' (texto vazio) se estiver tudo bem.
function validarCliente(nome, email, nif) {
  if (nome === '') {
    return 'O nome é obrigatório.';
  }
  if (email !== '' && !email.includes('@')) {
    return 'O email não é válido (falta o @).';
  }
  if (nif !== '' && (nif.length !== 9 || isNaN(nif))) {
    return 'O NIF tem de ter exatamente 9 algarismos.';
  }
  return '';
}

// Mostra uma mensagem por baixo do formulário.
// tipo: 'sucesso' (verde), 'erro' (vermelho) ou 'info' (azul)
function mostrarMensagem(texto, tipo) {
  const caixa = document.getElementById('mensagem');
  caixa.textContent = texto;
  caixa.className = 'mensagem ' + tipo;
}

Grava e vai à Consola do CRM. Vamos chamar as funções à mão para as testar:

🤔 Prevê antes de carregar Enter: o que devolve cada uma destas chamadas? Escreve, depois experimenta uma a uma na Consola.

validarCliente('', '', '')
validarCliente('Ana', 'ana.gmail.com', '')
validarCliente('Ana', '', '1234')
validarCliente('Ana', '[email protected]', '123456789')
mostrarMensagem('Olá, turma!', 'sucesso')

✅ Deves ver: (1) 'O nome é obrigatório.'; (2) 'O email não é válido (falta o @).'; (3) 'O NIF tem de ter exatamente 9 algarismos.'; (4) '' — texto vazio, ou seja, está tudo bem; (5) a frase Olá, turma! aparece a verde por baixo do formulário.

😕 validarCliente is not defined

Estás na Consola do CRM (index.html) e não na do treino.html?
Gravaste o app.js? Os scripts do passo 1 estão no index.html?
Se aparecer outro erro vermelho antes (por exemplo Unexpected token), há um erro de escrita no app.js que impede o ficheiro todo de funcionar. Volta a copiar o bloco.

Parte C — O botão Guardar (≈ 25 min)

3 A função `guardarCliente`

Esta é a função que vai correr quando se carregar em Guardar. Lê-se assim:

document.getElementById('nome').value → «vai buscar ao documento o campo com o id nome e dá-me o que lá está escrito». Lembras-te dos id da aula 2? É para isto que servem!
.trim() → corta os espaços a mais no início e no fim (' Ana ' passa a 'Ana').
Chama validarCliente e guarda a resposta na variável erro.
Se houver erro (erro !== ''), mostra-o a vermelho e faz return;, que sai da função logo ali: o resto não corre.
Se não houver erro, mostra a mensagem verde de sucesso.

Por agora o cliente ainda não fica guardado em lado nenhum: na aula 7 vamos pô-lo numa lista e na tabela, e na aula 8 guardá-lo a sério.

// Corre quando se clica no botão "Guardar".
function guardarCliente() {
  const nome = document.getElementById('nome').value.trim();
  const email = document.getElementById('email').value.trim();
  const nif = document.getElementById('nif').value.trim();

  const erro = validarCliente(nome, email, nif);
  if (erro !== '') {
    mostrarMensagem(erro, 'erro');
    return;
  }

  mostrarMensagem('Cliente ' + nome + ' guardado com sucesso!', 'sucesso');
}

💡 Cola-o por baixo da chaveta } que fecha a função mostrarMensagem, e não dentro dela. Uma função dentro de outra deixa de ser encontrada pelo botão.

4 O botão

Falta o botão. O atributo onclick="guardarCliente()" quer dizer: «quando clicarem neste botão, chama a função guardarCliente». A isto chama-se um evento: o programa reage a uma ação do utilizador.

E o type="button"? Um botão dentro de um <form>, por omissão, “envia” o formulário e recarrega a página (apagando tudo). Com type="button", ele só faz o que nós mandamos.

No index.html, dentro de <div class="botoes">, por baixo do comentário AULA 6: COLAR AQUI O BOTÃO GUARDAR:

<button type="button" id="botao-guardar" onclick="guardarCliente()">Guardar</button>

✅ Deves ver: um botão Guardar com a cor principal da tua empresa por baixo do formulário.

5 Testar

Grava os dois ficheiros e experimenta no CRM:

Faz isto e carrega em Guardar	Deves ver
Deixa tudo vazio	🔴 O nome é obrigatório.
Nome «Ana Silva» e email «ana.gmail.com»	🔴 O email não é válido (falta o @).
Email certo e NIF «12345678» (8 algarismos)	🔴 O NIF tem de ter exatamente 9 algarismos.
NIF «123456789»	🟢 Cliente Ana Silva guardado com sucesso!

🤔 Pensa: o cliente aparece na tabela depois da mensagem verde? Porquê? (Lê outra vez o último parágrafo do passo 3.)

😕 Não funciona? Abre a Consola (F12)

guardarCliente is not defined → o app.js não está ligado (passo 1), tem um erro de escrita (vê se há outro erro vermelho antes deste), ou colaste o guardarCliente dentro de outra função.
Cannot read properties of null (reading 'value') → um id não coincide: o JavaScript procura 'nome', 'email' e 'nif' e um dos campos do index.html tem outro id (atenção às maiúsculas!).
Cannot set properties of null (setting 'textContent') → falta o <p id="mensagem"> no index.html.
Não acontece nada e não há erros → confirma que escreveste onclick="guardarCliente()", com os parênteses.
A página “pisca” e os campos ficam vazios → falta o type="button" no botão.

🔎 Investiga

Na Consola, escreve mostrarMensagem('Olá!', 'erro'). De que cor fica? E com 'info'? Onde é que estão definidas estas cores?
Na função guardarCliente, apaga o .trim() da linha do nome e grava. Escreve só espaços no Nome e carrega em Guardar. O que acontece? Porque é que isso é mau para o CRM? (Volta a pôr o .trim().)
Ainda no guardarCliente, põe // no início da linha return; (fica um comentário) e tenta guardar com o nome vazio. O que aparece? Porquê? Para que serve, então, o return; sozinho? (Tira o //.)

✍️ Exercícios (fazem parte do teu projeto)

Estes exercícios não têm o código pronto: usa o que aprendeste hoje.

E1 · O botão Limpar

Ao lado do botão Guardar, cria um botão Limpar que apaga tudo o que está escrito no formulário e a mensagem que estiver por baixo dele.

💡 Dica: cria uma função nova no app.js (por exemplo, limparFormulario) e chama-a no onclick do botão novo. Os formulários têm uma função reset() que os limpa: que id tem o formulário no index.html? Para apagar a mensagem, podes reutilizar a mostrarMensagem com um texto vazio. Não te esqueças do type="button"! Para o botão ficar cinzento, usa a classe secundario, que já existe no style.css.

E2 · A mensagem desaparece sozinha

Faz com que as mensagens (verdes e vermelhas) desapareçam sozinhas passados 3 segundos.

💡 Dica: aqui vai uma “receita” pronta. Este código espera 3000 milésimos de segundo (3 segundos) e só depois corre o que está dentro das chavetas:

💡 Em que função deve ficar, para funcionar com todas as mensagens? E o que tens de pôr lá dentro para a caixa da mensagem ficar sem texto?

⭐ Desafio · Validar também o telefone

Faz com que a função validarCliente também verifique o telefone, com a regra do E1 da aula 5 (9 algarismos, a começar por 9 ou por 2), mas só se estiver preenchido (como o email e o NIF). Se estiver mal, o Guardar mostra uma mensagem de erro à tua escolha.

💡 Dica: a função precisa de receber mais um parâmetro, telefone. Depois, no guardarCliente, tens de ler o campo do telefone (qual é o id?) e passá-lo na chamada de validarCliente.

⚠️ Para a aula 7: na próxima aula, a função guardarCliente vai ser substituída por uma versão nova. Se fizeres este desafio, vais ter de voltar a acrescentar o telefone na chamada de validarCliente (na aula 7 será cliente.telefone). Se te esqueceres, ao carregar em Guardar pode aparecer na Consola o erro Cannot read properties of undefined (reading 'length').

📦 O que mostrar ao professor

O index.html tem os dois <script> e a Consola não mostra erros vermelhos.
Na Consola, validarCliente('', '', '') devolve 'O nome é obrigatório.'.
O botão Guardar mostra a mensagem vermelha com dados errados e a verde com dados certos.
Sei explicar o que é um parâmetro e o que faz o return.
E1: o botão Limpar apaga o formulário e a mensagem.
E2: as mensagens desaparecem passados 3 segundos.

⏱️ Se sobrar tempo

Faz o desafio ⭐.
Muda a mensagem de sucesso para incluir também o nome da empresa do cliente (dica: tens de ler mais um campo).
Muda o texto do botão para «Guardar cliente».
Na Consola, chama guardarCliente() diretamente, sem carregar no botão. O que acontece? O que concluis sobre o onclick?

🤖 Pedir ajuda à IA (opcional)

Se tiveres um erro que não percebes, podes pedir a uma IA gratuita (Claude, ChatGPT…) que te explique o erro, sem te dar a solução. Copia este pedido, troca o texto entre [ ] e cola-o na IA:

📖 Palavras novas

<script src="…">: Liga um ficheiro JavaScript à página.
Função: Bloco de código com nome, que só corre quando é chamado: function validarCliente(…) { … }.
Parâmetro: Valor que a função recebe entre parênteses (os “ingredientes”).
return: Devolve o resultado da função e termina-a naquele momento.
Chamar uma função: Mandá-la correr, escrevendo o nome e os valores: mostrarMensagem('Olá!', 'info').
document.getElementById('…'): Vai buscar à página o elemento com aquele id.
.value: O que está escrito num campo do formulário.
.trim(): Corta os espaços no início e no fim de um texto.
textContent: O texto que está dentro de um elemento.
Evento (onclick): Ação do utilizador (como um clique) a que o programa reage.
setTimeout: Corre um pedaço de código depois de esperar algum tempo (em milésimos de segundo).