PHP Coupé - Desenvolvimento rápido e reaproveitável

Aprendendo

Classes

Coupe_Form (0.2)

Métodos para criação de formulários.

Criando um fomulário

Create (atualizado)

Cria o formulário (ainda sem os seus campos).
Recebe como parâmetros uma string que será o indentificador do formulário e um array com as propriedades da tag (como name, post, method, class, etc.).
Se a propriedade 'method' não for informada, usa POST. Se o 'action' não for informado, submete para a mesma página.

Recebe: ($string=indentificador_form [, $array=configuracoes_da_tag_form])
Retorna: VOID (apenas cria um novo formulário dentro do vetor 'forms')

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create("meuform", array("name"=>"meuform", "method"=>"POST"));
...

Configurando

Config (atualizado)

Configura como o HTML do formulário será construído, onde:
colapse_label - se posição 1 for TRUE, a tag label engloba a tag do campo (<label><input /></label>)
colapse_div - se posição 2 for TRUE, separa os campos e seus labels dentro de uma div
type_in_id - se posição 3 for TRUE, adiciona o tipo do campo como prefixo do seu id ('#name' se torna '#input_name')
twopoint_label - se posição 4 for TRUE, adiciona dois pontos ao final do nome do label ('Nome' se torna 'Nome:')
break_label - se posição 5 for TRUE, adiciona a tag '<br />' ao final do label para quebrar a linha. (<label></label><br /><input />)

Recebe: ([$bool=label_engloba_campo], [$bool=colocar_dentro_div], [$bool=usar_tipo_do_campo_no_id], [$bool=colocar_2_pontos_no_label], [$bool=quebrar_a_linha])
Retorna: VOID (apenas configura o fomulário para quando for gerar seu HTML)

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create("meuform", array("name"=>"meuform", "method"=>"POST"));
$Coupe->Coupe_Form->config(TRUE, TRUE, FALSE);
...

Set Current

Define o formulario corrente.
Todo formulário criado é definido automáticamente como o formulário corrente.
Usamos essa função para adicionar campos a um formulário criado anteriormente a criação de outro.
Isso evita ter de indicar sempre o formulário na hora de adicionar seus campos.

Recebe: ($string=nome_de_um_formulario_criado)
Retorna: VOID (apenas configura o fomulário indicado como o corrente)

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create("meuform", array("name"=>"meuform", "method"=>"POST"));
$Coupe->Coupe_Form->create("segundoform");
$Coupe->Coupe_Form->setCurrent("meuform");
...

Adicionando campos

Input

Recebe: ($array=configuracoes, [$string=label])
Retorna: VOID (cria o campo na posição 'elements' do vetor do formulário corrente)

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create("meuform");
// gera um campo do tipo texto
$Coupe->Coupe_Form->input( array("name"=>"nome"), "Digite seu nome:" );
// gera um campo do tipo senha
$Coupe->Coupe_Form->input( array("name"=>"senha", "type"=>"password"), "Senha:" );
...

Select

Cria um select e suas opções.
Os options do select devem ser passados como vetor, onde a chave representa a 'value' da option, ou através do método 'options'.

Recebe: ($array=configuracoes, [$string=label], [$array=opcoes_do_select])
Retorna: VOID (cria o campo na posição 'elements' do vetor do formulário corrente)

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create("meuform");
$options = array("brasil"=>"Brasil", "franca"=>"França", "canada"=>"Canadá");
$Coupe->Coupe_Form->select( array("name"=>"pais"), "País:", $options );
...

Textarea

Cria um campo do tipo textarea.
O texto também pode ser passado através do metodo 'text'.

Recebe: ($array=configuracoes, [$string=label], [$string=texto])
Retorna: VOID (cria o campo na posição 'elements' do vetor do formulário corrente)

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create("meuform");
$Coupe->Coupe_Form->textarea( array("name"=>"comentario"), "Comentário:", "" );
...

Option (atualizado)

Adiciona os options a um select já criado.
Os itens devem ser adicionados em um array onde a chave associativa significa o valor e o conteúdo o texto apresentado.
O terceiro parâmetro é opcional e recebe o 'value' que indicará o item selecionado por padrão entre as opções.

