Descargar HTML FormFu - Descargar el código fuente HTML FormFu

SINOPSIS

Nota: Estos ejemplos hacen uso de html :: formfu :: modelo :: dbic. A partir de HTML::FormFu v02.005, el módulo html :: formfu :: modelo :: dbic no está incluido con HTML::FormFu y está disponible en una distribución independiente.

 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 );
}

Si está utilizando Catalyst, un ejemplo más adecuado podría 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 el "proceso" es llamado automáticamente por el controlador Catalyst; Si realiza alguna modificación al formulario dentro de su método de acción, como agregar o cambiar elementos, agregar restricciones, etc. Debe llamar a "procesar" nuevamente usted mismo antes de usar "Submisted_and_valid", cualquiera de los métodos enumerados en "Valores y errores de formulario enviados" o "modificar un formulario enviado", o representar el formulario.

Aquí hay un ejemplo de un archivo de configuración para crear un formulario de inicio de sesión básico (todos los ejemplos aquí son YAML, pero puede usar cualquier formato admitido por config :: any), también puede crear formularios directamente en su código Perl, en lugar de usar un archivo de configuración 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

DESCRIPCIÓN

HTML :: FormFU es un marco de formulario HTML que tiene como objetivo ser lo más fácil posible para usar para formas web básicas, pero con la potencia y la flexibilidad para hacer cualquier otra cosa que desee hacer (siempre que involucre formularios).

Puede configurar casi cualquier parte del comportamiento y la salida de Formfu. Por defecto, FormFU representa el marcado compatible con "XHTML 1.0 estricto", con la menor cantidad posible de marcado adicional, pero con suficientes nombres de clase CSS para permitir una amplia gama de estilos de salida que se generan cambiando solo el CSS.

Todos los métodos enumerados a continuación (excepto "nuevo") pueden llamarse como un método normal en su objeto $form o como una opción en su archivo de configuración. Los ejemplos se mostrarán principalmente en la sintaxis de configuración YAML.

Esta documentación sigue la convención de que los argumentos de método rodeados de corchetes cuadros [] son opcionales , y se requieren todos los demás argumentos.

Construir un formulario

nuevo

Argumentos: [%Opciones]

Valor de devolución: Forma $

Cree un nuevo objeto HTML :: Formfu.

Cualquier método que pueda llamarse en el objeto HTML :: FormFU puede aprobarse como un argumento a "Nuevo".

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

load_config_file

Argumentos: $ nombre de archivo

Argumentos: @filenames

Valor de devolución: Forma $

Acepta un nombre de archivo o lista de nombres de archivos, cuyos filetipos deben ser de cualquier formato reconocido por config :: any.

El contenido de cada archivo de configuración se pasa a "poblado", por lo que se agrega al formulario.

"Load_config_file" puede llamarse en un archivo de configuración en sí, para permitir que los configuraciones comunes se mantengan en un solo archivo de configuración que puede cargarse por cualquier formulario.

 ---
load_config_file:
  - file1
  - file2

Yaml múltiples documentos dentro de un solo archivo. El marcador de inicio del documento es una línea que contiene 3 guiones. Se aplicarán múltiples documentos en orden, como si se hubieran dado múltiples nombres de archivo.

En el siguiente ejemplo, se aprovechan varios documentos para cargar otro archivo de configuración después de que se agregan los elementos. (Si este fuera un solo documento, el load_config_file se llamaría a elements antes, independientemente de su posición en el archivo).

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

---
load_config_file: ext.yml

Las rutas relativas se resuelven desde el directorio "config_file_path" si se establece, de lo contrario desde el directorio de trabajo actual.

Consulte "Mejores prácticas" para obtener consejos sobre la organización de archivos de configuración.

config_callback

Argumentos: %opciones

Si se define, los argumentos se utilizan para crear un objeto de datos :: Visitor :: Callback durante "Load_config_file" que puede usarse para procesar previamente la configuración antes de que se envíe a "Popular".

Por ejemplo, el siguiente código agrega una devolución de llamada a un formulario que alterará dinámicamente cualquier valor de configuración que termine en ".yml" para terminar en ".yaml" cuando llame "load_config_file":

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

Valor predeterminado: no definido

