Inserir dados usando formulários

Objetivos de aprendizagem

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

• Explicar os requisitos essenciais de um formulário do Visualforce.
  
• Distinguir os elementos de formulário do Visualforce que usam o estilo visual da plataforma daqueles que não usam.
  
• Listar quatro ou mais marcas de formulário de entrada padrão.
  
• Criar um formulário do Visualforce para editar e salvar um registro.
  

Nota

Deseja aprender em português (Brasil)? Comece o desafio em um Trailhead Playground de português (Brasil) e copie e cole os valores de português (Brasil). Se você não passar no desafio em sua organização de português (Brasil), recomendamos que (1) mude o local para os Estados Unidos, (2) mude o idioma para inglês, seguindo as instruções aqui, e (3) clique novamente no botão “Validar o desafio”.

Consulte o emblema Trailhead no seu idioma para saber mais sobre como aproveitar a experiência de Trailhead em outros idiomas.

Introdução aos formulários do Visualforce

Criar e editar dados é um aspecto fundamental de qualquer aplicativo. O Visualforce fornece tudo que você precisa para criar facilmente páginas que podem criar novos registros – ou recuperar um registro – editar os valores respectivos e salvar as alterações de volta ao banco de dados.

Combinaremos aqui o controlador padrão com o componente <apex:form> e alguns elementos de formulário de fácil compreensão para criar uma página de edição de registros bastante sofisticada.

Criar um formulário básico

Use <apex:form> e <apex:inputField> para criar uma página para editar dados. Combine <apex:commandButton> com a ação save integrada no controlador padrão para criar um novo registro ou salvar mudanças em um registro existente.

Uma página que permite que alguém edite e atualize um registro deve permitir fazer todas as seguintes coisas.

• Buscar o registro a ser editado e recuperá-lo do banco de dados.
  
• Colocar os dados do registro relevante na página em formato de edição.
  
• Receber um formulário enviado com dados modificados.
  
• Validar os novos valores.
  
• Salvar as modificações válidas de volta no banco de dados.
  
• Fornecer mensagens apropriadas à pessoa que estiver enviando as modificações, quer os novos dados sejam salvos com sucesso, quer haja erros.
  

O Visualforce faz a maioria dessas coisas automaticamente quando você utiliza o controlador padrão e o componente <apex:form>.

Vamos começar com o básico.

1. Abra o Developer Console e clique em File (Arquivo) | New (Nova) | Visualforce Page (Página do Visualforce) para criar uma nova página do Visualforce. Insira AccountEdit para nome da página.
   
2. No editor, substitua qualquer marcação pelo seguinte.
   

   <apex:page standardController="Account">
       <h1>Edit Account</h1>
       <apex:form>
           <apex:inputField value="{! Account.Name }"/>
           <apex:commandButton action="{! save }" value="Save" />
       </apex:form>
   </apex:page>

3. Clique em Preview (Visualizar) para abrir uma visualização da página que você pode consultar enquanto faz alterações. Uma nova janela deverá ser exibida mostrando um formulário com um único campo vazio no corpo.
   
4. Na janela de visualização, adicione o ID de uma conta no URL e pressione ENTER. A URL terá o seguinte formato: https://MyDomainName.lightning.force.com/apex/AccountEdit?core.apexpages.request.devconsole=1&id=001D000000JRBes
   

Agora, você deve ver o nome da conta no campo do formulário. 

Isso comprova o funcionamento de seu controlador padrão e a validade de seu ID de registro.

Pode não parecer muito, mas com meia dúzia de linhas de marcação você obteve um formulário plenamente funcional para atualizar um nome de conta. Experimente!

Os aspectos essenciais deste formulário que você precisa compreender são os seguintes.

• A página utiliza o controlador padrão para contas, definido no componente <apex:page>.
  
• <apex:form> é um componente do Visualforce que reúne tudo dentro dele em um elemento que pode ser enviado de volta ao servidor como parte de uma ação de página. Se você precisar enviar dados de volta ao Salesforce, na maior parte do tempo você o fará dentro de um <apex:form>.
  