Recebe: ($string=nome_do_select, $array=itens_do_option [, $array=value_da(s)_opcao_selecionada(s)])
Retorna: VOID (cria um vetor com chave associativa igual o 'name' do select dentro do vetor 'option' do formulário corrente)

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create("meuform");
// cria o 'select' sem definir as opcoes
$Coupe->Coupe_Form->select( array("name"=>"pais"), "País:" );
// cria o array com as opcoes
$options = array("brasil"=>"Brasil", "franca"=>"França", "canada"=>"Canadá");
// finalmente "alimentamos" o select com as opcoes
$Coupe->Coupe_Form->option( "pais", $options );
...

Selected (novo)

Define quais opçõe de um select devem ter a propriedade 'selected'.

Recebe: ($string=nome_do_select, $array=value_da(s)_opcao_selecionada(s))
Retorna: VOID (alimenta a posicao 'selected' do formulario indicando as opcoes que devem ser marcadas como selecionadas)

...
$options = array("brasil"=>"Brasil", "franca"=>"França", "canada"=>"Canadá");
$Coupe->Coupe_Form->select( array("name"=>"pais"), "País:", $options );
$Coupe->Coupe_Form->selected( "pais", array("franca") );
...

Text

Adiciona o texto a um textarea já criado.

Recebe: ($string=nome_do_campo_de_texto, $string=texto)
Retorna: VOID (cria um vetor com chave associativa igual 'name' da textarea dentro do vetor 'text' do formulário corrente)

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create("meuform");
$Coupe->Coupe_Form->textarea( array("name"=>"comentario"), "Comentário:" );
$Coupe->Coupe_Form->text( "comentario", "Digite nesse campo seus comentários" );
...

HTML (novo)

Adiciona um trecho ao HTML que formará o formulário final.

Recebe: ($string=codigo_html)
Retorna: VOID (cria uma posicao no vetor 'elements' do formulario corrente)

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create("meuform");
$Coupe->Coupe_Form->html("<div class=\"campos\">");
$Coupe->Coupe_Form->input( array("name"=>"nome"), "Digite seu nome:" );
$Coupe->Coupe_Form->input( array("name"=>"senha", "type"=>"password"), "Senha:" );
$Coupe->Coupe_Form->html("</div>");
$Coupe->Coupe_Form->input( array("name"=>"enviar", "type"=>"submit", "value"=>"Enviar") );
...

Fieldset (atualizado)

Cria fieldsets para agruparem o campos criados entre as chamadas desse método.
Para abrir um novo fieldset, basta chamar o método passando a legenda (legend).
Para fechar o fieldset basta chamar o método sem passar o parâmentro legend, ou definir o segundo parâmentro como "close".
Se quiser abrir um fieldset sem legenda, chame o método sem passar o legend e o segundo parâmentro como "open".

Recebe: ([$string=legenda_do_fieldset] [, $string=(open|close)])
Retorna: VOID (adiciona trechos HTML que formam o fieldset no código do formulario quando ele for exibido)

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create("meuform");
$Coupe->Coupe_Form->legend("Dados pessoais:");
$Coupe->Coupe_Form->input( array("name"=>"nome"), "Digite seu nome:" );
$Coupe->Coupe_Form->input( array("name"=>"senha", "type"=>"password"), "Senha:" );
$Coupe->Coupe_Form->legend();
$Coupe->Coupe_Form->input( array("name"=>"enviar", "type"=>"submit", "value"=>"Enviar") );
...

Exibindo o formulário

Write (novo)

Retorna o formulário criado [e indicado] no formato HTML.

Recebe: ($string=nome_do_formulario)
Retorna: STRING (codigo HTML do formulario e seus campos)

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create("meuform");
$Coupe->Coupe_Form->config(TRUE, TRUE, FALSE);
$Coupe->Coupe_Form->input( array("name"=>"nome"), "Digite seu nome:" );
$Coupe->Coupe_Form->input( array("name"=>"senha", "type"=>"password"), "Senha:" );
$Coupe->Coupe_Form->input( array("name"=>"enviar", "type"=>"submit", "value"=>"Enviar") );
return $Coupe->Coupe_Form->write("meuform");
...

Gerenciando erros

Set Error

Permite setar uma mensagem de erro na execução do formulário.
Assim, se o submit não obter sucesso, poderá exibir a mensagem.