Este método es un 'accesor heredado' especial, lo que significa que se puede configurar en el formulario, un elemento de bloque o un solo elemento. Cuando se lee el valor, si no se define ningún valor, atraviesa automáticamente la jerarquía de padres del elemento, a través de cualquier elemento de bloque y hasta el formulario, buscando un valor definido.

poblar

Argumentos: %opciones

Valor de devolución: Forma $

Cada clave/valor de opción aprobado puede ser cualquier nombre de método y argumentos HTML :: FORMFU.

Proporciona una forma simple de establecer múltiples valores, o agregar múltiples elementos a un formulario con un solo método.

Intentos de llamar a los nombres del método en un orden semiinteligente (consulte la fuente de población () en HTML::FormFu::ObjectUtil para más detalles).

Valoras de default_

Argumentos: %predeterminados

Valor de devolución: Forma $

Establezca los valores predeterminados de múltiples campo de un solo hash-ref.

Las claves del hash-ref corresponden al nombre de un campo de formulario, y el valor se pasa al método predeterminado del campo.

Esto debe llamarse después de que todos los campos se hayan agregado al formulario, y antes de que se llame al "proceso" (de lo contrario, llame al "proceso" nuevamente antes de representar el formulario).

config_file_path

Argumentos: $ Directory_Name

"config_file_path" define dónde se buscarán los archivos de configuración, si no se da una ruta absoluta a "load_config_file".

Valor predeterminado: no definido

Es un accesor heredador.

indicador

Argumentos: $ field_name

Argumentos: & CodeRef

Si el "indicador" se establece en un nombre de campo, "enviado" devolverá verdadero si se envió un valor para ese nombre de campo.

Si "Indicador" se establece en un código de código, se llamará como una subrutina con los dos argumentos $form y $query , y su valor de devolución se utilizará como el valor de devolución para "enviado".

Si no se establece "indicador", "enviado" devolverá verdadero si se envió un valor para cualquier nombre de campo conocido.

auto_fieldset

Argumentos: 1

Argumentos: %opciones

Valor de devolución: $ Fieldset

Esta configuración es adecuada para la mayoría de las formas básicas, y significa que generalmente puede ignorar la adición de campos usted mismo.

Llamar $form->auto_fieldset(1) inmediatamente agrega un elemento FieldSet al formulario. A partir de entonces, $form->elements() agregará todos los elementos (excepto los campos) a ese campos, en lugar de directamente a la forma.

Para ser específicos, los elementos se agregan al último campos en el formulario, por lo que si agrega otro campos, se agregarán cualquier elemento adicional a ese campos.

Además, puede pasar un hashref a auto_fieldset (), y esto se usará para establecer los valores predeterminados para el primer campos creado.

Algunos ejemplos y su salida, para demostrar:

2 elementos sin campos.

 ---
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 con un "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>

El tercer elemento está dentro de un nuevo 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>

Debido a este comportamiento, si desea campos anidados, deberá agregar cada campos anidados directamente a su padre previsto.

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

$parent->element('fieldset');

form_error_message

Argumentos: $ String

Normalmente, los errores de entrada hacen que se muestre un mensaje de error junto con el campo Formulario apropiado. Si también desea que se muestre un mensaje de error general en la parte superior del formulario, puede establecer el mensaje con "Form_error_message".

Para establecer la clase CSS para el mensaje, consulte "Form_error_message_class".

Para cambiar el marcado utilizado para mostrar el mensaje, edite el archivo de plantilla form_error_message . Ver "Render_method".

Es un accesor de salida.

force_error_message

Si es verdadero, obliga a que se muestre el "form_error_message" incluso si no hay errores de campo.

default_args

Argumentos: %predeterminados

Establezca valores predeterminados que se agregarán a cada elemento, restricción, etc. del tipo dado que posteriormente se agrega al formulario.

Por ejemplo, para hacer que cada elemento Text tenga automáticamente un tamaño de 10 , y haga que cada deflador Strftime se ajuste automáticamente su strftime en %d/%m/%Y :

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

Un ejemplo para hacer que todos los elementos de fecha y hora obtengan automáticamente un deflator Strftime apropiado y un inflador de fecha y hora:

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

Tipos de pseudo