• <apex:inputField> cria um campo de formulário na tela para o campo de dados do registro a ele associado. Para isso, basta que você forneça uma expressão que mencione o campo relevante no atributo value. Aqui, aquela expressão é {!Account.Name }, que, como você deve ter adivinhado, é o campo de Nome da conta.
  
• Por fim, <apex:commandButton> adiciona um botão à interface de usuário da página. Quando clicado, esse botão ativa uma ação. Neste caso, a ação é o método de ação save() no controlador padrão. Assim como com o <apex:inputField>, você conecta o <apex:commandButton> com sua ação fazendo referência ao método de ação a ser chamado em uma expressão fornecida ao atributo de ação <apex:commandButton>.
  

Adicionar rótulos de campo e estilo de plataforma

Coloque os elementos de formulário dentro das marcas <apex:pageBlock> e <apex:pageBlockSection> para organizá-los e agrupá-los, e para que o formulário adote o estilo visual da plataforma.

Vamos rever o seu formulário para que você se familiarize mais com ele.

Dentro do componente <apex:form>, envolva os dois elementos de formulário nas marcas <apex:pageBlock> e <apex:pageBlockSection>, de modo que sua marcação seja semelhante a esta.

<apex:page standardController="Account">
	<apex:form>
		<apex:pageBlock title="Edit Account">
			<apex:pageBlockSection>
				<apex:inputField value="{! Account.Name }"/>
			</apex:pageBlockSection>
			<apex:pageBlockButtons>
				<apex:commandButton action="{! save }" value="Save" />
			</apex:pageBlockButtons>
		</apex:pageBlock>
	</apex:form>
</apex:page>

O estilo desta versão do formulário é bem diferente! Assim como acontece com os componentes de saída, quando você usa componentes de entrada dentro das marcas <apex:pageBlock> e <apex:pageBlockSection> eles adotam o estilo visual da plataforma.

1. Abaixo do campo de nome da conta, adicione mais três campos para que sua marcação seja semelhante a esta.
   

   <apex:pageBlockSection columns="1">
       <apex:inputField value="{! Account.Name }"/>
       <apex:inputField value="{! Account.Phone }"/>
       <apex:inputField value="{! Account.Industry }"/>
       <apex:inputField value="{! Account.AnnualRevenue }"/>
   </apex:pageBlockSection>

   Agora, você tem um formulário mais completo e realista para trabalhar. 
   

O componente <apex:inputField> renderiza o widget de entrada apropriado com base no tipo de campo de um objeto padrão ou personalizado. Por exemplo, se você usar uma marca <apex:inputField> para exibir um campo de data, um widget de calendário será exibido no formulário. Se você usar uma marca <apex:inputField> para exibir um campo de lista de opções, como fizemos aqui no campo Setor, uma lista suspensa surgirá.

A marca <apex:inputField> pode ser usada para capturar a entrada do usuário referente a um campo de objeto padrão ou personalizado e respeita todos os metadados ajustados na definição do campo, como se o campo é obrigatório ou exclusivo, ou se o usuário atual tem permissão para ver ou editar.

Exibir mensagens e erros de formulários

Use <apex:pageMessages> para exibir mensagens ou erros de processamento de formulários.

Sua página deve fornecer feedback útil quando as coisas dão errado, como quando um campo obrigatório está ausente ou quando ocorre falha na validação do valor de campo. Na verdade, o controlador padrão lida com tudo isso para você. Tudo que você precisa fazer é dizer a ele onde colocar as mensagens na página.

1. Na marca <apex:pageBlock>, adicione a seguinte linha.
   <apex:pageMessages/>
2. Tente excluir o nome da conta e salvar o registro com um nome em branco. Os erros de validação referentes à página são exibidos.
   

Como é possível notar, <apex:inputField> exibe erros do seu próprio campo, mas para um formulário mais longo constitui uma boa forma de listar todos os erros da página em um lugar na parte superior da página.

O controlador padrão já coleta todas as mensagens da página quando o formulário é processado. O componente <apex:pageMessages> permite exibir essas mensagens sempre que achar necessário.

Editar registros relacionados

