Download HTML FormFu - HTML FormFu fonte download

SINOPSE

Nota: Esses exemplos usam o HTML :: FormFU :: Model :: DBIC. A partir de HTML::FormFu v02.005, o módulo html :: formFU :: Model :: DBIC não é incluído com HTML::FormFu e está disponível em uma distribuição independente.

 use HTML::FormFu;

my $form = HTML::FormFu->new;

$form->load_config_file('form.yml');

$form->process( $cgi_query );

if ( $form->submitted_and_valid ) {
    # do something with $form->params
}
else {
    # display the form
    $template->param( form => $form );
}

Se você estiver usando o Catalyst, um exemplo mais adequado pode ser:

 package MyApp::Controller::User;
use Moose;
extends 'Catalyst::Controller::HTML::FormFu';

sub user : Chained CaptureArgs(1) {
    my ( $self, $c, $id ) = @_;

    my $rs = $c->model('Schema')->resultset('User');

    $c->stash->{user} = $rs->find( $id );

    return;
}

sub edit : Chained('user') Args(0) FormConfig {
    my ( $self, $c ) = @_;

    my $form = $c->stash->{form};
    my $user = $c->stash->{user};

    if ( $form->submitted_and_valid ) {

        $form->model->update( $user );

        $c->res->redirect( $c->uri_for( "/user/$id" ) );
        return;
    }

    $form->model->default_values( $user )
        if ! $form->submitted;

}

Nota: porque o "processo" é chamado automaticamente para você pelo controlador catalisador; Se você fizer alguma modificação no formulário dentro do seu método de ação, como adicionar ou alterar elementos, adicionar restrições, etc; Você deve chamar "Processar" novamente antes de usar "submet_and_valid", qualquer um dos métodos listados em "valores e erros de formulário enviado" ou "modificando um formulário enviado" ou renderizando o formulário.

Aqui está um exemplo de um arquivo de configuração para criar um formulário de login básico (todos os exemplos aqui são YAML, mas você pode usar qualquer formato suportado por config :: qualquer), você também pode criar formulários diretamente no seu código PERL, em vez de usar um arquivo de configuração externo.

 ---
action: /login
indicator: submit
auto_fieldset: 1

elements:
  - type: Text
    name: user
    constraints:
      - Required

  - type: Password
    name: pass
    constraints:
      - Required

  - type: Submit
    name: submit

constraints:
  - SingleValue

DESCRIÇÃO

HTML :: FormFu é uma estrutura de formulário HTML que visa ser o mais fácil possível de usar para formulários básicos da Web, mas com o poder e a flexibilidade de fazer qualquer outra coisa que você queira fazer (desde que envolva formas).

Você pode configurar quase qualquer parte do comportamento e saída do FormFU. Por padrão, o FormFu renderiza a marcação "XHTML 1.0 Strict" compatível com o mínimo possível de marcas, mas com nomes de classe CSS suficientes para permitir que uma ampla gama de estilos de saída seja gerada alterando apenas o CSS.

Todos os métodos listados abaixo (exceto "novo") podem ser chamados de método normal no seu objeto $form ou como uma opção no seu arquivo de configuração. Exemplos serão mostrados principalmente na sintaxe da configuração YAML.

Esta documentação segue a convenção de que os argumentos do método cercados por colchetes [] são opcionais e todos os outros argumentos são necessários.

Construindo um formulário

novo

Argumentos: [%Opções]

Valor de retorno: $ form

Crie um novo objeto HTML :: FormFU.

Qualquer método que possa ser chamado no objeto HTML :: FormFU pode ser passado como um argumento para "novo".

 my $form = HTML::FormFu->new({
    action        => '/search',
    method        => 'GET',
    auto_fieldset => 1,
});

load_config_file

Argumentos: $ filename

Argumentos: @FileNames

Valor de retorno: $ form

Aceita um nome de arquivo ou lista de nomes de arquivos, cujos arquivos devem ter qualquer formato reconhecido pela configuração :: qualquer.

O conteúdo de cada arquivo de configuração é passado para "preencher" e, portanto, é adicionado ao formulário.

"load_config_file" pode ser chamado em um arquivo de configuração, de modo a permitir que as configurações comuns sejam mantidas em um único arquivo de configuração que possa ser carregado por qualquer formulário.

 ---
load_config_file:
  - file1
  - file2

YAML Vários documentos em um único arquivo. O marcador inicial do documento é uma linha contendo 3 traços. Vários documentos serão aplicados em ordem, como se vários nomes de arquivos tivessem sido fornecidos.

No exemplo a seguir, vários documentos são aproveitados para carregar outro arquivo de configuração após a adição dos elementos. (Se este fosse um único documento, o load_config_file seria chamado antes elements , independentemente de sua posição no arquivo).

 ---
elements:
  - name: one
  - name: two

---
load_config_file: ext.yml

Os caminhos relativos são resolvidos no diretório "config_file_path", se estiver definido, caso contrário, no diretório de trabalho atual.

Consulte "Melhores práticas" para obter conselhos sobre como organizar arquivos de configuração.

config_callback

Argumentos: %opções