Como caso especial, también puede usar el Block , Field y Input de las teclas elements para que coincidan con cualquier elemento que herede de html :: formfu :: element :: bloque o que does html :: formfu :: rol :: element :: campo o html :: formfu :: rol :: element :: input.

Alternativas

Cada clave elements puede contener una lista any lista utilizando el | divisor: por ejemplo

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

Antepasado

Cada lista de claves elements puede contener un tipo que comienza con + para hacer coincidir solo los elementos con un antepasado del tipo dado: EG

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

No coincidan con el antepasado

Cada lista de claves elements puede contener un tipo que comienza con - coincidir con elementos que no tienen un antepasado del tipo dado: por ejemplo

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

Orden

Los argumentos se aplican en orden menos a más específico: Block , Field , Input , $type . Dentro de cada uno de estos, se aplican argumentos en orden de más corto a más largo.

La clave type debe coincidir con el valor devuelto por type , por ejemplo, "tipo" en html :: formfu :: elemento. Si, por ejemplo, tiene un elemento personalizado fuera del espacio HTML::FormFu::Element::* , que carga a través de $form->element({ type => '+My::Custom::Element' }) , la clave dada a "default_args" no debe incluir el liderazgo + , ya que eso está despojado del valor de type() devuelto (). Ejemplo:

 # 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

Chalecos

"Default_args" genera un solo hashref para pasar a "poblarse", fusionando argumentos para cada tipo a su vez, lo que significa que "población" solo se llama una vez en total, no una vez para cada tipo. Debido a que los valores escalar no se fusionan, esto significa que los valores posteriores anularán los valores anteriores: por ejemplo

 # 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: A diferencia de los métodos adecuados que tienen alias, por ejemplo, "elementos", que es un alias para "elemento", las claves dadas a default_args deben ser de la forma plural, por ejemplo:

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

javascript

Si se establece, el contenido se representará dentro de una etiqueta script , dentro de la parte superior del formulario.

javascript_src

Argumentos: $ URL

Argumentos: @urls

Agrega una etiqueta script para cada URL, inmediatamente antes de cualquier sección "JavaScript".

alijo

Argumentos: [%private_stash]

Valor de devolución: %Stash

Proporciona un hash-Ref en el que puede almacenar cualquier datos que desee asociar con el formulario.

 ---
stash:
  foo: value
  bar: value

elementos

elemento

Argumentos: $ tipo

Argumentos: %opciones

Valor de devolución: $ elemento

Argumentos: @arrayref_of_types_or_options

Valor de retorno: @Elements

Agrega un nuevo elemento al formulario. Consulte "Campos de formulario básico" en html :: formfu :: elemento y "otros elementos centrales" en html :: formfu :: elemento para una lista de elementos centrales.

Si desea cargar un elemento desde un espacio de nombres que no sea HTML::FormFu::Element:: , puede usar un nombre de paquete completamente calificado al prefijo con + .

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

Si no se proporciona un type en las %options , se utilizará el Text predeterminado.

"Elemento" es un alias para "elementos".

defleos

deflador

Argumentos: $ tipo

Argumentos: %opciones

Valor de devolución: $ Deflator

Argumentos: @arrayref_of_types_or_options

Valor de retorno: @deflators

Un deflator puede estar asociado con cualquier campo de formulario y le permite proporcionar $ Field-> predeterminado con un valor que puede ser un objeto.

Si un objeto no se aplica a un valor adecuado para la pantalla, el deflator puede asegurarse de que el campo de formulario reciba un valor de cadena adecuado en su lugar.

Consulte "Deflatadores centrales" en html :: formfu :: deflator para una lista de defladores centrales.

Si no se proporciona un atributo name , se crea un nuevo deflator y se agrega a cada campo en el formulario.

Si desea cargar un deflator en un espacio de nombres que no sea HTML::FormFu::Deflator:: , puede usar un nombre de paquete completamente calificado mediante el prefijo con + .

"Deflator" es un alias para "Defladores".

insert_before

Argumentos: $ new_element, $ EXIT_ELEMENT

Valor de retorno: $ new_element

El primer argumento debe ser el elemento que desea agregar, el segundo argumento debe ser el elemento existente de que el nuevo elemento debe colocarse antes.

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

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

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

En la primera línea del ejemplo anterior, el elemento $new se agrega inicialmente al final del formulario. Sin embargo, el método insert_before reparente el elemento $new , por lo que ya no estará al final del formulario. Debido a esto, si intenta copiar un elemento de un formulario a otro, 'robará' el elemento, en lugar de copiarlo. En este caso, debe 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, $ EXIT_ELEMENT

Valor de retorno: $ new_element

El primer argumento debe ser el elemento que desea agregar, el segundo argumento debe ser el elemento existente en el que se debe colocar el nuevo elemento.

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

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

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

En la primera línea del ejemplo anterior, el elemento $new se agrega inicialmente al final del formulario. Sin embargo, el método insert_after reparenta el elemento $new , por lo que ya no estará al final del formulario. Debido a esto, si intenta copiar un elemento de un formulario a otro, 'robará' el elemento, en lugar de copiarlo. En este caso, debe 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 );

eliminar_ELEMENT

Argumentos: $ elemento

Valor de devolución: $ elemento

Elimina el $element del formulario o la matriz de niños de bloque.

 $form->remove_element( $element );

El elemento huérfano no se puede usar de manera útil para nada hasta que se vuelva a colocar a un formulario o bloque con "Insert_before" o "Insert_After".

Formulario de lógica y validación

HTML :: FormFU proporciona varias etapas para lo que tradicionalmente se describe como validación . Estos son:

Html :: formfu :: filtro
Html :: formfu :: restricción
Html :: formfu :: inflator
Html :: formfu :: validador
Html :: formfu :: transformer

La primera etapa, los filtros, permiten la limpieza de la entrada del usuario, como codificar o eliminar el espacio en blanco liderante/posterior, o eliminar caracteres no dígitos de un número de tarjeta de crédito.

Todas las siguientes etapas permiten un procesamiento más complejo, y cada una de ellas tiene un mecanismo para permitir que se arrojen excepciones, para representar errores de entrada. En cada etapa, todos los campos de formulario deben procesarse sin error para que la siguiente etapa continúe. Si hubo algún error, el formulario debe volver a mostrar al usuario, para permitirles ingresar valores correctos.

Las restricciones están destinadas a la validación de valores de bajo nivel, como "¿Es esto un entero?", "¿Este valor está dentro de los límites?" o "¿Es esta una dirección de correo electrónico válida?".

Los infladores están destinados a permitir que un valor se convierta en un objeto apropiado. El objeto resultante se pasará a los validadores y transformadores posteriores, y también será devuelto por "Params" y "Param".

Los validadores están destinados a una validación de nivel superior, como las restricciones de la base de datos y la base de datos, como "¿Es único este nombre de usuario?". Los validadores solo se ejecutan si todas las restricciones e infladores se han ejecutado sin errores. Se espera que la mayoría de los validadores sean específicos de la aplicación, por lo que cada uno se implementará como una clase separada escrita por el usuario HTML :: FORMFU.

filtros

filtrar

Argumentos: $ tipo

Argumentos: %opciones

Valor de retorno: $ filtro

Argumentos: @arrayref_of_types_or_options

Valor de retorno: @filters

Si proporciona un valor name o names , el filtro se agregará solo a ese campo nombrado. Si no proporciona un valor name o names , el filtro se agregará a todos los campos ya adjuntos al formulario.

Consulte "Filtros principales" en HTML :: Formfu :: Filtro para una lista de filtros principales.

Si desea cargar un filtro en un espacio de nombres que no sea HTML::FormFu::Filter:: , puede usar un nombre de paquete completamente calificado mediante el prefijo con + .

"Filtro" es un alias para "filtros".

restricciones

restricción

Argumentos: $ tipo

Argumentos: %opciones

Valor de devolución: $ restricción

Argumentos: @arrayref_of_types_or_options

Valor de retorno: @Constraints

Consulte "Restricciones básicas" en HTML :: Formfu :: restricción para una lista de restricciones centrales.

Si no se proporciona un atributo name , se crea una nueva restricción y se agrega a cada campo en el formulario.

Si desea cargar una restricción en un espacio de nombres que no sea HTML::FormFu::Constraint:: , puede usar un nombre de paquete totalmente calificado mediante el prefijo con + .

La "restricción" es un alias para "restricciones".

infladores

inflador

Argumentos: $ tipo

Argumentos: %opciones

Valor de devolución: $ inflator