Recebe: ($string=nome_formulario, $string=mensagem_de_erro)
Retorna: VOID (apenas seta a mensagem no vetor para poder ser usada mais tarde)

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create("clientes");
$Coupe->Coupe_Form->input( array("name"=>"nome"), "Nome:" );
$Coupe->Coupe_Form->input( array("name"=>"enviar", "type"=>"submit", "value"=>"Enviar") );
if ( isset($_POST["enviar"]) && ! isset($_POST["nome"]) )
{
	$Coupe->Coupe_Form->setError( "clientes", "Digite seu nome." );
}
return $Coupe->Coupe_Form->write("clientes");
...

Get Error

Retorna o primeiro erro encontrado no form ou todos erros que foram setados.

Recebe: ($string=nome_formulario, $bool=retornar_todos)
Retorna: STRING (se retornar somente o primeiro erro) ou ARRAY (se retornar todos erros)

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create("clientes");
$Coupe->Coupe_Form->input( array("name"=>"nome"), "Nome:" );
$Coupe->Coupe_Form->input( array("name"=>"ci"), "CI:" );
$Coupe->Coupe_Form->input( array("name"=>"enviar", "type"=>"submit", "value"=>"Enviar") );
$html = $Coupe->Coupe_Form->write("clientes");
if ( isset($_POST["enviar"]) )
{
	if ( ! isset($_POST["nome"]) )
	{
	$Coupe->Coupe_Form->setError( "clientes", "Digite seu nome." );
	}
	elseif ( ! isset($_POST["ci"]) )
	{
	$Coupe->Coupe_Form->setError( "clientes", "Digite seu identidade." );
	}
}
$first_error = $Coupe->Coupe_Form->getError("clientes");
return '<p>'.$first_error.'</p>'.$html;
...

Verify Error (novo)

Verifica se os campos foram preenchidos corretamente e seta as mensagens de erro ('setError') caso encontre.
Como o campo será avaliado dependerá da classe definida em seus paramentros.
Usamos classes pois assim é possível conciliar com validação do lado cliente com Javascript.
O nome das classes para validação são pré-definidos e são os mesmo do JS VForm <http://www.samuelcorradi.com.br/vform>
OBS: Para trabalhar junto com o VForm, ainda falta algumas implementações.
vObrigatorio - indica que o campo eh obrigatorio.

Recebe: ($string='nome_form')
Retorna: VOID (TRUE me caso de erro encotrado ou FALSE caso nao haja erros)

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create("clientes");
// cria o campo de nome com a classe que indica que eh um campo obrigatorio
$Coupe->Coupe_Form->input( array("name"=>"nome", "class"=>"vObrigatorio"), "Nome:" );
$Coupe->Coupe_Form->input( array("name"=>"enviar", "type"=>"submit", "value"=>"Enviar") );
// verifica se houve erro na postagem de acordo com as classes dos campos
if ( $Coupe->Coupe_Form->verifyError==TRUE )
{
	return $Coupe->Coupe_Form->getError("clientes");
}
...se nao houve erro, envia mensagem de sucesso
else
{
	return "O campo nome foi preenchido!";
}
...

Preenchendo

Fill (novo)

Preenche os campos do formulário criado de acordo com o array passado.
Sendo que as chaves associativas devem ter o mesmo nome dos campos, e o conteúdo é o valor a ser preenchido.
Se o nome do formulario a ser preenchido não for informado, é usado o formulário corrente.
Dica: Pode-se usar o método 'vector' da classe 'Coupe Database' para gerar um array de uma consulta ao banco de dados.

Recebe: ($array=lista_de_valores, [$string=nome_do_form])
Retorna: VOID (apenas inclui os valores nos campos dentro do vetor do form de acordo com seu tipo)

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create( array("name"=>"contato") );
$Coupe->Coupe_Form->input( array("name"=>"nome"), "Nome:" );
$Coupe->Coupe_Form->input( array("name"=>"email"), "Email:" );
$Coupe->Coupe_Form->textarea( array("name"=>"mensagem"), "Mensagem:" );
$Coupe->Coupe_Form->input( array("name"=>"enviar", "type"=>"submit", "value"=>"Enviar") );
// crio um array com as chaves associativas igual ao nome dos campos
$array = ("nome"=>"Nome da pessoa", "email"=>"Email da pessoa", "mensagem"=>"Sua mensagem!" );
// preencho o formulario usando o array criado
$Coupe->Coupe_Form->fill( $array );
// imprime o formulario preenchido
$Coupe->Coupe_Form->write( "contato" );
...