Se definido, os argumentos são usados para criar um objeto Data :: Visitor :: Rallback durante "load_config_file", que pode ser usado para pré-processo da configuração antes de ser enviado para "Popular".

Por exemplo, o código abaixo adiciona um retorno de chamada a um formulário que alterará dinamicamente qualquer valor de configuração que termine em ".yml" para terminar em ".yaml" quando você chama "load_config_file":

 $form->config_callback({
  plain_value => sub {
    my( $visitor, $data ) = @_;
    s/.yml/.yaml/;
  }
});

Valor padrão: não definido

Este método é um 'acessador herdado' especial, o que significa que pode ser definido no formulário, um elemento de bloco ou um único elemento. Quando o valor for lido, se nenhum valor for definido, ele atravessa automaticamente a hierarquia dos pais do elemento, através de qualquer elementos de bloco e até o formulário, procurando um valor definido.

preencher

Argumentos: %opções

Valor de retorno: $ form

Cada tecla/valor de opção passada pode ser qualquer nome de método HTML :: FormFU e argumentos.

Fornece uma maneira simples de definir vários valores ou adicionar vários elementos a um formulário com uma única chamada de método.

Tenta chamar os nomes de métodos em uma ordem semi-intelligente (consulte a fonte de POPULE () em HTML::FormFu::ObjectUtil para obter detalhes).

default_values

Argumentos: %Padrões

Valor de retorno: $ form

Defina os valores padrão de vários campos de um único hash-ref.

As chaves do hash-ref correspondem ao nome de um campo de formulário e o valor é passado para o método padrão do campo.

Isso deve ser chamado depois que todos os campos foram adicionados ao formulário e antes que o "processo" seja chamado (caso contrário, ligue para o "processo" novamente antes de renderizar o formulário).

config_file_path

Argumentos: $ diretório_name

"Config_file_path" define onde os arquivos de configuração serão pesquisados, se um caminho absoluto não for fornecido para "load_config_file".

Valor padrão: não definido

É um acessador herdador.

indicador

Argumentos: $ field_name

Argumentos: & coderef

Se o "indicador" estiver definido como um nome de campo, "enviado" retornará true se um valor para esse nome de campo foi enviado.

Se o "indicador" estiver definido como um código-ref, ele será chamado como uma sub-rotina com os dois argumentos $form e $query , e seu valor de retorno será usado como o valor de retorno para "enviado".

Se o "indicador" não estiver definido, "enviado" retornará true se um valor para qualquer nome de campo conhecido foi enviado.

Auto_fieldset

Argumentos: 1

Argumentos: %opções

Valor de retorno: $ fieldset

Essa configuração é adequada para a maioria dos formulários básicos e significa que você geralmente pode ignorar a adição de Fieldsets.

Chamando $form->auto_fieldset(1) adiciona imediatamente um elemento Fieldset ao formulário. Posteriormente, $form->elements() adicionará todos os elementos (exceto o Fieldsets) a esse Fieldset, em vez de diretamente ao formulário.

Para serem específicos, os elementos são adicionados ao último campos no formulário; portanto, se você adicionar outro Fieldset, outros elementos serão adicionados a esse Fieldset.

Além disso, você pode passar um hashref para auto_fieldset (), e isso será usado para definir padrões para o primeiro Fieldset criado.

Alguns exemplos e sua produção, para demonstrar:

2 elementos sem fieldset.

 ---
elements:
  - type: Text
    name: foo
  - type: Text
    name: bar

<form action="" method="post">
  <div class="text">
    <input name="foo" type="text" />
  </div>
  <div class="text">
    <input name="bar" type="text" />
  </div>
</form>

2 elementos com um "auto_fieldset".

 ---
auto_fieldset: 1
elements:
  - type: Text
    name: foo
  - type: Text
    name: bar

<form action="" method="post">
  <fieldset>
    <div class="text">
      <input name="foo" type="text" />
    </div>
    <div class="text">
      <input name="bar" type="text" />
    </div>
  </fieldset>
</form>

O terceiro elemento está dentro de um novo Fieldset

 ---
auto_fieldset: { id: fs }
elements:
  - type: Text
    name: foo
  - type: Text
    name: bar
  - type: Fieldset
  - type: Text
    name: baz

<form action="" method="post">
  <fieldset id="fs">
    <div class="text">
      <input name="foo" type="text" />
    </div>
    <div class="text">
      <input name="bar" type="text" />
    </div>
  </fieldset>
  <fieldset>
    <div class="text">
      <input name="baz" type="text" />
    </div>
  </fieldset>
</form>

Devido a esse comportamento, se você quiser campos aninhados, precisará adicionar cada campos aninhado diretamente ao pai pretendido.

 my $parent = $form->get_element({ type => 'Fieldset' });

$parent->element('fieldset');

form_error_message

Argumentos: $ string

Normalmente, os erros de entrada fazem com que uma mensagem de erro seja exibida ao lado do campo de formulário apropriado. Se você também deseja uma mensagem de erro geral a ser exibida na parte superior do formulário, você pode definir a mensagem com "form_error_message".

Para definir a classe CSS para a mensagem, consulte "form_error_message_class".

Para alterar a marcação usada para exibir a mensagem, edite o arquivo do modelo form_error_message . Veja "render_method".