Argumentos: @arrayref_of_types_or_options

Valor de retorno: @Inflators

Consulte "Infladores centrales" en html :: formfu :: inflator para una lista de infladores centrales.

Si no se proporciona un atributo name , se crea un nuevo inflador y se agrega a cada campo en el formulario.

Si desea cargar un inflador en un espacio de nombres que no sea HTML::FormFu::Inflator:: , puede usar un nombre de paquete completamente calificado al prefijo con + .

"Inflator" es un alias para "infladores".

validador

Argumentos: $ tipo

Argumentos: %opciones

Valor de devolución: $ Validador

Argumentos: @arrayref_of_types_or_options

Valor de retorno: @Validators

Consulte "Validadores principales" en HTML :: Formfu :: Validador para una lista de validadores principales.

Si no se proporciona un atributo name , se crea un nuevo validador y se agrega a cada campo en el formulario.

Si desea cargar un validador en un espacio de nombres que no sea HTML::FormFu::Validator:: , puede usar un nombre de paquete completamente calificado mediante el prefijo con + .

"Validador" es un alias para "validadores".

transformadores

transformador

Argumentos: $ tipo

Argumentos: %opciones

Valor de retorno: $ transformer

Argumentos: @arrayref_of_types_or_options

Valor de retorno: @Transformers

Consulte "Transformadores de núcleo" en HTML :: Formfu :: Transformer para una lista de transformadores centrales.

Si no se proporciona un atributo name , se crea un nuevo transformador y se agrega a cada campo en el formulario.

Si desea cargar un transformador en un espacio de nombres que no sea HTML::FormFu::Transformer:: , puede usar un nombre de paquete completamente calificado mediante el prefijo con + .

"Transformer" es un alias para "Transformers".

Cambiar el comportamiento predeterminado

render_proced_value

El comportamiento predeterminado al volver a mostrar un formulario después de un envío es que el campo contiene el valor original sin cambios con el usuario.

Si "render_proced_value" es verdadero, el valor de campo será el resultado final después de todos los filtros, infladores y transformadores se han ejecutado. Los defectos también se ejecutarán con el valor.

Si establece esto en un campo con un inflador, pero sin un deflator equivalente, debe asegurarse de que los infladores vuelvan a un valor utilizable, para no confundir / molestar al usuario.

Valor predeterminado: falso

Es un accesor heredador.

Force_errors

Forzar una restricción a fallar, independientemente de la entrada del usuario.

Si esto se llama en tiempo de ejecución, después de que el formulario ya se haya procesado, debe llamar "proceso" en html :: formfu nuevamente antes de redisir el formulario al usuario.

Valor predeterminado: falso

Este método es un 'accesor heredado' especial, lo que significa que se puede establecer en el formulario, un elemento de bloque, un elemento o una sola restricción. Cuando se lee el valor, si no se define ningún valor, atraviesa automáticamente la jerarquía de padres del elemento, a través de cualquier elemento de bloque y hasta el formulario, buscando un valor definido.

Es un accesor heredador.

params_ignore_underscore

Si es verdadero, causa "parámetros", "parámetro" y "válido" para ignorar cualquier campo cuyo nombre comience con un subrayador _ .

El campo todavía se procesa como de costumbre, y los errores harán que "Submisted_and_Valid" devuelva falso.

Valor predeterminado: falso

Atributos de formulario

Todos los atributos se agregan a la etiqueta de inicio del formulario renderizado.

atributos

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

Es un accesor de atributos.

identificación

Es un atributo atrevido.

acción

Valor predeterminado: ""

Obtenga o establezca la acción asociada con el formulario. El valor predeterminado no es acción, lo que hace que la mayoría de los navegadores se sometan al URI actual.

Es un atributo atrevido.

cisquero

Obtenga o establezca el tipo de codificación del formulario. Los valores válidos son application/x-www-form-urlencoded y multipart/form-data .

Si el formulario contiene un elemento de archivo, el enctype se establece automáticamente en multipart/form-data .

Es un atributo atrevido.

método

Valor predeterminado: "Publicar"

Obtenga o establezca el método utilizado para enviar el formulario. Se puede configurar en "publicar" o "obtener".

Es un atributo atrevido.

título

Obtenga o establezca el atributo de título del formulario.