Facilite para que os usuários editem informações relacionadas ao fornecer links para os registros relacionados.

Até agora, nossos formulários editaram apenas um registro de cada vez. Mais especificamente, como eles usam o controlador padrão para o objeto da conta, o formulário pode apenas fazer alterações nos registros de conta.

Este não é sempre o fluxo de trabalho mais eficiente para os usuários. Embora não seja possível salvar as alterações a vários tipos de objetos em uma solicitação com o controlador padrão, você pode facilitar a navegação até registros relacionados oferecendo links que realizam ações como editar ou excluir nesses registros.

1. Abaixo da marca de fechamento existente </apex:pageBlock>, adicione a seguinte marcação.
   

   <apex:pageBlock title="Contacts">
       <apex:pageBlockTable value="{!Account.contacts}" var="contact">
           <apex:column>
               <apex:outputLink
                   value="{! URLFOR($Action.Contact.Edit, contact.Id) }">
                   Edit
               </apex:outputLink>
               <apex:outputLink
                   value="{! URLFOR($Action.Contact.Delete, contact.Id) }">
                   Del
               </apex:outputLink>
           </apex:column>
           <apex:column value="{!contact.Name}"/>
           <apex:column value="{!contact.Title}"/>
           <apex:column value="{!contact.Phone}"/>
       </apex:pageBlockTable>
   </apex:pageBlock>

   Uma lista de contatos de contas é exibida abaixo do formulário de edição da conta.
   
2. Tente clicar no link Edit (Editar) de um contato. Para onde o link levou você? O que acontece ao salvar suas alterações ou clicar em cancelar nessa página?
   

O componente <apex:pageBlockTable> cria uma tabela com uma lista de contatos de contas. A novidade aqui é a coluna com os componentes <apex:outputLink>. Eles usam uma expressão que referencia uma variável global, $Action e a combina com a ID do contato dentro da função URLFOR(). O resultado é um link para a página de edição ou exclusão do contato, dependendo da ação referenciada. Este pode ser um atalho muito útil para os usuários deste formulário.

Quero saber mais...

Há muito mais o que aprender sobre a criação de formulários úteis para seus aplicativos da web.

Para começar, o Visualforce oferece cerca de uma dúzia de componentes de entrada, não apenas <apex:inputField>. O <apex:inputField> funciona bem com o controlador padrão e para editar dados de registro diretamente. No caso de páginas em que você está usando seu próprio código de controlador personalizado, ou quando a entrada de formulário não mapeia diretamente para campos em um registro, convém conhecer os outros. A maioria desses componentes têm nomes que começam com apex:input e você pode encontrá-los agrupados na referência de componente. Para controles de listas de seleção e botões de opção, procure os componentes cujos nomes comecem com apex:select.

Para interfaces de usuário que serão usadas em dispositivos móveis, veja <apex:input>, que é projetado para uso em páginas em HTML5 e permite que você use uma miríade de recursos que facilitam o uso dos elementos de usuário de entrada resultantes em dispositivos móveis.

O código que você escreveu aqui usou várias ações fornecidas pelo controlador padrão da página. Nós as chamamos de ações padrão e há várias delas. Existe um conjunto principal que está disponível para todos os objetos com controladores padrão, mas vários dos objetos padrão integrados têm ações adicionais que você pode usar.

Falando em ações, você foi capaz de adicionar ações para editar e excluir contatos relacionados. Como você pode adicionar a capacidade de criar novos contatos relacionados? Não é tão fácil quanto criar um link usando a ação create da maneira usada com edit e delete. Isso ocorre porque essas ações funcionavam em registros existentes, que já tem um relacionamento com a conta relacionada. Mas quando você cria um novo registro, precisa criar o relacionamento por conta própria. Isso exige que você escreva um código de controlador personalizado próprio.

Recursos

• Guia do desenvolvedor do Visualforce: Using Input Components in a Page
• Guia do desenvolvedor do Visualforce: Using Standard Controller Actions
• Guia do desenvolvedor do Visualforce: Valores válidos para a variável global $Action
• Guia do desenvolvedor do Visualforce: Standard Controllers