É um acessador de saída.

force_error_message

Se verdadeiro, força o "form_error_message" a ser exibido mesmo se não houver erros de campo.

default_args

Argumentos: %Padrões

Defina os padrões que serão adicionados a todos os elementos, restrições etc. do tipo fornecido que é subsequentemente adicionado ao formulário.

Por exemplo, para fazer com que todos os elementos Text tenham um tamanho de 10 e faça com que todos os deflatadores Strftime sejam definidos automaticamente para %d/%m/%Y :

 default_args:
    elements:
        Text:
            size: 10
    deflators:
        Strftime:
            strftime: '%d/%m/%Y'

Um exemplo para fazer com que todos os elementos do DateTime obtenham automaticamente um deflator apropriado e um inflador DateTime:

 default_args:
    elements:
        DateTime:
            deflators:
                type: Strftime
                strftime: '%d-%m-%Y'
            inflators:
                type: DateTime
                parser:
                    strptime: '%d-%m-%Y'

Tipos de pseudo

Como um caso especial, você também pode usar o Block , Field e Input de teclas elements para corresponder a qualquer elemento que does do html :: formfu :: element :: block ou que html :: formfu :: função :: element :: field ou html :: formfu: role ::

Alternativas

Cada chave elements pode conter uma lista any usando o | Divisor: por exemplo

 # apply the given class to any Element of type Password or Button
default_args:
    elements:
        'Password|Button':
            attrs:
                class: novalidate

Combinar ancestral

Cada lista de teclas elements pode conter um tipo começando com + para combinar apenas elementos com um ancestral do tipo dado: por exemplo

 # only apple the given class to an Input field within a Multi block
default_args:
    elements:
        'Input|+Multi':
            attrs:
                class: novalidate

Não combine com ancestral

Cada lista de teclas elements pode conter um tipo começando - para combinar apenas elementos que não têm um ancestral do tipo dado: por exemplo

 # apply the given class only to Input fields that are not in a Multi block
default_args:
    elements:
        'Input|-Multi':
            attrs:
                class: validate

Ordem

Os argumentos são aplicados no mínimo ao pedido mais específico: Block , Field , Input , $type . Dentro de cada um deles, os argumentos são aplicados em ordem de mais curta a mais longa.

A tecla type deve corresponder ao valor retornado por type , por exemplo, "Tipo" em html :: formfu :: element. Se, por exemplo, você terá um elemento personalizado fora do HTML::FormFu::Element::* namespace, que você carrega via $form->element({ type => '+My::Custom::Element' }) , a chave dada para "default_args" não deve incluir a + , como isso é retirado do type() . Exemplo:

 # don't include the leading '+' here
default_args:
    elements:
        'My::Custom::Element':
            attrs:
                class: whatever

# do include the leading '+' here
elements:
    - type: +My::Custom::Element

Confrontos

"Default_args" gera um único hashref para passar para "preencher", mesclando argumentos para cada tipo por sua vez - o que significa "PoPular" é chamado apenas uma vez no total - não uma vez para cada tipo. Como os valores escalares não são mesclados - isso significa que os valores posteriores substituirão os valores anteriores: por exemplo

 # Normally, calling $field->add_attrs({ class => 'input' })
# then calling      $field->add_attrs({ class => 'not-in-multi' })
# would result in both values being retained:
#           class="input not-in-multi"
#
# However, default_args() creates a single data-structure to pass once
# to populate(), so any scalar values will overwrite earlier ones
# before they reach populate().
#
# The below example would result in the longest-matching key
# overwriting any others:
#           class="not-in-multi"
#
default_args:
    elements:
        Input:
            add_attrs:
                class: input
        'Input:-Multi':
            add_attrs:
                class: not-in-multi

Rigor

Nota: Ao contrário dos métodos adequados que possuem aliases, por exemplo, "elementos", que é um alias para "elemento" - as chaves dadas aos default_args devem ser da forma plural, por exemplo:

 default_args:
    elements:          {}
    deflators:         {}
    filters:           {}
    constraints:       {}
    inflators:         {}
    validators:        {}
    transformers:      {}
    output_processors: {}

JavaScript

Se definido, o conteúdo será renderizado em uma tag script , dentro da parte superior do formulário.

javascript_src

Argumentos: $ url

Argumentos: @urls

Adiciona uma tag script para cada URL, imediatamente antes de qualquer seção "JavaScript".

esconder

Argumentos: [%private_stash]

Valor de retorno: %STASH

Fornece um hash-ref no qual você pode armazenar quaisquer dados que você queira associar ao formulário.

 ---
stash:
  foo: value
  bar: value

elementos

elemento

Argumentos: $ tipo

Argumentos: %opções

Valor de retorno: $ elemento

Argumentos: @arrayref_of_types_or_options

Valor de retorno: @Elements

Adiciona um novo elemento ao formulário. Consulte "Campos Core Formulários" em HTML :: FormFU :: Element e "outros elementos principais" em HTML :: FormFu :: Element para uma lista de elementos principais.

Se você deseja carregar um elemento de um espaço para nome diferente de HTML::FormFu::Element:: , você pode usar um nome de pacote totalmente qualificado, prefixando-o com + .

 ---