Es un atributo atrevido.

Clases de CSS

form_error_message_class

Atributo de clase para el mensaje de error que se muestra en la parte superior del formulario.

Consulte "Form_error_message"

LOCALIZACIÓN

lenguas

Argumentos: [ @languages]

Una lista de idiomas que se pasarán al objeto de localización.

Valor predeterminado: ['en']

localize_class

Argumentos: [$ class_name]

ClassName que se utilizará para el objeto de localización predeterminado.

Valor predeterminado: 'html :: formfu :: i18n'

localizar

loc

Argumentos: [$ Key, @argumentos]

Compatible con el método maketext en locale :: maketext.

lugar

Argumentos: $ locales

Actualmente solo usado por html :: formfu :: deflator :: formatNumber and html :: formfu :: filtre :: formatNumber.

Es un accesor heredador.

Procesar un formulario

consulta

Argumentos: [$ query_object]

Argumentos: %params

Proporcione un objeto de consulta compatible con CGI o un hash-Ref de nombres/valores enviados. Alternativamente, el objeto de consulta se puede pasar directamente al objeto "Proceso".

Query_Type

Argumentos: [$ query_type]

Establecer qué módulo se está utilizando para proporcionar la "consulta".

The Catalyst :: Controller :: Html :: Formfu Establece automáticamente esto en Catalyst .

Los valores válidos son CGI , Catalyst y CGI::Simple .

Valor predeterminado: 'CGI'

proceso

Argumentos: [$ query_object]

Argumentos: [%Params]

Procese el objeto de consulta proporcionado o los valores de entrada. Se debe llamar process antes de llamar a cualquiera de los métodos enumerados en "Valores y errores de formulario enviados" y "modificar un formulario enviado".

process también debe llamarse al menos una vez antes de imprimir el formulario o llamar "Render" o "render_data".

Nota para los usuarios de Catalyst :: Controller :: Html :: Formfu: porque el "proceso" es llamado automáticamente por el controlador de catalizador; Si realiza alguna modificación al formulario dentro de su método de acción, como agregar o cambiar elementos, agregar restricciones, etc. Debe llamar a "procesar" nuevamente usted mismo antes de usar "Submisted_and_valid", cualquiera de los métodos enumerados en "Valores y errores de formulario enviados" o "modificar un formulario enviado", o representar el formulario.

Valores y errores de formulario enviados

enviado

Devuelve verdadero si se ha enviado el formulario. Consulte "Indicador" para obtener detalles sobre cómo se calcula esto.

enviado_and_valid

Abreviado para $form->submitted && !$form->has_errors

parámetros

Valor de retorno: %params

Devuelve un hash-Ref de todas las entradas válidas para las cuales no hubo errores.

param_value

Argumentos: $ field_name

Una versión más confiable y recomendada de "Param". Garantizado para devolver siempre un solo valor, independientemente de si se llama en el contexto de la lista o no. Si se enviaron múltiples valores, esto solo devuelve el primer valor. Si el valor no es válido o no se envió el formulario, devuelve undef . Esto lo hace adecuado para su uso en el contexto de la lista, donde se requiere un solo valor.

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

param_array

Argumentos: $ field_name

Garantizado para devolver siempre una matriz-Ref de valores, independientemente del contexto e independientemente de si múltiples valores se enviaron o no. Si el valor no es válido o no se envió el formulario, devuelve una matriz vacía.

param_list

Argumentos: $ field_name

Garantizado para devolver siempre una lista de valores, independientemente del contexto. Si el valor no es válido o no se envió el formulario, devuelve una lista vacía.

parámetro

Argumentos: [$ field_name]

Valor de retorno: $ input_value

Valor de retorno: @valid_names

Ya no se recomienda su uso, ya que su comportamiento es difícil de predecir. Use "param_value", "param_array" o "param_list" en su lugar.

Un método (Readonly) similar al de CGI.

Si se da un nombre de campo, en la lista de contexto devuelve cualquier valor válido enviado para ese campo, y en el contexto escalar solo devuelve el primero de los valores válidos enviados para ese campo.

Si no se ofrece ningún argumento, devuelve una lista de todos los nombres de campo de entrada válidos sin errores.

Pasar más de 1 argumento es un error fatal.

válido