Get Fill (novo)

Retorna o valor de um campo preenchido pelo método 'fill'.

Recebe: ($string=nome_do_campo, [$string=nome_do_form])
Retorna: STRING

...
// crio um array com as chaves associativas igual ao nome dos campos
$array = ("nome"=>"Nome da pessoa", "email"=>"Email da pessoa", "mensagem"=>"Sua mensagem!" );
// preencho o formulario usando o array criado
$Coupe->Coupe_Form->fill( $array );
// retorna o valor preenchido no campo indicado
return $Coupe->Coupe_Form->getFill( "mensagem" );
...

Outras utilidades

Mail

Cria automaticamente uma mensagem para ser enviada por email de acordo com o form criado (e indicado) e o POST submetido.
Básicamente cria um texto para ser enviado por email usando o label dos campos e seus valores para construir a mensagem.
Permite excluir campos da mensagem, definir um valor padrão para campos não preenchidos e um cabecalho com IP e data/hora.

Recebe: ($string=nome_do_formulario, [$bool=enviar_ip_e_hora], [$array=nao_usar_esses_campos])
Retorna: STRING (mensagem com os labels e valores dos campos postados)

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create( array("name"=>"contato") );
$Coupe->Coupe_Form->input( array("name"=>"nome"), "Nome:" );
$Coupe->Coupe_Form->input( array("name"=>"email"), "Email:" );
$Coupe->Coupe_Form->textarea( array("name"=>"mensagem"), "Mensagem:" );
$Coupe->Coupe_Form->input( array("name"=>"enviar", "type"=>"submit", "value"=>"Enviar") );
$Coupe->Coupe_Form->html( "contato" );
if ( isset($_POST["enviar"]) )
{
	$texto = $Coupe->Coupe_Form->mail( "contato", TRUE, array("enviar") );
	mail("destinatario@exemplo.com.br", "Título", $texto);
}
...

Query (atualizado)

Gera [ou executa] um comando SQL de INSERT, UPDATE, SELECT ou DELETE de acordo com o POST de um determinado formulário.
Possui algums parâmetros que ajudam a controlar como será a query criada. Esses parâmetros são:
$param["select"] - recebe o nome dos campos que se deseja usar no SELECT separados por vírgula;
$param["transform"] - se algum campo do formulário não tiver o mesmo nome na tabela, permite a conversão;
$param["include"] - força inclusão de campos que não estao no formulário, ou nao foram preenchidos, mas que devem ser incluidos na tabela;
$param["exclude"] - recebe um array onde seus valores indicam os campos que não devem entrar na query;
$param["where"] - recebe um array onde seus valores indicam os campos que deve ser usados na cláusula WHERE.

Recebe: ($string=nome_formulario_submetido, $string=nome_da_tabela, $string=acao_select|insert|update, $array=parametros_que_complementam_o_SQL, $bool=executar_query?)
Retorna: STRING (se não foi pedido para executar a query gerada) ou BOOL (se foi pedido para executar a query)

...
$Coupe->import("Coupe_Form");
$Coupe->Coupe_Form->create( array("name"=>"contato") );
// cria os campos !!onde o name eh igual ao nome do campo no banco de dados!!
$Coupe->Coupe_Form->input( array("name"=>"nome"), "Nome:" );
$Coupe->Coupe_Form->input( array("name"=>"email"), "Email:" );
$Coupe->Coupe_Form->textarea( array("name"=>"mensagem"), "Mensagem:" );
$Coupe->Coupe_Form->input( array("name"=>"salvar", "type"=>"submit", "value"=>"Salvar") );
$Coupe->Coupe_Form->html( "contato" );
// diz que nao eh para usar o campo 'salvar' na query gerada
$params = array ( "exclude" => array("salvar") );
// nao pede para executar a query e, por tanto, soh retorna o comando SQL gerado
$query = $Coupe->Coupe_Form->query( "contato", "contacts", "insert", $params );
...

Classes

Mudar idioma: