Téléchargement HTML FormFu - Téléchargement du code source HTML FormFu

SYNOPSIS

Remarque: Ces exemples utilisent HTML :: FormFu :: Model :: DBIC. À partir de HTML::FormFu V02.005, le module HTML :: FormFu :: Model :: DBIC n'est pas regroupé avec HTML::FormFu et est disponible dans une distribution autonome.

 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 vous utilisez Catalyst, un exemple plus approprié pourrait être:

 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;

}

Remarque: parce que le "processus" est automatiquement appelé par le contrôleur de catalyseur; Si vous apportez des modifications au formulaire dans votre méthode d'action, comme l'ajout ou la modification des éléments, l'ajout de contraintes, etc.; Vous devez appeler à nouveau "Processus" vous-même avant d'utiliser "Soumisd_and_valid", l'une des méthodes énumérées sous "Valeurs et erreurs de formulaire soumis" ou "Modification d'un formulaire soumis", ou rendant le formulaire.

Voici un exemple de fichier de configuration pour créer un formulaire de connexion de base (tous les exemples ici sont YAML, mais vous pouvez utiliser n'importe quel format pris en charge par config :: any), vous pouvez également créer des formulaires directement dans votre code Perl, plutôt que d'utiliser un fichier de configuration externe.

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

DESCRIPTION

HTML :: FormFu est un cadre de formulaire HTML qui vise à être aussi simple que possible à utiliser pour les formulaires Web de base, mais avec la puissance et la flexibilité pour faire tout ce que vous pourriez vouloir faire (tant qu'elle implique des formulaires).

Vous pouvez configurer presque n'importe quelle partie du comportement et de la sortie de FormFu. Par défaut, FormFU rend le balisage conforme "XHTML 1.0" avec le moins de balisage supplémentaire possible, mais avec des noms de classe CSS suffisants pour permettre une large gamme de styles de sortie à générer en modifiant uniquement le CSS.

Toutes les méthodes énumérées ci-dessous (sauf "Nouveau") peuvent être appelées comme une méthode normale sur votre objet $form , soit comme une option dans votre fichier de configuration. Les exemples seront principalement affichés dans la syntaxe de configuration YAML.

Cette documentation suit la convention selon laquelle les arguments de la méthode entourés de crochets [] sont facultatifs et tous les autres arguments sont requis.

Construire une forme

nouveau

Arguments: [% Options]

Valeur de retour: $ formulaire

Créez un nouvel objet HTML :: FormFu.

Toute méthode qui peut être appelée sur l'objet HTML :: FormFu peut plutôt être transmis comme un argument à "Nouveau".

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

load_config_file

Arguments: $ nom de fichier

Arguments: @FileNames

Valeur de retour: $ formulaire

Accepte un nom de fichier ou une liste de noms de fichiers, dont les filetypes doivent être de n'importe quel format reconnu par config :: tout.

Le contenu de chaque fichier de configuration est passé pour "remplir", et il est donc ajouté au formulaire.

"Load_config_file" peut être appelé dans un fichier de configuration lui-même, afin de permettre à des paramètres communs d'être conservés dans un seul fichier de configuration qui peut être chargé par n'importe quel formulaire.

 ---
load_config_file:
  - file1
  - file2

YAML plusieurs documents dans un seul fichier. Le marqueur de démarrage du document est une ligne contenant 3 tirets. Plusieurs documents seront appliqués dans l'ordre, comme si plusieurs noms de fichiers avaient été donnés.

Dans l'exemple suivant, plusieurs documents sont partis pour charger un autre fichier de configuration après l'ajout des éléments. (S'il s'agissait d'un seul document, le load_config_file serait appelé avant elements , quelle que soit sa position dans le fichier).

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

---
load_config_file: ext.yml

Les chemins relatifs sont résolus à partir du répertoire "config_file_path" s'il est défini, sinon dans le répertoire de travail actuel.

Voir «Meilleures pratiques» pour des conseils sur l'organisation des fichiers de configuration.

config_callback

Arguments: % Options

S'il est défini, les arguments sont utilisés pour créer un objet Data :: Visitor :: Callback pendant "LOAD_CONFIG_FILE" qui peut être utilisé pour prétraiter la configuration avant d'être envoyée à "remplir".

Par exemple, le code ci-dessous ajoute un rappel à un formulaire qui modifiera dynamiquement toute valeur de configuration se terminant par ".yml" pour se terminer par ".yaml" lorsque vous appelez "load_config_file":

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

Valeur par défaut: non définie

Cette méthode est un «accessoire héréditaire» spécial, ce qui signifie qu'il peut être défini sur le formulaire, un élément de bloc ou un seul élément. Lorsque la valeur est lue, si aucune valeur n'est définie, elle traverse automatiquement la hiérarchie des parents de l'élément, via tous les éléments de bloc et jusqu'à la forme, à la recherche d'une valeur définie.

peupler

Arguments: % Options

Valeur de retour: $ formulaire

Chaque clé / valeur d'option réalisée peut être n'importe quel nom et arguments HTML :: FormFu.

Fournit un moyen simple de définir plusieurs valeurs ou d'ajouter plusieurs éléments à un formulaire avec un seul appel de méthode.

Tente d'appeler les noms de méthode dans un ordre semi-intelligent (voir la source de Populate () dans HTML::FormFu::ObjectUtil pour plus de détails).

default_values

Arguments: % par défaut

Valeur de retour: $ formulaire

Définissez les valeurs par défaut du champ multiple à partir d'un seul hash-ref.

Les clés du hash-ref correspondent au nom d'un champ de formulaire et la valeur est transmise à la méthode par défaut du champ.

Cela doit être appelé après que tous les champs ont été ajoutés au formulaire, et avant que le "processus" ne soit appelé (sinon, appelez à nouveau "Process" avant de rendre le formulaire).

config_file_path

Arguments: $ Directory_name

"config_file_path" définit où les fichiers de configuration seront recherchés, si un chemin absolu n'est pas donné à "load_config_file".

Valeur par défaut: non définie

Est un accessoire héritant.

indicateur

Arguments: $ field_name

Arguments: & coderef

Si "Indicateur" est défini sur un nom de champ, "Soumis" reviendra True si une valeur pour ce nom de champ a été soumise.

Si "l'indicateur" est défini sur un code de code, il sera appelé sous-programme avec les deux arguments $form et $query , et sa valeur de retour sera utilisée comme valeur de retour pour "soumis".

Si "indicateur" n'est pas défini, "soumis" reviendra True si une valeur pour un nom de champ connu a été soumise.

Auto_Fieldset

Arguments: 1

Arguments: % Options

Valeur de retour: $ Fieldset

Ce paramètre convient à la plupart des formulaires de base et signifie que vous pouvez généralement ignorer l'ajout de champs vous-même.

Appeler $form->auto_fieldset(1) ajoute immédiatement un élément de champ au formulaire. Par la suite, $form->elements() ajoutera tous les éléments (à l'exception des champs) à ce champ, plutôt que directement au formulaire.

Pour être spécifique, les éléments sont ajoutés au dernier champ du formulaire, donc si vous ajoutez un autre champ, tout autre éléments sera ajouté à ce champ.

En outre, vous pouvez passer un hashref à Auto_FieldSet (), et cela sera utilisé pour définir les défauts pour le premier champ créé.

Quelques exemples et leur sortie, pour démontrer:

2 éléments sans champ.

 ---
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 éléments avec 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>

Le 3ème élément se situe dans un nouveau champ

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

En raison de ce comportement, si vous voulez des ensembles de champs imbriqués, vous devrez ajouter chaque champ imbriqué directement à son parent prévu.

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

$parent->element('fieldset');

form_error_message

Arguments: $ String

Normalement, les erreurs d'entrée entraînent une affichage d'un message d'erreur à côté du champ de formulaire approprié. Si vous souhaitez également afficher un message d'erreur général en haut du formulaire, vous pouvez définir le message avec "form_error_message".

Pour définir la classe CSS pour le message, voir "Form_error_Message_Class".

Pour modifier le balisage utilisé pour afficher le message, modifiez le fichier de modèle form_error_message . Voir "render_method".

Est un accessoire de sortie.

force_error_message

Si c'est vrai, le "form_error_message" est affiché même s'il n'y a pas d'erreurs de champ.

default_args

Arguments: % par défaut

Définissez les défauts qui seront ajoutés à chaque élément, contrainte, etc. du type donné qui est ensuite ajouté au formulaire.

Par exemple, pour que chaque élément Text ait automatiquement une taille de 10 et que chaque déflateur Strftime obtienne automatiquement son strime réglé sur %d/%m/%Y :

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

Un exemple pour faire de tous les éléments DateTime obtient automatiquement un déflateur approprié de STRFTIME et un inflateur DateTime:

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

Pseudo-types

En tant que cas particulier, vous pouvez également utiliser le Block , Field et Input touches elements pour correspondre à tout élément qui hérite de HTML :: FormFu :: Element :: Block ou qui does HTML :: FormFu :: Role :: Element :: Field ou Html :: FormFu :: Role :: Element :: Entrée.

Alternatives

Chaque clé elements peut contenir une liste any utilisant le | Diviseur: par exemple

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

Associer l'ancêtre

Chaque liste de clés elements peut contenir un type commençant par + pour faire correspondre les éléments avec un ancêtre du type donné: par exemple

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

Ne correspondez pas à l'ancêtre

Chaque liste de clés elements peut contenir un type commençant par - pour ne correspondre que des éléments qui n'ont pas d'ancêtre du type donné: par exemple

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

Commande

Les arguments sont appliqués dans le moins au plus spécifique: Block , Field , Input , $type . Dans chacun de ceux-ci, des arguments sont appliqués par ordre le plus court au plus long.

La touche type doit correspondre à la valeur renvoyée par type , par exemple "type" dans l'élément html :: formfu ::. Si, par exemple, vous avez un élément personnalisé à l'extérieur de l'espace de HTML::FormFu::Element::* que vous chargez via $form->element({ type => '+My::Custom::Element' }) , la clé donnée à "Default_args" ne devrait pas inclure le leader + , car cela est éliminé de la valeur retournée type() . Exemple:

 # 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

Affrontements

"Default_args" génère un seul hashref pour passer à "peupler", la fusion des arguments pour chaque type à son tour - ce qui signifie que "peupler" n'est appelé qu'une seule fois au total - pas une fois pour chaque type. Parce que les valeurs scalaires ne sont pas fusionnées - cela signifie que les valeurs ultérieures remplaceront les valeurs antérieures: par exemple

 # 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

Rigueur

Remarque: Contrairement aux méthodes appropriées qui ont des alias, par exemple "éléments" qui est un alias pour "élément" - les clés données à default_args doivent être de la forme plurielle, par exemple:

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

javascrip

S'il est défini, le contenu sera rendu dans une balise script , en haut du formulaire.

javascript_src

Arguments: $ url

Arguments: @urls

Ajoute une balise script pour chaque URL, immédiatement avant toute section "JavaScript".

planque

Arguments: [% private_stash]

Valeur de retour: % cachette

Fournit un hash-ref dans lequel vous pouvez stocker toutes les données que vous voudrez peut-être associer au formulaire.

 ---
stash:
  foo: value
  bar: value

éléments

élément

Arguments: $ Type

Arguments: % Options

Valeur de retour: $ élément

Arguments: @arrayref_of_types_or_options

Valeur de retour: @Elements

Ajoute un nouvel élément au formulaire. Voir "Core Form Fields" dans HTML :: FormFu :: Element et "Autres éléments principaux" dans HTML :: FormFu :: élément pour une liste d'éléments principaux.

Si vous souhaitez charger un élément d'un espace de noms autres que HTML::FormFu::Element:: , vous pouvez utiliser un nom de package entièrement qualifié en le préfixant avec + .

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

Si un type n'est pas fourni dans les %options , le Text par défaut sera utilisé.

"Element" est un alias pour "éléments".

déflateurs

déflateur

Arguments: $ Type

Arguments: % Options

Valeur de retour: $ Deflateur

Arguments: @arrayref_of_types_or_options

Valeur de retour: @deflators

Un déflateur peut être associé à n'importe quel champ de formulaire et vous permet de fournir un champ $-> par défaut avec une valeur qui peut être un objet.

Si un objet ne chaîne pas à une valeur appropriée pour l'affichage, le défteur peut s'assurer que le champ de formulaire reçoit plutôt une valeur de chaîne appropriée.

Voir "Deflateurs de base" dans HTML :: FormFu :: Deflateur pour une liste de déflateurs de base.

Si un attribut name n'est pas fourni, un nouveau déflateur est créé et ajouté à tous les champs du formulaire.

Si vous souhaitez charger un déflateur dans un espace de noms autres que HTML::FormFu::Deflator:: , vous pouvez utiliser un nom de package entièrement qualifié en le préfixant avec + .

"Deflateur" est un alias pour les "déflateurs".

insert_before

Arguments: $ new_element, $ existant_element

Valeur de retour: $ new_element

Le 1er argument doit être l'élément que vous souhaitez ajouter, le 2ème argument doit être l'élément existant que le nouvel élément doit être placé avant.

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

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

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

Dans la première ligne de l'exemple ci-dessus, l'élément $new est initialement ajouté à la fin du formulaire. Cependant, la méthode insert_before reparent l'élément $new , il ne sera donc plus à la fin du formulaire. Pour cette raison, si vous essayez de copier un élément d'un formulaire à un autre, il «volera» l'élément, au lieu de le copier. Dans ce cas, vous devez utiliser 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

Arguments: $ new_element, $ existant_element

Valeur de retour: $ new_element

Le 1er argument doit être l'élément que vous souhaitez ajouter, le 2ème argument doit être l'élément existant dont le nouvel élément doit être placé.

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

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

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

Dans la première ligne de l'exemple ci-dessus, l'élément $new est initialement ajouté à la fin du formulaire. Cependant, la méthode insert_after reparent l'élément $new , il ne sera donc plus à la fin du formulaire. Pour cette raison, si vous essayez de copier un élément d'un formulaire à un autre, il «volera» l'élément, au lieu de le copier. Dans ce cas, vous devez utiliser 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 );

retirer_element

Arguments: $ élément

Valeur de retour: $ élément

Supprime l' $element de la gamme d'enfants du formulaire ou du bloc.

 $form->remove_element( $element );

L'élément orphelin ne peut pas être utilisé utilement pour quoi que ce soit tant qu'il n'est pas attaché à un formulaire ou à un bloc avec "insert_before" ou "insert_after".

Formulaire logique et validation

HTML :: FormFu fournit plusieurs étapes pour ce qui est traditionnellement décrit comme une validation . Ce sont:

Html :: formfu :: filtre
HTML :: FORMFU :: CONTRAINTION
HTML :: FORMFU :: Inflateur
HTML :: FORMFU :: VALIDATEUR
Html :: Formfu :: Transformateur

Est un accessoire héritant.

Force_errors

Forcer une contrainte à échouer, quelle que soit la saisie de l'utilisateur.

Si cela est appelé lors de l'exécution, une fois que le formulaire a déjà été traité, vous devez à nouveau appeler "Process" dans HTML :: FormFu avant de rediger le formulaire à l'utilisateur.

Valeur par défaut: false

Cette méthode est un «accessoire héréditaire» spécial, ce qui signifie qu'il peut être défini sur le formulaire, un élément de bloc, un élément ou une seule contrainte. Lorsque la valeur est lue, si aucune valeur n'est définie, elle traverse automatiquement la hiérarchie des parents de l'élément, via tous les éléments de bloc et jusqu'à la forme, à la recherche d'une valeur définie.

Est un accessoire héritant.

params_ignore_underscore

Si c'est vrai, provoque des "paramètres", "param" et "valides" pour ignorer tous les champs dont le nom commence par un soulignement _ .

Le champ est toujours traité comme d'habitude, et les erreurs provoqueront "Soumisd_and_valid" pour retourner false.

Valeur par défaut: false

Attributs de formulaire

Tous les attributs sont ajoutés à la balise de démarrage du formulaire rendu.

attributs

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

Obtenez ou définissez l'attribut de titre du formulaire.

Est un attribut raccourci.

Cours CSS

form_error_message_class

Attribut de classe pour le message d'erreur affiché en haut du formulaire.

Voir "form_error_message"

LOCALISATION

langues

Arguments: [ @Languages]

Une liste de langues qui seront transmises à l'objet de localisation.

Valeur par défaut: [«en»]

localiser_class

Arguments: [$ class_name]

ClassName à utiliser pour l'objet de localisation par défaut.

Valeur par défaut: 'html :: formfu :: i18n'

localiser

Arguments: [$ key, @arguments]

Compatible avec la méthode maketext dans les paramètres régionaux :: maketext.

lieu

Arguments: $

Actuellement uniquement utilisé par HTML :: FormFu :: Deflateur :: FormatNumber et HTML :: FormFu :: Filter :: FormatNumber.

Est un accessoire héritant.

Traitement d'un formulaire

requête

Arguments: [$ query_object]

Arguments: % params

Fournissez un objet de requête compatible CGI ou un hash-ref de nom / valeurs soumis. Alternativement, l'objet de requête peut être transmis directement à l'objet "Process".

query_type

Arguments: [$ query_type]

Définissez quel module est utilisé pour fournir la "requête".

The Catalyst :: Controller :: Html :: FormFu le définit automatiquement sur Catalyst .

Les valeurs valides sont CGI , Catalyst et CGI::Simple .

Valeur par défaut: «CGI»

processus

Arguments: [$ query_object]

Arguments: [% params]

Traiter l'objet de requête fourni ou les valeurs d'entrée. process doit être appelé avant d'appeler l'une des méthodes énumérées sous «Valeurs et erreurs de formulaire soumises» et «Modification d'un formulaire soumis».

process doit également être appelé au moins une fois avant d'imprimer le formulaire ou d'appeler "rendu" ou "render_data".

Remarque aux utilisateurs de Catalyst :: Controller :: html :: FormFu: parce que "Process" est automatiquement appelé pour vous par le contrôleur Catalyst; Si vous apportez des modifications au formulaire dans votre méthode d'action, comme l'ajout ou la modification des éléments, l'ajout de contraintes, etc.; Vous devez appeler à nouveau "Processus" vous-même avant d'utiliser "Soumisd_and_valid", l'une des méthodes énumérées sous "Valeurs et erreurs de formulaire soumis" ou "Modification d'un formulaire soumis", ou rendant le formulaire.

Valeurs et erreurs de formulaire soumis

soumis

Renvoie True si le formulaire a été soumis. Voir "Indicateur" pour plus de détails sur la façon dont cela est calculé.

soumis_and_valid

SHORTMAND POUR $form->submitted && !$form->has_errors

paramètres

Valeur de retour: % params

Renvoie un hash-ref de toutes les entrées valides pour lesquelles il n'y avait pas d'erreurs.

param_value

Arguments: $ field_name

Une version plus fiable et recommandée de "param". Garanti pour toujours renvoyer une seule valeur, qu'elle soit appelée ou non dans le contexte de la liste. Si plusieurs valeurs étaient soumises, cela ne renvoie que la première valeur. Si la valeur n'est pas valide ou si le formulaire n'a pas été soumis, il renvoie undef . Cela le rend adapté à une utilisation dans le contexte de la liste, où une seule valeur est requise.

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

param_array

Arguments: $ field_name

Garanti pour toujours renvoyer un tableau de valeurs, quel que soit le contexte et que les valeurs multiples aient été soumises ou non. Si la valeur n'est pas valide ou si le formulaire n'a pas été soumis, il renvoie un tableau vide.

param_list

Arguments: $ field_name

Garanti pour toujours renvoyer une liste de valeurs, quel que soit le contexte. Si la valeur n'est pas valide ou si le formulaire n'a pas été soumis, il renvoie une liste vide.

paramot

Arguments: [$ field_name]

Valeur de retour: $ input_value

Valeur de retour: @valid_name

Il n'est plus recommandé pour une utilisation, car son comportement est difficile à prévoir. Utilisez "param_value", "param_array" ou "param_list".

Une méthode (Readonly) similaire à celle des CGI.

Si un nom de champ est donné, dans List-Context renvoie toutes les valeurs valides soumises pour ce champ, et dans Scalar-Context ne renvoie que la première des valeurs valides soumises pour ce champ.

Si aucun argument n'est donné, renvoie une liste de tous les noms de champ de saisie valides sans erreurs.

Passer plus d'un argument est une erreur fatale.

valide

Arguments: [$ field_name]

Valeur de retour: @valid_name

Valeur de retour: $ bool

Si un nom de champ s'il est donné, renvoie true si ce champ n'avait pas d'erreurs et false s'il y avait des erreurs.

Si aucun argument n'est donné, renvoie une liste de tous les noms de champ de saisie valides sans erreurs.

Has_errors

Arguments: [$ field_name]

Valeur de retour: @Names

Valeur de retour: $ bool

Si un nom de champ s'il est donné, renvoie true si ce champ avait des erreurs et false s'il n'y avait pas d'erreurs.

Si aucun argument n'est donné, renvoie une liste de tous les noms de champ de saisie avec des erreurs.

get_errors

Arguments: [% Options]

Valeur de retour: @Errors

Renvoie un tableau des objets d'exception de tous les champs de la forme.

Accepte les arguments name , type et stage pour affiner les résultats retournés.

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

get_error

Arguments: [% Options]

Valeur de retour: $ Erreur

Accepte les mêmes arguments que "get_errors", mais renvoie uniquement la première erreur trouvée.

Interaction modèle / base de données

Voir HTML :: FormFu :: Modèle pour plus de détails et des modèles disponibles.

default_model

Arguments: $ model_name

Valeur par défaut: «dbic»

modèle

Arguments: [$ model_name]

Valeur de retour: $ modèle

modèle_config

Arguments: % config

Modification d'un formulaire soumis

add_valid

Arguments: $ Name, $ valeur

HTML::FormFu fournit un système de plugin qui permet à des plugins d'être facilement ajoutés à un formulaire ou à un élément, pour modifier le comportement ou la sortie par défaut.

Voir HTML :: FormFu :: Plugin pour plus de détails.

Personnalisation avancée

Par défaut, FormFu rend le balisage conforme strict "XHTML 1.0" avec le moins de balisage supplémentaire possible. De nombreux crochets sont fournis pour ajouter des noms de classe CSS générés par programme, afin de permettre une large gamme de styles de sortie à générer en modifiant uniquement le CSS.

La personnalisation de base du balisage est possible via les méthodes de mise en page et multi_layout. Cela vous permet de réorganiser la position de différentes parties de chaque champ - comme l'étiquette, le commentaire, les messages d'erreur et la balise d'entrée - ainsi que l'insertion de toute autre balise arbitraire que vous pouvez souhaiter.

Si cela n'est pas suffisant, vous pouvez faire entièrement personnaliser le balisage en disant à HTML :: FormFu pour utiliser un moteur de rendu externe, tel que Tablate Toolkit ou modèle :: ALLIAG. Voir "render_method" et "tt_module" pour plus de détails.

Même si vous définissez HTML :: FormFu à utiliser Template :: Toolkit sur rendu, les formulaires, HTML :: FormFu peuvent toujours être utilisés en conjonction avec le autre système de modèles que vous préférez utiliser pour votre propre page de page, que ce soit HTML :: Template: <TMPL_VAR form> , Petal: <form tal:replace="form"></form>  .

À partir de HTML::FormFu v1.00 , TT n'est plus répertorié une condition préalable requise - vous devrez donc l'installer manuellement si vous souhaitez utiliser les fichiers de modèle.

rendu_method

Valeur par défaut: string

Peut être défini sur tt pour générer le formulaire avec des fichiers de modèle externe.

Pour personnaliser le balisage, vous aurez besoin d'une copie des fichiers de modèle, local dans votre application. Voir "Installation des modèles TT" dans HTML :: FormFu :: Manual :: Cookbook pour plus de détails.

Vous pouvez personnaliser le balisage pour un seul élément en définissant "render_method" de tt élément, tandis que le reste du formulaire utilise la méthode de rendu string par défaut. Notez cependant que si vous essayez de définir le formulaire ou "Render_Method" d'un bloc sur tt , puis définir "Render_method" d'un élément enfant sur string , ce paramètre sera ignoré et les éléments enfants utiliseront toujours la méthode de rendu 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

Est un accessoire héritant.

nom de fichier

Modifiez le nom de fichier de modèle utilisé pour le formulaire.

Valeur par défaut: "Form"

tt_args

Arguments: [% Constructor_arguments]

Accepte un hash-ref d'arguments transmis à "render_method", qui est appelé en interne par "rendu".

Dans TT_ARGS, les clés RELATIVE et RECURSION sont remplacées pour toujours être vraies, car ce sont une exigence de base pour le moteur de modèle.

Le répertoire système contenant des fichiers de modèle HTML :: FormFu est toujours ajouté à la fin de INCLUDE_PATH , afin que les fichiers de modèle de base soient trouvés. Vous n'avez besoin de le définir vous-même que si vous avez votre propre copie des fichiers de modèle à des fins de personnalisation.

add_tt_args

Arguments: [% Constructor_arguments]

S'assure que l'argument de hash-ref est fusionné avec toute valeur de hash-ref existante de "tt_args".

tt_module

Valeur par défaut: modèle

Le module utilisé lorsque "Render_Method" est défini sur tt . Devrait fournir une interface compatible avec le modèle.

rendu_data

Généralement appelé implicitement par «rendu». Renvoie la structure de données qui serait normalement transmise sur la string ou les méthodes de rendu tt .

Comme pour "rendu", vous devez appeler "Processus" une fois après avoir construit le formulaire, et avant d'appeler "render_data".

render_data_non_recursive

Comme "render_data", mais n'inclut pas les données pour les éléments enfants.

INTROSPECTION

get_fields

Arguments: [% Options]

Valeur de retour: @Elements

Renvoie tous les champs sous la forme (en particulier, tous les éléments qui ont un vrai "is_field" dans html :: formfu :: Valeur d'élément).

Accepte les arguments name et type pour réduire les résultats retournés.

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

Accepte également un regexp pour rechercher des résultats.

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

get_field

Arguments: [% Options]

Valeur de retour: $ élément

Accepte les mêmes arguments que "get_fields", mais renvoie uniquement le premier champ trouvé.

get_elements

Arguments: [% Options]

Valeur de retour: @Elements

Renvoie tous les éléments de niveau supérieur sous la forme (pas récursif). Voir "get_all_elements" pour une version récursive.

Accepte les arguments name et type pour réduire les résultats retournés.

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

Accepte également un regexp pour rechercher des résultats.

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

get_element

Arguments: [% Options]

Valeur de retour: $ élément

Accepte les mêmes arguments que "get_elements", mais renvoie uniquement le premier élément trouvé.

Voir "get_all_element" pour une version récursive.

get_all_elements

Arguments: [% Options]

Valeur de retour: @Elements

Renvoie tous les éléments de la forme récursivement.

Accepte éventuellement les arguments name et type pour affiner les résultats retournés.

 # return all Text elements

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

Accepte également un regexp pour rechercher des résultats.

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

Voir "Get_Elements" pour une version non rérécise.

get_all_element

Arguments: [% Options]

Valeur de retour: $ élément

Accepte les mêmes arguments que "get_all_elements", mais renvoie uniquement le premier élément trouvé.

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

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

Accepte également un regexp pour rechercher des résultats.

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

Voir "get_all_elements" pour une version non réécursive.

get_deflators

Arguments: [% Options]

Valeur de retour: @deflators

Renvoie tous les déflateurs de niveau supérieur de tous les champs.

Accepte les arguments name et type pour réduire les résultats retournés.

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

get_deflator

Arguments: [% Options]

Valeur de retour: $ élément

Accepte les mêmes arguments que "get_deflators", mais renvoie uniquement le premier déflateur trouvé.

get_filters

Arguments: [% Options]

Valeur de retour: @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.

cloner

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

LIVRE DE CUISINE

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 .