Argumentos: [$ field_name]

Valor de retorno: @valid_names

Valor de devolución: $ bool

Si se da un nombre de campo si se da, devuelve true si ese campo no tenía errores ni false si había errores.

Si no se ofrece ningún argumento, devuelve una lista de todos los nombres de campo de entrada válidos sin errores.

HAS_Errors

Argumentos: [$ field_name]

Valor de retorno: @names

Valor de devolución: $ bool

Si se da un nombre de campo si se da, devuelve true si ese campo tenía errores y false si no había errores.

Si no se ofrece ningún argumento, devuelve una lista de todos los nombres de campo de entrada con errores.

Get_errors

Argumentos: [%Opciones]

Valor de retorno: @errors

Devuelve una matriz-Ref de objetos de excepción de todos los campos en el formulario.

Acepta argumentos de name , type y stage para reducir los resultados devueltos.

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

Get_error

Argumentos: [%Opciones]

Valor de retorno: $ error

Acepta los mismos argumentos que "get_errors", pero solo devuelve el primer error encontrado.

Interacción modelo / base de datos

Consulte HTML :: Formfu :: Modelo para más detalles y modelos disponibles.

default_model

Argumentos: $ model_name

Valor predeterminado: 'DBIC'

modelo

Argumentos: [$ model_name]

Valor de devolución: $ modelo

modelo_config

Argumentos: %config

Modificar un formulario enviado

add_valid

Argumentos: $ nombre, $ valor

Valor de devolución: $ valor

El valor proporcionado reemplaza cualquier valor actual para el campo nombrado. Este valor se devolverá en las llamadas posteriores a "Params" y "Param" y el campo nombrado se incluirá en los cálculos de "Válido".

Clear_errors

Elimina todos los errores de un formulario enviado.

Renderizar un formulario

prestar

Valor de devolución: $ cadena

Debe llamar a "procesar" una vez después de construir el formulario y antes de llamar a "Render".

comenzar

Valor de devolución: $ cadena

Devuelve la etiqueta de inicio de formulario y cualquier salida de "form_error_message" y "javaScript".

fin

Valor de devolución: $ cadena

Devuelve la etiqueta final del formulario.

oculto_fields

Valor de devolución: $ cadena

Devuelve todos los campos de formulario ocultos.

Sistema de complemento

HTML::FormFu proporciona un sistema de complementos que permite que los complementos se agregen fácilmente a un formulario o elemento, para cambiar el comportamiento o salida predeterminada.

Ver html :: formfu :: complemento para más detalles.

Personalización avanzada

Por defecto, FormFU representa el marcado compatible "XHTML 1.0 Strict", con la menor cantidad de marcado adicional posible. Se proporcionan muchos ganchos para agregar nombres de clase CSS generados por programación programáticamente, para permitir que se genere una amplia gama de estilos de salida cambiando solo el CSS.

La personalización básica del marcado es posible a través de los métodos de diseño y multi_layout. Esto le permite reordenar la posición de varias partes de cada campo, como la etiqueta, el comentario, los mensajes de error y la etiqueta de entrada, así como insertar cualquier otra etiqueta arbitraria que desee.

Si esto no es suficiente, puede personalizar completamente el marcado diciéndole a HTML :: Formfu que use un motor de renderizado externo, como TECHA TOOLKIT o plantilla :: ALLOY. Consulte "Render_method" y "TT_Module" para más detalles.

Incluso si establece html :: formfu para usar plantplate :: toolkit para renderizar, los formularios, html :: formfu todavía se puede utilizar junto con cualquier otro sistema de plantilla que prefiera usar para su propio diseño de página, si es html :: template: <TMPL_VAR form> , petal: <form tal:replace="form"></form>  .

A partir de HTML::FormFu v1.00 , TT ya no se enumera un requisito previo requerido, por lo que deberá instalarlo manualmente si desea usar los archivos de plantilla.

render_method

Valor predeterminado: string

Se puede configurar en tt para generar el formulario con archivos de plantilla externos.

Para personalizar el marcado, necesitará una copia de los archivos de plantilla, local en su aplicación. Consulte "Instalación de las plantillas TT" en HTML :: Formfu :: Manual :: Cookbook para más detalles.

