Bem-vindo ao Cookbook

O primeiro método que você vai precisar para começar a usar o FormHelper é o create(). Este método especial retorna uma tag de abertura de formulário HTML.

create(string $model = null, array $options = array())

Todos os parâmetros são opcionais. Se o create() for chamado sem nenhum parâmetro, ele assume que você está criando um formulário que submete para o controller atual por meio de uma action chamada add() ou edit(). O método padrão para submissão de formulários é o POST. A tag form também é retornada com um DOM ID. O ID é gerado a partir do nome do model e do nome do controller, no formato CamelCase. Se chamarmos create() dentro de uma view do UsersController, veremos uma saída semelhante à esta no código renderizado da view:

<form id="UserAddForm" method="post" action="/users/add">

1. <form id="UserAddForm" method="post" action="/users/add">

Você também pode passar false para o parâmetro $model. Isso faz com que os dados de seu formulário sejam submetidos diretamente dentro do array $this->data (ao invés de dentro de um sub-array $this->data['Model']). Isto pode ser útil para formulários pequenos e que não tenham uma correspondência direta com nenhuma entidade em sua base de dados.

O método create() nos permite ainda mais personalizações através de seus parâmetros. Primeiro, você pode especificar um nome para o model. Ao especificar um model para o form, você está criando um contexto de formulário. Assume-se que todos os campos dentro de um contexto pertençam ao model especificado (a menos que outro model seja explicitamente definido no nome do campo), além de presumir-se que demais models associados façam referência ao model em questão. Se você não especificar um model, então o Cake vai assumir que você está usando o model padrão para o controller atual.

<?php echo $form->create('Recipe'); ?>
 
// saída:
<form id="RecipeAddForm" method="post" action="/recipes/add">

1. <?php echo $form->create('Recipe'); ?>
3. // saída:
4. <form id="RecipeAddForm" method="post" action="/recipes/add">

Isto irá submeter os dados do formulários via POST para a action add() do RecipesController. Mas você também pode usar a mesma lógica para criar um formulário de edição. O FormHelper utiliza a propriedade $this->data para detectar automaticamente se deve criar um form de inserção (add) ou de edição (edit). Se o $this->data contiver um elemento de array com o nome do model, e se este array for composto por um outro array contendo um índice com o mesmo nome da chave primária do model, então o FormHelper irá criar um formulário de edição para o registro atual. Por exemplo, se acessarmos http://example.com/recipes/edit/5, vamos obter o seguinte:

// controllers/recipes_controller.php:
<?php
function edit($id = null) {
	if (empty($this->data)) {
		$this->data = $this->Recipe->findById($id);
	} else {
		// Lógica para salvar o registro aqui
	}
}
?>

// views/recipes/edit.ctp:

// Como $this->data['Recipe']['id'] = 5, um form de edição é que será gerado
<?php echo $form->create('Recipe'); ?>

// saída:
<form id="RecipeEditForm" method="post" action="/recipes/edit/5">
<input type="hidden" name="_method" value="PUT" />

1. // controllers/recipes_controller.php:
2. <?php
3. function edit($id = null) {
4. if (empty($this->data)) {
5. $this->data = $this->Recipe->findById($id);
6. } else {
7. // Lógica para salvar o registro aqui
8. }
9. }
10. ?>
11.  
12. // views/recipes/edit.ctp:
13. // Como $this->data['Recipe']['id'] = 5, um form de edição é que será gerado
14. <?php echo $form->create('Recipe'); ?>
15.  
16. // saída:
17. <form id="RecipeEditForm" method="post" action="/recipes/edit/5">
18. <input type="hidden" name="_method" value="PUT" />

Como este é um formulário de edição, um campo escondido é gerado para sobrescrever o método HTTP padrão.

O array $options é o parâmetro que contém a maioria das configurações do formulário. Este array pode conter diversos pares de chave-valor que afetam a maneira como a tag form é gerada.