elements:
  - type: +MyApp::CustomElement
    name: foo

Se um type não for fornecido nas %options , o Text padrão será usado.

"Element" é um pseudônimo para "elementos".

Defladores

Deflator

Argumentos: $ tipo

Argumentos: %opções

Valor de retorno: $ deflator

Argumentos: @arrayref_of_types_or_options

Valor de retorno: @deflators

Um deflator pode estar associado a qualquer campo de formulário e permite fornecer $ field-> padrão com um valor que pode ser um objeto.

Se um objeto não se trata de um valor adequado para exibição, o deflator poderá garantir que o campo do formulário receba um valor de string adequado.

Consulte "Core Deflators" em HTML :: FormFU :: Deflator para obter uma lista de Defladores Core.

Se um atributo name não for fornecido, um novo deflator será criado e adicionado a todos os campos do formulário.

Se você deseja carregar um deflator em um espaço para nome diferente de HTML::FormFu::Deflator:: , você pode usar um nome de pacote totalmente qualificado, prefixando-o com + .

"Deflator" é um pseudônimo para "Defladores".

insert_be antes

Argumentos: $ new_element, $ existing_element

Valor de retorno: $ new_element

O primeiro argumento deve ser o elemento que deseja adicionar, o segundo argumento deve ser o elemento existente que o novo elemento deve ser colocado antes.

 my $new = $form->element(%specs);

my $position = $form->get_element({ type => $type, name => $name });

$form->insert_before( $new, $position );

Na primeira linha do exemplo acima, o elemento $new é inicialmente adicionado ao final do formulário. No entanto, o método insert_before repave o $new elemento, portanto não estará mais no final do formulário. Por esse motivo, se você tentar copiar um elemento de um formulário para outro, ele 'roubará' o elemento, em vez de copiá -lo. Nesse caso, você deve usar clone :

 my $new = $form1->get_element({ type => $type1, name => $name1 })
                ->clone;

my $position = $form2->get_element({ type => $type2, name => $name2 });

$form2->insert_before( $new, $position );

insert_after

Argumentos: $ new_element, $ existing_element

Valor de retorno: $ new_element

O primeiro argumento deve ser o elemento que deseja adicionar, o segundo argumento deve ser o elemento existente que o novo elemento deve ser colocado depois.

 my $new = $form->element(%specs);

my $position = $form->get_element({ type => $type, name => $name });

$form->insert_after( $new, $position );

Na primeira linha do exemplo acima, o elemento $new é inicialmente adicionado ao final do formulário. No entanto, o método insert_after repave o elemento $new , portanto não estará mais no final do formulário. Por esse motivo, se você tentar copiar um elemento de um formulário para outro, ele 'roubará' o elemento, em vez de copiá -lo. Nesse caso, você deve usar clone :

 my $new = $form1->get_element({ type => $type1, name => $name1 })
                ->clone;

my $position = $form2->get_element({ type => $type2, name => $name2 });

$form2->insert_after( $new, $position );

remove_element

Argumentos: $ elemento

Valor de retorno: $ elemento

Remove o $element do formulário ou a variedade de crianças do bloco.

 $form->remove_element( $element );

O elemento órfão não pode ser usado para nada até que seja reaparecido a um formulário ou bloqueio com "insert_be antes" ou "insert_after".

Formulário de lógica e validação

HTML :: FormFU fornece vários estágios para o que é tradicionalmente descrito como validação . Estes são:

Html :: formfu :: filtro
Html :: formfu :: restrição
Html :: formfu :: inflator
Html :: formfu :: validator
Html :: formfu :: Transformer

É um acessador herdador.

force_errors

Forçar uma restrição a falhar, independentemente da entrada do usuário.

Se isso for chamado no tempo de execução, depois que o formulário já foi processado, você deve chamar "Processo" no HTML :: FormFu novamente antes de exibir o formulário para o usuário.

Valor padrão: false

Este método é um 'acessador herdado' especial, o que significa que pode ser definido no formulário, um elemento de bloco, um elemento ou uma única restrição. Quando o valor for lido, se nenhum valor for definido, ele atravessa automaticamente a hierarquia dos pais do elemento, através de qualquer elementos de bloco e até o formulário, procurando um valor definido.

É um acessador herdador.

params_ignore_underscore

Se verdadeiro, causa "parâmetros", "param" e "válido" para ignorar quaisquer campos cujo nome começa com um sublinhado _ .

O campo ainda é processado normalmente e os erros causarão "submetido_and_valid" para retornar false.

Valor padrão: false

Atributos de forma

Todos os atributos são adicionados à tag de início do formulário renderizado.

atributos

 # Example
---
attributes:
  id: form
  class: fancy_form

Obtenha ou defina o atributo de título do formulário.

É um atributo curto.

Classes CSS

form_error_message_class

Atributo da classe para a mensagem de erro exibida na parte superior do formulário.

Veja "form_error_message"

LOCALIZAÇÃO

idiomas

Argumentos: [ @Languages]

Uma lista de idiomas que serão passados para o objeto de localização.

Valor padrão: ['en']

localize_class

Argumentos: [$ Class_name]

ClassName a ser usado para o objeto de localização padrão.