Puede personalizar el marcado para un solo elemento configurando "render_method" de ese elemento en tt , mientras que el resto del formulario usa el método de renderizado string predeterminado. Sin embargo, tenga en cuenta que si intenta configurar el formulario o el "render_method" de un bloque a tt , y luego establece el "render_method" de un elemento infantil en string , esa configuración se ignorará, y los elementos infantiles aún usarán el metro de renderizado 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

Es un accesor heredador.

Nombre del archivo

Cambie el nombre de archivo de plantilla utilizado para el formulario.

Valor predeterminado: "Formulario"

tt_args

Argumentos: [%constructor_arguments]

Acepta un hash-Ref de argumentos pasados a "render_method", que se llama internamente por "render".

Dentro de TT_ARGS, las teclas RELATIVE y RECURSION están anuladas para ser siempre verdaderas, ya que estos son un requisito básico para el motor de plantilla.

El directorio del sistema que contiene los archivos de plantilla HTML :: FormFU siempre se agrega al final de INCLUDE_PATH , de modo que se encontrarán los archivos de plantilla de núcleo. Solo necesita establecer esto usted mismo si tiene su propia copia de los archivos de plantilla para fines de personalización.

add_tt_args

Argumentos: [%constructor_arguments]

Asegura que el argumento hash-ref se fusione con cualquier valor de hash-ref hash existente de "tt_args".

tt_module

Valor predeterminado: plantilla

El módulo utilizado cuando "render_method" se establece en tt . Debe proporcionar una interfaz compatible con la plantilla.

render_data

Generalmente llamado implícitamente por "render". Devuelve la estructura de datos que normalmente se pasaría a la string o los métodos de renderizado tt .

Al igual que con "Render", debe llamar al "proceso" una vez después de construir el formulario y antes de llamar "render_data".

render_data_non_recursive

Como "render_data", pero no incluye los datos para ningún elemento infantil.

INTROSPECCIÓN

get_fields

Argumentos: [%Opciones]

Valor de retorno: @elements

Devuelve todos los campos en el formulario (específicamente, todos los elementos que tienen un verdadero "IS_FIELD" en HTML :: Formfu :: Value del elemento).

Acepta argumentos name y type para reducir los resultados devueltos.

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

Acepta también un regexp para buscar resultados.

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

get_field

Argumentos: [%Opciones]

Valor de devolución: $ elemento

Acepta los mismos argumentos que "get_fields", pero solo devuelve el primer campo encontrado.

Get_elements

Argumentos: [%Opciones]

Valor de retorno: @elements

Devuelve todos los elementos de nivel superior en el formulario (no recursivo). Consulte "Get_all_elements" para una versión recursiva.

Acepta argumentos name y type para reducir los resultados devueltos.

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

Acepta también un regexp para buscar resultados.

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

Get_Element

Argumentos: [%Opciones]

Valor de devolución: $ elemento

Acepta los mismos argumentos que "get_elements", pero solo devuelve el primer elemento encontrado.

Consulte "Get_all_element" para obtener una versión recursiva.

get_all_elements

Argumentos: [%Opciones]

Valor de retorno: @elements

Devuelve todos los elementos en el formulario recursivamente.

Opcionalmente acepta argumentos name y type para reducir los resultados devueltos.

 # return all Text elements

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

Acepta también un regexp para buscar resultados.

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

Consulte "Get_elements" para obtener una versión no recursiva.

get_all_element

Argumentos: [%Opciones]

Valor de devolución: $ elemento

Acepta los mismos argumentos que "get_all_elements", pero solo devuelve el primer elemento encontrado.

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

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

Acepta también un regexp para buscar resultados.

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

Consulte "Get_all_elements" para obtener una versión no recursiva.

get_deflators

Argumentos: [%Opciones]

Valor de retorno: @deflators

Devuelve todos los defladores de nivel superior de todos los campos.

Acepta argumentos name y type para reducir los resultados devueltos.

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

get_deflator

Argumentos: [%Opciones]

Valor de devolución: $ elemento

Acepta los mismos argumentos que "get_deflators", pero solo devuelve el primer deflator encontrado.

get_filters

Argumentos: [%Opciones]

Valor de retorno: @filters

Devuelve todos los filtros de nivel superior de todos los campos.

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.

clon

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".

COOKBOOK

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 .