Valor padrão: 'html :: formfu :: i18n'

localizar

loc

Argumentos: [$ key, @arguments]

Compatível com o método maketext em Locale :: MakeText.

localidade

Argumentos: $ Locale

Atualmente usado apenas por html :: formfu :: deflator :: formatNumber e html :: formfu :: filter :: formatNumber.

É um acessador herdador.

Processando um formulário

consulta

Argumentos: [$ query_object]

Argumentos: %params

Forneça um objeto de consulta compatível com CGI ou um hash-ref de nomes/valores enviados. Como alternativa, o objeto de consulta pode ser passado diretamente para o objeto "processo".

Query_type

Argumentos: [$ query_type]

Defina qual módulo está sendo usado para fornecer a "consulta".

O Catalyst :: Controller :: HTML :: FormFu define automaticamente isso como Catalyst .

Os valores válidos são CGI , Catalyst e CGI::Simple .

Valor padrão: 'CGI'

processo

Argumentos: [$ query_object]

Argumentos: [%params]

Processe o objeto de consulta fornecido ou os valores de entrada. process deve ser chamado antes de ligar para qualquer um dos métodos listados em "Valores e erros de formulário enviado" e "modificar um formulário enviado".

process também deve ser chamado pelo menos uma vez antes de imprimir o formulário ou chamar "renderizar" ou "render_data".

Nota aos usuários do Catalyst :: Controller :: HTML :: FormFu: porque o "Process" é automaticamente chamado para você pelo controlador Catalyst; Se você fizer alguma modificação no formulário dentro do seu método de ação, como adicionar ou alterar elementos, adicionar restrições, etc; Você deve chamar "Processar" novamente antes de usar "submet_and_valid", qualquer um dos métodos listados em "valores e erros de formulário enviado" ou "modificando um formulário enviado" ou renderizando o formulário.

Valores e erros de formulário enviados

enviado

Retorna true se o formulário foi enviado. Consulte "Indicador" para obter detalhes sobre como isso é calculado.

submetido_and_valid

Abreviação de $form->submitted && !$form->has_errors

params

Valor de retorno: %params

Retorna um hash-ref de toda a entrada válida para a qual não houve erros.

param_value

Argumentos: $ field_name

Uma versão mais confiável e recomendada de "param". Garantido sempre retornar um único valor, independentemente de ser chamado no contexto da lista ou não. Se vários valores foram enviados, isso retornará apenas o primeiro valor. Se o valor for inválido ou o formulário não foi enviado, ele retornará undef . Isso o torna adequado para uso no contexto da lista, onde é necessário um único valor.

 $db->update({
    name    => $form->param_value('name'),
    address => $form->param_value('address),
});

param_array

Argumentos: $ field_name

Garantido sempre retornar uma reclamação de valores, independentemente do contexto e independentemente de vários valores serem enviados ou não. Se o valor for inválido ou o formulário não foi enviado, ele retornará uma matriz vazia.

param_list

Argumentos: $ field_name

Garantido sempre retornar uma lista de valores, independentemente do contexto. Se o valor for inválido ou o formulário não foi enviado, ele retornará uma lista vazia.

param

Argumentos: [$ field_name]

Valor de retorno: $ input_value

Valor de retorno: @Valid_Names

Não é mais recomendado para uso, pois é difícil prever seu comportamento. Use "param_value", "param_array" ou "param_list".

Um método (readonly) semelhante ao dos CGIs.

Se um nome de campo for fornecido, no List-Context Retornará quaisquer valores válidos enviados para esse campo e, em contexto escalar, retorna apenas o primeiro de qualquer valores válidos enviados para esse campo.

Se nenhum argumento for fornecido, retornará uma lista de todos os nomes de campos de entrada válidos sem erros.

Passar mais de 1 argumento é um erro fatal.

válido

Argumentos: [$ field_name]

Valor de retorno: @Valid_Names

Valor de retorno: $ bool

Se um nome de campo, se for dado, retornará true se esse campo não tivesse erros e false se houver erros.

Se nenhum argumento for fornecido, retornará uma lista de todos os nomes de campos de entrada válidos sem erros.

has_errors

Argumentos: [$ field_name]

Valor de retorno: @Names

Valor de retorno: $ bool

Se um nome de campo, se for dado, retornará true se esse campo tiveram erros e false se não houvesse erros.

Se nenhum argumento for fornecido, retornará uma lista de todos os nomes de campos de entrada com erros.

get_errors

Argumentos: [%Opções]

Valor de retorno: @errors

Retorna uma matriz-ref de objetos de exceção de todos os campos no formulário.

Aceita os argumentos de name , type e stage para restringir os resultados retornados.

 $form->get_errors({
    name  => 'foo',
    type  => 'Regex',
    stage => 'constraint'
});

get_error

Argumentos: [%Opções]

Valor de retorno: $ erro

Aceita os mesmos argumentos que "get_errors", mas retorna apenas o primeiro erro encontrado.

Interação modelo / banco de dados

Consulte o modelo HTML :: FormFU :: para obter mais detalhes e modelos disponíveis.

default_model

Argumentos: $ model_name

Valor padrão: 'dbic'

modelo

Argumentos: [$ model_name]

Valor de retorno: $ modelo

Model_config

Argumentos: %config

Modificando um formulário enviado

add_valid

Argumentos: $ nome, $ valor

HTML::FormFu fornece um sistema de plug-in que permite que os plug-ins sejam facilmente adicionados a um formulário ou elemento, para alterar o comportamento ou saída padrão.

Consulte HTML :: FormFU :: Plugin para obter detalhes.

Personalização avançada

Por padrão, a FormFu renderiza a marcação compatível com o "XHTML 1.0 Rigiction", com o mínimo de marcação extra possível. Muitos ganchos são fornecidos para adicionar nomes de classe CSS gerados programaticamente, para permitir que uma ampla gama de estilos de saída seja gerada alterando apenas o CSS.

A personalização básica da marcação é possível através dos métodos de layout e multi_layout. Isso permite que você reordene a posição de várias partes de cada campo - como o rótulo, o comentário, as mensagens de erro e a tag de entrada - além de inserir quaisquer outras tags arbitrárias que desejar.

Se isso não for suficiente, você poderá personalizar completamente a marcação dizendo ao HTML :: FormFu para usar um mecanismo de renderização externo, como modelo de ferramenta de modelo ou modelo :: liga. Consulte "render_method" e "tt_module" para obter detalhes.

Mesmo se você definir html :: formfu para usar o modelo :: Toolkit para renderizar, os formulários, html :: formFu ainda poderá ser usado em conjunto com o outro sistema de modelos: você prefere usar para o seu próprio layouts de página: <TMPL_VAR form> <form tal:replace="form"></form> formath:  .

A partir de HTML::FormFu v1.00 , o TT não está mais listado um pré -requisito necessário - portanto, você precisará instalá -lo manualmente, se desejar usar os arquivos de modelo.

render_method

Valor padrão: string

Pode ser definido como tt para gerar o formulário com arquivos de modelo externo.

Para personalizar a marcação, você precisará de uma cópia dos arquivos de modelo, local do seu aplicativo. Consulte "Instalando os modelos TT" em html :: formfu :: manual :: livro de receitas para obter mais detalhes.

Você pode personalizar a marcação para um único elemento, definindo "render_method" desse elemento para tt , enquanto o restante do formulário usa a string padrão render-method. Observe que, se você tentar definir o formulário ou o "render_method" de um bloco para tt e definir o "render_method" de um elemento string , essa configuração será ignorada e os elementos filhos ainda usarão o Method tt .

 ---
elements:
  - name: foo
    render_method: tt
    filename: custom_field

  - name: bar

# in this example, 'foo' will use a custom template,
# while bar will use the default 'string' rendering method

É um acessador herdador.

nome do arquivo

Altere o nome do arquivo de modelo usado para o formulário.

Valor padrão: "formulário"

tt_args

Argumentos: [%construtor_arguments]

Aceita um hash-ref de argumentos aprovados para "render_method", que é chamado internamente por "renderização".

Dentro de TT_ARGS, as chaves RELATIVE e RECURSION são substituídas para sempre ser verdadeira, pois esse é um requisito básico para o mecanismo de modelo.

O diretório do sistema que contém os arquivos de modelo HTML :: FormFU é sempre adicionado ao final do INCLUDE_PATH , para que os arquivos do modelo principal sejam encontrados. Você só precisa definir isso você mesmo se tiver sua própria cópia dos arquivos de modelo para fins de personalização.

add_tt_args

Argumentos: [%construtor_arguments]

Garante que o argumento de hash-ref seja fundido com qualquer valor existente de hash-ref de "tt_args".

tt_module

Valor padrão: modelo

O módulo usado quando "render_method" está definido como tt . Deve fornecer uma interface compatível com o modelo.

render_data

Geralmente chamado implicitamente por "renderizar". Retorna a estrutura de dados que normalmente seria passada para a string ou os métodos de renderização tt .

Assim como "renderizar", você deve chamar de "processo" uma vez depois de criar o formulário e antes de ligar para "render_data".

render_data_non_recursive

Como "render_data", mas não inclui os dados para nenhum elemento infantil.

INTROSPECÇÃO

get_fields

Argumentos: [%Opções]

Valor de retorno: @Elements

Retorna todos os campos no formulário (especificamente, todos os elementos que possuem um verdadeiro "is_field" em html :: formfu :: elemento valor).

Aceita argumentos name e type para restringir os resultados retornados.

 $form->get_fields({
    name => 'foo',
    type => 'Radio',
});

Aceita também um regexp para procurar resultados.

 $form->get_elements({
    name => qr/oo/,
});

get_field

Argumentos: [%Opções]

Valor de retorno: $ elemento

Aceita os mesmos argumentos que "get_fields", mas apenas retorna o primeiro campo encontrado.

get_elements

Argumentos: [%Opções]

Valor de retorno: @Elements

Retorna todos os elementos de nível superior no formulário (não recursivo). Consulte "get_all_elements" para uma versão recursiva.

Aceita argumentos name e type para restringir os resultados retornados.

 $form->get_elements({
    name => 'foo',
    type => 'Radio',
});

Aceita também um regexp para procurar resultados.

 $form->get_elements({
    name => qr/oo/,
});

get_element

Argumentos: [%Opções]

Valor de retorno: $ elemento

Aceita os mesmos argumentos que "get_elements", mas retorna apenas o primeiro elemento encontrado.

Consulte "get_all_element" para uma versão recursiva.

get_all_elements

Argumentos: [%Opções]

Valor de retorno: @Elements

Retorna todos os elementos no formulário recursivamente.

Opcionalmente aceita name e type argumentos para restringir os resultados retornados.

 # return all Text elements

$form->get_all_elements({
    type => 'Text',
});

Aceita também um regexp para procurar resultados.

 $form->get_elements({
    name => qr/oo/,
});

Consulte "get_elements" para uma versão não recursiva.

get_all_element

Argumentos: [%Opções]

Valor de retorno: $ elemento

Aceita os mesmos argumentos que "get_all_elements", mas retorna apenas o primeiro elemento encontrado.

 # return the first Text field found, regardless of whether it's
# within a fieldset or not

$form->get_all_element({
    type => 'Text',
});

Aceita também um regexp para procurar resultados.

 $form->get_elements({
    name => qr/oo/,
});

Consulte "get_all_elements" para uma versão não recursiva.

get_deflators

Argumentos: [%Opções]

Valor de retorno: @deflators

Retorna todos os defladores de nível superior de todos os campos.

Aceita argumentos name e type para restringir os resultados retornados.

 $form->get_deflators({
    name => 'foo',
    type => 'Strftime',
});

get_deflator

Argumentos: [%Opções]

Valor de retorno: $ elemento

Aceita os mesmos argumentos que "get_deflators", mas retorna apenas o primeiro deflator encontrado.

get_filters

Argumentos: [%Opções]

Valor de retorno: @Filters

Returns all top-level filters from all fields.

Accepts both name and type arguments to narrow the returned results.

 $form->get_filters({
    name => 'foo',
    type => 'LowerCase',
});

get_filter

Arguments: [%options]

Return Value: $filter

Accepts the same arguments as "get_filters", but only returns the first filter found.

get_constraints

Arguments: [%options]

Return Value: @constraints

Returns all constraints from all fields.

Accepts both name and type arguments to narrow the returned results.

 $form->get_constraints({
    name => 'foo',
    type => 'Equal',
});

get_constraint

Arguments: [%options]

Return Value: $constraint

Accepts the same arguments as "get_constraints", but only returns the first constraint found.

get_inflators

Arguments: [%options]

Return Value: @inflators

Returns all inflators from all fields.

Accepts both name and type arguments to narrow the returned results.

 $form->get_inflators({
    name => 'foo',
    type => 'DateTime',
});

get_inflator

Arguments: [%options]

Return Value: $inflator

Accepts the same arguments as "get_inflators", but only returns the first inflator found.

get_validators

Arguments: [%options]

Return Value: @validators

Returns all validators from all fields.

Accepts both name and type arguments to narrow the returned results.

 $form->get_validators({
    name => 'foo',
    type => 'Callback',
});

get_validator

Arguments: [%options]

Return Value: $validator

Accepts the same arguments as "get_validators", but only returns the first validator found.

get_transformers

Arguments: [%options]

Return Value: @transformers

Returns all transformers from all fields.

Accepts both name and type arguments to narrow the returned results.

 $form->get_transformers({
    name => 'foo',
    type => 'Callback',
});

get_transformer

Arguments: [%options]

Return Value: $transformer

Accepts the same arguments as "get_transformers", but only returns the first transformer found.

clone

Returns a deep clone of the $form object.

Because of scoping issues, code references (such as in Callback constraints) are copied instead of cloned.

ATTRIBUTE ACCESSORS

For the basic method, eg /attributes :

Arguments: [%attributes]

Return Value: $form

As a special case, if no arguments are passed, the attributes hash-ref is returned. This allows the following idioms.

 # set a value
$form->attributes->{id} = 'form';

# delete all attributes
%{ $form->attributes } = ();

All methods documented as 'attribute accessors' also have the following variants generated:

*_xml can be used as a setter, and ensures that its argument is not XML-escaped in the rendered form.

*_loc can he used as a setter, and passes the arguments through "localize".

add_* can be used to append a word to an attribute without overwriting any already-existing value.

 # Example
$form->attributes({ class => 'fancy' });
$form->add_attributes({ class => 'pants' });
# class="fancy pants"

add_*_xml , like add_* , but ensures it doesn't get XML-escaped.

add_*_loc , like add_* , but passing the arguments through "localize".

del_* can be used to remove a word from an attribute value.

 # Example
$form->attributes({ class => 'fancy pants' });
$form->del_attributes({ class => 'pants' });
# class="fancy"

del_*_xml , like del_* , but ensures it doesn't get XML-escaped.

del_*_loc , like del_* , but passing the arguments through "localize".

Also, any attribute method-name which contains the word attributes also has aliases created for all these variants, with the word attributes replaced by attrs .

 # For example, the attributes() method would have all these variant
# methods available

$form->attributes({ class => 'fancy' });
$form->attributes_xml({ title => '<b>fancy</b>' });
$form->attributes_loc({ title => 'fancy' });
$form->add_attributes({ class => 'fancy' });
$form->add_attributes_xml({ title => '<b>fancy</b>' });
$form->add_attributes_loc({ title => 'fancy' });
$form->del_attributes({ class => 'fancy' });
$form->del_attributes_xml({ title => '<b>fancy</b>' });
$form->del_attributes_loc({ title => 'fancy' });

# Because the method contains the word 'attributes', it also gets the
# following short-forms

$form->attrs({ class => 'fancy' });
$form->attrs_xml({ title => '<b>fancy</b>' });
$form->attrs_loc({ title => 'fancy' });
$form->add_attrs({ class => 'fancy' });
$form->add_attrs_xml({ title => '<b>fancy</b>' });
$form->add_attrs_loc({ title => 'fancy' });
$form->del_attrs({ class => 'fancy' });
$form->del_attrs_xml({ title => '<b>fancy</b>' });
$form->del_attrs_loc({ title => 'fancy' });

ATTRIBUTE SHORT-CUTS

All methods documented as 'attribute short-cuts' are short-cuts to directly access individual attribute key/values.

 # Example
$form->id( 'login' );
$id = $form->id;

# is equivalent to:
$form->attributes({ id => 'login' });
$id = $form->attributes->{id};

All attribute short-cuts also have a *_xml variant.

 # Example
$form->id_xml( $xml );

# is equivalent to:
$form->attributes_xml({ id => $xml });

All attribute short-cuts also have a *_loc variant.

 # Example
$form->title_loc( $key );

# is equivalent to:
$form->attributes_loc({ title => $key });

INHERITING ACCESSORS

All methods documented as 'inheriting accessors' can be set on the form, a block element or a single field element. When the value is read, if no value is defined it automatically traverses the element's hierarchy of parents, searching for a defined value.

All inherited accessors also have a *_no_inherit variant, which can be used as a getter to fetch any defined value, without traversing the hierarchy of parents. This variant cannot be used as a setter.

Eg, the "auto_id" has a variant named auto_id_no_inherit .

OUTPUT ACCESSORS

All methods documented as 'output accessors' also have *_xml and *_loc variants.

The *_xml variant can be used as a setter, and ensures that its argument is not XML-escaped in the rendered form.

The *_loc variant can be used as a setter, and passes the arguments through "localize".

Eg, the label method has variants named label_xml and label_loc .

BOOLEAN ATTRIBUTE ACCESSORS

To support boolean attributes, whose value should either be equal to the attribute name, or empty. Any true value will switch the attribute 'on', any false value will remove the attribute.

 # Example

$field->autofocus(1);
# equivalent to:
$field->attributes({ autofocus => 'autofocus' });

$field->autofocus(0);;
# equivalent to:
delete $field->attributes->{autofocus};

ATTRIBUTE SUBSTITUTIONS

Some attributes support character substitutions: the following substitutions are possible:

 %f # $form->id
%n # $field->name
%t # lc( $field->type )
%r # $block->repeatable_count
%s # $error->stage

These allow each field to have consistent attributes, while remaining unique.

DEPRECATION POLICY

We try our best to not make incompatible changes, but if they're required we'll make every effort possible to provide backwards compatibility for several release-cycles, issuing a warnings about the changes, before removing the legacy features.

RESTORING LEGACY HTML CLASSES

v1.00 dropped most of the default HTML class-names, with the intention that each application should define just what it needs, without needing to reset unwanted options first. We also gain the benefit of less markup being generated, speeding up both render and HTTP transfers.

To restore the previous behaviour, set the following options.

If you're using best practices, you'll only need to set these once per-application in your app-wide config file.

 ---
auto_container_class: '%t'
auto_container_label_class: 'label'
auto_container_comment_class: 'comment'
auto_comment_class: 'comment'
auto_container_error_class: 'error'
auto_container_per_error_class: 'error_%s_%t'
auto_error_class: 'error_message error_%s_%t'

DEPRECATED METHODS

See "DEPRECATED METHODS" in HTML::FormFu::Role::Element::Field.

REMOVED METHODS

See also "REMOVED METHODS" in HTML::FormFu::Element.

element_defaults

Has been removed; see "default_args" instead.

model_class

Has been removed; use "default_model" instead.

defaults_from_model

Has been removed; use "default_values" in HTML::FormFu::Model instead.

save_to_model

Has been removed; use "update" in HTML::FormFu::Model instead.

BEST PRACTICES

It is advisable to keep application-wide (or global) settings in a single config file, which should be loaded by each form.

See "load_config_file".

LIVRO DE RECEITAS

HTML::FormFu::Manual::Cookbook

Unicode

HTML::FormFu::Manual::Unicode

EXAMPLES

vertically-aligned CSS

The distribution directory examples/vertically-aligned contains a form with example CSS for a "vertically aligned" theme.

This can be viewed by opening the file vertically-aligned.html in a web-browser.

If you wish to experiment with making changes, the form is defined in file vertically-aligned.yml , and the HTML file can be updated with any changes by running the following command (while in the distribution root directory).

 perl examples/vertically-aligned/vertically-aligned.pl

This uses the Template Toolkit file vertically-aligned.tt , and the CSS is defined in files vertically-aligned.css and vertically-aligned-ie.css .