HTML FormFu Download - HTML FormFu Quellcode herunterladen

ZUSAMMENFASSUNG

Hinweis: Diese Beispiele verwenden HTML :: Formfu :: model :: dbic. Ab HTML::FormFu V02.005 ist das HTML :: Formfu :: Model :: DBIC-Modul nicht mit HTML::FormFu gebündelt und ist in einer eigenständigen Verteilung erhältlich.

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

Wenn Sie den Katalysator verwenden, kann ein geeigneteres Beispiel sein:

 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;

}

Hinweis: Weil "Prozess" vom Catalysator -Controller automatisch aufgerufen wird; Wenn Sie Änderungen des Formulars innerhalb Ihrer Aktionsmethode vornehmen, z. B. das Hinzufügen oder Ändern von Elementen, Hinzufügen von Einschränkungen usw.; Sie müssen "Process" erneut selbst aufrufen, bevor Sie "ordnungsgemäß_and_valid", eine der unter "übermittelten Formularwerte und -fehler und Fehler" aufgeführten Methoden oder "Änderung eines übermittelten Formulars" oder das Rendern des Formulars.

Hier ist ein Beispiel für eine Konfigurationsdatei zum Erstellen eines grundlegenden Anmeldeformulars (alle Beispiele hier sind YAML. Sie können jedoch jedes von config :: beliebige Format verwenden). Sie können auch Formulare direkt in Ihrem Perl -Code erstellen, anstatt eine externe Konfigurationsdatei zu verwenden.

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

BESCHREIBUNG

HTML :: Formfu ist ein HTML -Formular -Framework, das so einfach wie möglich für grundlegende Webformulare zu verwenden ist, aber mit der Leistung und Flexibilität, was Sie möglicherweise tun möchten (solange es sich um Formulare handelt).

Sie können fast jeden Teil des Verhaltens und der Ausgabe von Formfu konfigurieren. Standardmäßig rendert Formfu "XHTML 1.0 Strict" -Kennzeichen mit so wenig zusätzlichem Markup wie möglich, jedoch mit ausreichenden CSS-Klassennamen, um eine breite Reichweite von Ausgangsstilen zu ermöglichen, indem nur die CSS geändert werden.

Alle unten aufgeführten Methoden (außer "neu") können entweder als normale Methode in Ihrem $form -Objekt oder als Option in Ihrer Konfigurationsdatei aufgerufen werden. Beispiele werden hauptsächlich in der YAML -Konfigurationssyntax angezeigt.

Diese Dokumentation folgt der Konvention, dass Methodenargumente, die von quadratischen Klammern umgeben sind [] , optional und alle anderen Argumente erforderlich sind.

Ein Formular erstellen

neu

Argumente: [%Optionen]

Rückgabewert: $ Form

Erstellen Sie ein neues HTML :: Formfu -Objekt.

Jede Methode, die auf das HTML :: Formfu -Objekt aufgerufen werden kann, kann stattdessen als Argument an "neu" übergeben werden.

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

load_config_file

Argumente: $ Dateiname

Argumente: @FileNames

Rückgabewert: $ Form

Akzeptieren Sie einen Dateinamen oder eine Liste von Dateinamen, deren Filetypen ein beliebiges Format haben sollten, das von config :: angewendet wird.

Der Inhalt jeder Konfigurationsdatei wird an "Populate" übergeben und dem Formular hinzugefügt.

"load_config_file" kann in einer Konfigurationsdatei selbst aufgerufen werden, damit die allgemeinen Einstellungen in einer einzelnen Konfigurationsdatei aufbewahrt werden können, die möglicherweise nach einem beliebigen Formular geladen werden kann.

 ---
load_config_file:
  - file1
  - file2

YAML Mehrere Dokumente in einer einzelnen Datei. Der Dokumentstartmarker ist eine Zeile mit 3 Strichen. Es werden mehrere Dokumente in der Reihenfolge angewendet, so wie es mehrere Dateinamen angegeben worden wären.

Im folgenden Beispiel werden mehrere Dokumente ausgenutzt, um eine andere Konfigurationsdatei nach hinzugefügten Elementen zu laden. (Wenn dies ein einzelnes Dokument wäre, würde die load_config_file vor elements aufgerufen, unabhängig von ihrer Position in der Datei).

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

---
load_config_file: ext.yml

Relative Pfade werden aus dem Verzeichnis "config_file_path" aufgelöst, wenn es festgelegt ist, ansonsten aus dem aktuellen Arbeitsverzeichnis.

"Best Practices" finden Sie unter Beratung zum Organisieren von Konfigurationsdateien.

config_callback

Argumente: %Optionen

Wenn Sie definiert sind, werden die Argumente verwendet, um ein Daten zu erstellen :: Visitor :: Callback-Objekt während "load_config_file", mit der möglicherweise die Konfiguration vorbereitet wird, bevor sie an "Populate" gesendet wird.

Der folgende Code fügt beispielsweise einem Formular einen Rückruf hinzu, der jeden Konfigurationswert dynamisch ändert, der in ".yml" in ".yaml" endet, wenn Sie "load_config_file" aufrufen:

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

Standardwert: Nicht definiert

Diese Methode ist ein spezieller "ererbter Accessor", was bedeutet, dass sie auf das Formular, ein Blockelement oder ein einzelnes Element eingestellt werden kann. Wenn der Wert gelesen wird, durchquert er automatisch die Hierarchie des Elements durch Blockelemente und bis zum Formular, um nach einem definierten Wert zu suchen.

bevölkern

Argumente: %Optionen

Rückgabewert: $ Form

Jeder Optionsschlüssel/jeder übergebene Wert kann ein beliebiges HTML :: Formfu-Methodenname und Argumente sein.

Bietet eine einfache Möglichkeit, mehrere Werte festzulegen oder mehrere Elemente zu einem Formular mit einem einzelnen Methodenanruf hinzuzufügen.

Versuche, die Methodennamen in einer halb-intelligenten Reihenfolge aufzurufen (siehe Quelle von Populate () in HTML::FormFu::ObjectUtil für Einzelheiten).

default_values

Argumente: %Standard

Rückgabewert: $ Form

Stellen Sie die Standardwerte mehrerer Felds von einem einzelnen Hash-Ref ein.

Die Schlüssel des Hash-Ref entsprechen dem Namen eines Formularfelds, und der Wert wird an die Standardmethode des Feldes übergeben.

Dies sollte aufgerufen werden, nachdem alle Felder dem Formular hinzugefügt wurden, und bevor "Prozess" aufgerufen wurde (ansonsten "Prozess" erneut aufrufen, bevor das Formular rendert).

config_file_path

Argumente: $ DIRECTORY_NAME

"config_file_path" definiert, wo nach Konfigurationsdateien gesucht werden, ob ein absoluter Pfad nicht "lade_config_file" angegeben wird.

Standardwert: Nicht definiert

Ist ein Erbe -Acterning.

Indikator

Argumente: $ field_name

Argumente: & coderef

Wenn "Indikator" auf einen Feldnamen festgelegt wird ", wird" eingereicht "true zurückgegeben, wenn ein Wert für diesen Feldnamen eingereicht wurde.

Wenn "Indikator" auf einen Code-Ref eingestellt ist, wird er als Unterprogramm mit den beiden Argumenten $form und $query bezeichnet, und sein Rückgabewert wird als Rückgabewert für "übermittelt" verwendet.

Wenn "Indikator" nicht festgelegt ist, wird "eingereicht" true zurückgegeben, wenn ein Wert für einen bekannten Feldnamen eingereicht wurde.

auto_fieldset

Argumente: 1

Argumente: %Optionen

Rückgabewert: $ fieldset

Diese Einstellung ist für die meisten grundlegenden Formulare geeignet und bedeutet, dass Sie selbst das Hinzufügen von Feldern selbst ignorieren können.

Das Aufrufen von $form->auto_fieldset(1) fügt dem Formular sofort ein Fieldset-Element hinzu. Danach fügt $form->elements() alle Elemente (außer Feldersets) zu diesem Felderset und nicht direkt zum Formular hinzu.

Um spezifisch zu sein, werden die Elemente dem letzten Felderset auf dem Formular hinzugefügt. Wenn Sie also ein weiteres Feldset hinzufügen, werden diesem Felderset weitere Elemente hinzugefügt.

Außerdem können Sie einen Hashref an auto_fieldset () übergeben, und dies wird verwendet, um Standardeinstellungen für das erste erstellte Fieldset festzulegen.

Ein paar Beispiele und ihre Ausgabe, um zu demonstrieren:

2 Elemente ohne Fieldset.

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

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

2 Elemente mit einem "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>

Das 3. Element befindet sich in einem neuen 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>

Aufgrund dieses Verhaltens müssen Sie, wenn Sie verschachtelte Fieldsets möchten, jedes verschachtelte Felderset direkt zu seinem beabsichtigten Elternteil hinzufügen.

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

$parent->element('fieldset');

Form_Error_message

Argumente: $ String

Normalerweise werden Eingabefehler zusammen mit dem entsprechenden Formularfeld angezeigt. Wenn Sie auch eine allgemeine Fehlermeldung finden möchten, die oben im Formular angezeigt werden soll, können Sie die Nachricht mit "Form_Error_Message" festlegen.

Um die CSS -Klasse für die Nachricht festzulegen, siehe "Form_error_message_class".

Um das Markup zu ändern, mit dem die Nachricht angezeigt wird, bearbeiten Sie die Vorlagendatei form_error_message . Siehe "Render_Method".

Ist ein Ausgabempfänger.

Force_Error_Message

Wenn wahr, erzwingt die Anzeige der "Form_Error_Message", auch wenn keine Feldfehler vorliegen.

default_args

Argumente: %Standard

Stellen Sie Standardeinstellungen fest, die zu jedem Element, jeder Einschränkung usw. des angegebenen Typs hinzugefügt werden, der anschließend dem Formular hinzugefügt wird.

Zum Beispiel, damit jedes Text automatisch eine Größe von 10 hat und jeden Strftime Deflator automatisch auf %d/%m/%Y eingestellt wird:

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

Ein Beispiel, um alle DateTime -Elemente automatisch einen geeigneten Straftime Deflator und einen DateTime -Inflator zu erhalten:

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

Pseudo -Typen

Als Sonderfall können Sie auch den elements Block , Field und Input verwenden, um zu jedem Element übereinzustimmen, das von html :: formfu :: element :: block does oder das html :: formfu :: rollen :: element :: field oder html :: formfu :: rolle :: element :: Eingabe.

Alternativen

Jeder elements -Schlüssel kann eine any Liste mit dem | enthalten Teiler: z

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

Match Vorfahr

Jede Schlüsselliste elements kann einen Typ enthalten, der mit + beginnt, um nur Elemente mit einem Vorfahren des angegebenen Typs zu übereinstimmen: z.

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

Passen Sie nicht mit Vorfahren zusammen

Jede Schlüsselliste elements kann einen Typ enthalten, der mit - nur Elemente übereinstimmen, die keinen Vorfahr des angegebenen Typs haben: z.

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

Befehl

Die Argumente werden im geringsten auf die spezifischste Reihenfolge angewendet: Block , Field , Input , $type . Innerhalb von diesen werden Argumente in der Reihenfolge der kürzesten bis zum längsten längeren Reihenfolge angewendet.

Die type muss mit dem nach type zurückgegebenen Wert übereinstimmen, z. B. "Typ" in html :: formfu :: element. Wenn Sie beispielsweise ein benutzerdefiniertes Element außerhalb des HTML::FormFu::Element::* Namespace haben, den Sie über $form->element({ type => '+My::Custom::Element' }) , sollte der Schlüssel, der "default_args" angegeben ist, nicht enthalten, da das Leading + das ausgestattete type() Wert () Wert () Wert () Wert () Value () Value () Value. Beispiel:

 # 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

Zusammenstöße

"default_args" generiert einen einzelnen Hashref, um an "Populate" zu gelangen und Argumente für jeden Typ wiederum zu verschmelzen - was bedeutet, dass "Populate" nur einmal in der Gesamtfläche bezeichnet wird - nicht einmal für jeden Typ. Da Skalarwerte nicht zusammengeführt werden - dies bedeutet, dass spätere Werte frühere Werte überschreiben: z.

 # 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

Strenge

HINWEIS: Im Gegensatz zu den richtigen Methoden mit Aliase, zum Beispiel "Elemente", die ein Alias für "Element" sind, müssen die Tasten, die an default_args angegeben sind, von der Pluralform, z. B.

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

JavaScript

Wenn festgelegt wird, wird der Inhalt innerhalb eines script -Tags in der Oberseite des Formulars gerendert.

JavaScript_Src

Argumente: $ url

Argumente: @urls

Fügt ein script -Tag für jede URL unmittelbar vor einem Abschnitt "JavaScript" hinzu.

Versteck

Argumente: [%privat_stash]

Rückgabewert: %Stash

Bietet einen Hash-Ref, in dem Sie alle Daten speichern können, die Sie möglicherweise mit dem Formular assoziieren möchten.

 ---
stash:
  foo: value
  bar: value

Elemente

Element

Argumente: $ type

Argumente: %Optionen

Rückgabewert: $ Element

Argumente: @arrayref_of_types_or_options

Rückgabewert: @Elements

Fügt dem Formular ein neues Element hinzu. Weitere Informationen finden Sie in Html :: Formfu :: Element und "Andere Kernelemente" in html :: formfu :: element für eine Liste von Kernelementen.

Wenn Sie ein Element aus einem anderen Namespace als HTML::FormFu::Element:: laden möchten, können Sie einen vollständig qualifizierten Paketnamen verwenden, indem Sie es mit + vorangestellt.

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

Wenn in den %options kein type angegeben ist, wird der Text verwendet.

"Element" ist ein Alias für "Elemente".

Deflatoren

Deflator

Argumente: $ type

Argumente: %Optionen

Rückgabewert: $ Deflator

Argumente: @arrayref_of_types_or_options

Rückgabewert: @deflators

Ein Deflator kann jedem Formularfeld zugeordnet sein und ermöglicht es Ihnen, $ field-> Standard mit einem Wert bereitzustellen, der möglicherweise ein Objekt ist.

Wenn ein Objekt nicht an einen geeigneten Wert für die Anzeige angestrahlt wird, kann der Deflator sicherstellen, dass das Formularfeld stattdessen einen geeigneten String -Wert empfängt.

Eine Liste der Kerndeflatoren finden Sie unter "Core Deflators" in html :: formfu :: Deflator.

Wenn ein name nicht angegeben ist, wird ein neuer Deflator für jedes Feld auf dem Formular erstellt und hinzugefügt.

Wenn Sie einen Deflator in einem anderen Namespace als HTML::FormFu::Deflator:: laden möchten, können Sie einen vollständig qualifizierten Paketnamen verwenden, indem Sie ihn mit + vorfixieren.

"Deflator" ist ein Alias für "Deflators".

einfügen_before

Argumente: $ new_element, $ vorhanden_element

Rückgabewert: $ new_element

Das erste Argument muss das Element sein, das Sie hinzugefügt haben, das 2. Argument muss das vorhandene Element sein, das das neue Element zuvor platziert werden sollte.

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

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

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

In der ersten Zeile des obigen Beispiels wird das $new Element zunächst am Ende des Formulars hinzugefügt. Die insert_before -Methode regt jedoch das $new Element um, sodass es nicht mehr am Ende des Formulars liegt. Aus diesem Grund wird es das Element "stehlen", wenn Sie versuchen, ein Element von einer Form in eine andere zu kopieren, anstatt es zu kopieren. In diesem Fall müssen Sie clone verwenden:

 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

Argumente: $ new_element, $ vorhanden_element

Rückgabewert: $ new_element

Das erste Argument muss das Element sein, das Sie hinzugefügt haben, das 2. Argument muss das vorhandene Element sein, nach dem das neue Element platziert werden soll.

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

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

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

In der ersten Zeile des obigen Beispiels wird das $new Element zunächst am Ende des Formulars hinzugefügt. Die insert_after -Methode regt jedoch das $new Element um, sodass es nicht mehr am Ende des Formulars liegt. Aus diesem Grund wird es das Element "stehlen", wenn Sie versuchen, ein Element von einer Form in eine andere zu kopieren, anstatt es zu kopieren. In diesem Fall müssen Sie clone verwenden:

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

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

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

entfernen_element

Argumente: $ Element

Rückgabewert: $ Element

Entfernt das $element aus dem Formular oder Block -Array von Kindern.

 $form->remove_element( $element );

Das verwaiste Element kann für irgendetwas nicht nützlich verwendet werden, wenn es mit "Insert_before" oder "Insert_after" wieder in ein Formular oder mit "Insert_Before" oder "Insert_after" angeschlossen wird.

Formularlogik und Validierung

HTML :: Formfu bietet mehrere Stufen für die traditionell als Validierung bezeichnete Stufen. Diese sind:

Html :: Formfu :: Filter
Html :: formfu :: Connection
Html :: Formfu :: Inflator
Html :: formfu :: validator
Html :: formfu :: transformator

Die erste Stufe, die Filter, ermöglichen die Bereinigung von Benutzereingängen, z. B. Codierung oder Entfernen von Leading/Trailing Whitespace oder Entfernen von nicht-stellenden Zeichen aus einer Kreditkartennummer.

Alle folgenden Phasen ermöglichen eine komplexere Verarbeitung, und jeder von ihnen verfügt über einen Mechanismus, damit Ausnahmen ausgeworfen werden können, um Eingabefehler darzustellen. In jeder Phase müssen alle Formularfelder ohne Fehler verarbeitet werden, um fortzufahren. Bei Fehlern sollte das Formular an den Benutzer weitergegeben werden, damit sie korrekte Werte eingeben können.

Die Einschränkungen sind für die Validierung von Werten auf niedriger Ebene bestimmt, z. B. "Ist das eine Ganzzahl?", "Ist dieser Wert innerhalb von Grenzen?" oder "Ist das eine gültige E -Mail -Adresse?".

Inflatoren sollen zulassen, dass ein Wert in ein geeignetes Objekt verwandelt wird. Das resultierende Objekt wird an nachfolgende Validatoren und Transformatoren übergeben und auch durch "Parameter" und "Param" zurückgegeben.

Validatoren sind für eine höhere Validierung vorgesehen, wie z. B. Business-Logic- und Datenbankbeschränkungen wie "Ist dieser Benutzername einzigartig?". Validatoren werden nur ausgeführt, wenn alle Einschränkungen und Inflatoren ohne Fehler gelaufen sind. Es wird erwartet, dass die meisten Validatoren anwendungsspezifisch sind, und so wird jeder als separate Klasse implementiert, die vom Benutzer von HTML :: Formfu geschrieben wurde.

render_processed_value

Das Standardverhalten bei der erneuten Aufgabe eines Formulars nach einer Einreichung besteht darin, dass das Feld den ursprünglichen, unveränderten Benutzer-Wert enthält.

Wenn "render_processed_value" wahr ist, ist der Feldwert das Endergebnis, nachdem alle Filter, Inflatoren und Transformatoren ausgeführt wurden. Deflatoren werden auch auf dem Wert ausgeführt.

Wenn Sie dies mit einem Inflator auf ein Feld festlegen, jedoch ohne einen äquivalenten Deflator, sollten Sie sicherstellen, dass die Inflators auf einen verwendbaren Wert zurückkehren, um den Benutzer nicht zu verwirren / zu ärgern.

Standardwert: Falsch

Ist ein Erbe -Acterning.

Force_errors

Erzwingen Sie eine Einschränkung, unabhängig von der Benutzereingabe zu scheitern.

Wenn dies zur Laufzeit aufgerufen wird, müssen Sie nach der Verarbeitung des Formulars in Html :: Formfu erneut "Prozess" bezeichnen, bevor Sie das Formular an den Benutzer wieder wiedergeben.

Standardwert: Falsch

Diese Methode ist ein spezieller "ererbter Accessor", was bedeutet, dass sie auf das Formular, ein Blockelement, ein Element oder eine einzige Einschränkung festgelegt werden kann. Wenn der Wert gelesen wird, durchquert er automatisch die Hierarchie des Elements durch Blockelemente und bis zum Formular, um nach einem definierten Wert zu suchen.

Ist ein Erbe -Acterning.

params_ignore_underscore

Wenn wahr, verursacht "Params", "Param" und "gültig", um alle Felder zu ignorieren, deren Name mit einem Unterstrich beginnt _

Das Feld wird immer noch als normal verarbeitet, und Fehler verursachen "ab darüber", um false zurückzugeben.

Standardwert: Falsch

Formattribute

Alle Attribute werden zum Start -Tag des gerenderten Formulars hinzugefügt.

Attribute

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

Ist ein Attribut -Accessor.

Ausweis

Ist ein Attribut kurzschnitten.

Aktion

Standardwert: ""

Holen Sie sich die mit dem Formular verknüpfte Aktion oder setzen Sie sie. Der Standardwert ist keine Aktion, die dazu führt, dass die meisten Browser dem aktuellen URI unterwerfen.

Ist ein Attribut kurzschnitten.

Enctype

Holen Sie sich den Codierungstyp des Formulars. Gültige Werte sind application/x-www-form-urlencoded und multipart/form-data .

Wenn das Formular ein Dateielement enthält, wird der EngeTePe automatisch auf multipart/form-data eingestellt.

Ist ein Attribut kurzschnitten.

Verfahren

Standardwert: "Post"

Holen Sie sich die Methode, mit der das Formular eingereicht wurde. Kann entweder auf "Post" oder "Get" eingestellt werden.

Ist ein Attribut kurzschnitten.

Titel

Holen Sie sich das Titelattribut des Formulars.

Ist ein Attribut kurzschnitten.

CSS -Klassen

Form_error_message_class

Klassenattribut für die Fehlermeldung oben im Formular.

Siehe "Form_error_message"

LOKALISIERUNG

Sprachen

Argumente: [ @uanguages]

Eine Liste von Sprachen, die an das Lokalisierungsobjekt übergeben werden.

Standardwert: ['en']

LOCORIZE_CLASS

Argumente: [$ class_name]

Klassenname für das Standard -Lokalisierungsobjekt verwendet werden.

Standardwert: 'html :: formfu :: i18n'

lokalisieren

loc

Argumente: [$ key, @Arguments]

Kompatibel mit der maketext -Methode im Ort :: Maketext.

Gebietsschema

Argumente: $ Locale

Derzeit wird nur von html :: formfu :: Deflator :: FormatNumber und html :: formfu :: filter :: formatNumber verwendet.

Ist ein Erbe -Acterning.

Verarbeitung eines Formulars

Abfrage

Argumente: [$ query_object]

Argumente: %Params

Geben Sie ein CGI-kompatibles Abfrageobjekt oder ein Hash-Ref von eingereichten Namen/Werten an. Alternativ kann das Abfrageobjekt direkt an das "Prozess" -Objekt übergeben werden.

query_type

Argumente: [$ query_type]

Setzen Sie, mit welchem Modul die "Abfrage" bereitgestellt wird.

Der Katalysator :: Controller :: html :: formfu setzt dies automatisch auf Catalyst .

Gültige Werte sind CGI , Catalyst und CGI::Simple .

Standardwert: 'CGI'

Verfahren

Argumente: [$ query_object]

Argumente: [%Params]

Verarbeiten Sie die bereitgestellten Abfragebobjekte oder Eingabewerte. process muss aufgerufen werden, bevor die Methoden aufgerufen werden, die unter "über eingereichten Formularwerte und -fehler gesenkt" aufgeführt sind und "ein eingereichtes Formular ändern" werden.

process muss auch mindestens einmal aufgerufen werden, bevor das Formular gedruckt oder "Render" oder "render_data" angerufen wird.

Hinweis an Benutzer von Catalyst :: Controller :: html :: formfu: Weil "Prozess" vom Catalyst Controller automatisch auffordert; Wenn Sie Änderungen des Formulars innerhalb Ihrer Aktionsmethode vornehmen, z. B. das Hinzufügen oder Ändern von Elementen, Hinzufügen von Einschränkungen usw.; Sie müssen "Process" erneut selbst aufrufen, bevor Sie "ordnungsgemäß_and_valid", eine der unter "übermittelten Formularwerte und -fehler und Fehler" aufgeführten Methoden oder "Änderung eines übermittelten Formulars" oder das Rendern des Formulars.

Eingereichte Formularwerte und Fehler

eingereicht

Gibt true zurück, wenn das Formular eingereicht wurde. Weitere Informationen dazu finden Sie in der "Anzeige", wie dies berechnet wird.

eingereicht_and_valid

Kurzschrift für $form->submitted && !$form->has_errors

Parameter

Rückgabewert: %Params

Gibt einen Hash-Ref aller gültigen Eingaben zurück, für die keine Fehler vorhanden waren.

param_value

Argumente: $ field_name

Eine zuverlässigere, empfohlene Version von "Param". Garantiert immer einen einzelnen Wert zurückgeben, unabhängig davon, ob er im Listenkontext aufgerufen wird oder nicht. Wenn mehrere Werte eingereicht wurden, gibt dies nur den ersten Wert zurück. Wenn der Wert ungültig ist oder das Formular nicht eingereicht wurde, gibt er undef zurück. Dies macht es für die Verwendung im Listenkontext geeignet, bei dem ein einzelner Wert erforderlich ist.

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

param_array

Argumente: $ field_name

Garantiert immer wieder ein Array-Ref von Werten zurückgibt, unabhängig vom Kontext und unabhängig davon, ob mehrere Werte eingereicht wurden oder nicht. Wenn der Wert ungültig ist oder das Formular nicht eingereicht wurde, gibt er ein leeres Array-Ref zurück.

param_list

Argumente: $ field_name

Garantiert immer eine Liste von Werten zurückgeben, unabhängig vom Kontext. Wenn der Wert ungültig ist oder das Formular nicht eingereicht wurde, gibt es eine leere Liste zurück.

Param

Argumente: [$ field_name]

Rückgabewert: $ input_Value

Rückgabewert: @valid_names

Für den Einsatz nicht mehr empfohlen, da sein Verhalten schwer vorherzusagen ist. Verwenden Sie stattdessen "param_value", "param_array" oder "param_list".

Eine (readonly) Methode ähnlich der von CGI.

Wenn ein Feldname angegeben ist, gibt im Listenkontext alle für dieses Feld übermittelten gültigen Werte zurück, und in Scalar-Kontext gibt nur die ersten der für dieses Feld übermittelten gültigen Werte zurück.

Wenn kein Argument angegeben ist, gibt eine Liste aller gültigen Eingabefeldnamen ohne Fehler zurück.

Das Bestehen von mehr als 1 Argument ist ein tödlicher Fehler.

gültig

Argumente: [$ field_name]

Rückgabewert: @valid_names

Rückgabewert: $ bool

Wenn ein Feldname gegeben ist, gibt es true zurück, wenn dieses Feld keine Fehler hatte und false , wenn Fehler vorliegen.

Wenn kein Argument angegeben ist, gibt eine Liste aller gültigen Eingabefeldnamen ohne Fehler zurück.

Has_errors

Argumente: [$ field_name]

Rückgabewert: @Names

Rückgabewert: $ bool

Wenn ein Feldname gegeben ist, gibt es true zurück, ob dieses Feld Fehler hatte und false wenn keine Fehler vorliegen.

Wenn kein Argument angegeben ist, gibt eine Liste aller Eingabefeldnamen mit Fehlern zurück.

get_errors

Argumente: [%Optionen]

Rückgabewert: @Errors

Gibt eine Array-Ref von Ausnahmebobjekten aus allen Feldern in der Form zurück.

Akzeptiert sowohl name type auch stage , um die zurückgegebenen Ergebnisse einzugrenzen.

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

get_error

Argumente: [%Optionen]

Rückgabewert: $ Fehler

Akzeptiert die gleichen Argumente wie "get_errors", gibt aber nur den ersten gefundenen Fehler zurück.

Modell / Datenbankinteraktion

Weitere Details und verfügbare Modelle finden Sie unter html :: Formfu :: Modell.

default_model

Argumente: $ model_name

Standardwert: 'DBIC'

Modell

Argumente: [$ model_name]

Rückgabewert: $ Modell

model_config

Argumente: %config

Ändern eines eingereichten Formulars

add_valid

Argumente: $ name, $ value

HTML::FormFu bietet ein Plugin-System, mit dem Plugins einfach zu einem Formular oder Element hinzugefügt werden können, um das Standardverhalten oder die Ausgabe zu ändern.

Weitere Informationen finden Sie unter html :: Formfu :: Plugin.

Erweiterte Anpassung

Standardmäßig rendert Formfu "XHTML 1.0 Strict" -Kennzeichen mit so wenig zusätzlichem Aufschlag wie möglich. Viele Haken werden bereitgestellt, um programmatisch erzeugte CSS-Klassennamen hinzuzufügen, damit eine breite Ausgangsstile durch Ändern des CSS generiert werden kann.

Grundlegende Anpassungen des Markups sind über die Methoden Layout und Multi_Layout möglich. Auf diese Weise können Sie die Position verschiedener Teile jedes Feldes - wie der Etikett, der Kommentar, der Fehlermeldungen und des Eingabetags - neu ordnen und alle anderen willkürlichen Tags einfügen, die Sie möglicherweise wünschen.

Wenn dies nicht ausreicht, können Sie das Markup vollständig personalisieren, indem Sie HTML :: Formfu mit einer externen Rendering -Engine wie Vorlagen -Toolkit oder Vorlage :: Alloy mitteilen. Weitere Informationen finden Sie unter "Render_Method" und "TT_MODULE".

Selbst wenn Sie HTML :: Formfu so einstellen, dass die Formulare vorlagen :: Toolkit, können die Formulare in Verbindung mit dem anderen Templatesystem, das Sie für <TMPL_VAR form> eigene Seitenlayouts verwenden, in Verbindung mit welchem anderen Templatesystem verwendet werden <form tal:replace="form"></form>  .

Ab HTML::FormFu v1.00 ist TT nicht mehr eine erforderliche Voraussetzung aufgelistet. Sie müssen daher manuell installieren, wenn Sie die Vorlagendateien verwenden möchten.

render_method

Standardwert: string

Kann auf tt eingestellt werden, um das Formular mit externen Vorlagendateien zu generieren.

Um das Markup anzupassen, benötigen Sie eine Kopie der Vorlagendateien, die lokal an Ihre Anwendung sind. Weitere Informationen finden Sie unter "Installieren der TT -Vorlagen" in html :: formfu :: manual :: cookbook.

Sie können das Markup für ein einzelnes Element anpassen, indem Sie das Element "render_method" an tt festlegen, während der Rest des Formulars die Standard string -Render-Methode verwendet. Beachten Sie jedoch, dass, wenn Sie versuchen, das Formular oder das "Render_Method" eines Blocks auf tt festzulegen, und dann das "Render_Method" eines untergeordneten Elements auf string einstellen, diese Einstellung wird ignoriert und die untergeordneten Elemente werden immer noch den tt -Render-Methode verwenden.

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

Ist ein Erbe -Acterning.

Dateiname

Ändern Sie den für das Formular verwendeten Vorlagendateinamen.

Standardwert: "Form"

tt_args

Argumente: [%constructor_arguments]

Akzeptiert eine Hash-Ref von Argumenten, die an "render_method" übergeben wurden und von "Render" intern bezeichnet wird.

Innerhalb von TT_ARGs werden die Tasten RELATIVE und RECURSION so überschrieben, dass es immer wahr ist, da diese eine grundlegende Anforderung für die Vorlagenmotor sind.

Das Systemverzeichnis, das die Vorlagendateien von HTML :: Formfu enthält, wird immer zum Ende von INCLUDE_PATH hinzugefügt, sodass die Kernvorlagendateien gefunden werden. Sie müssen dies nur selbst einstellen, wenn Sie eine eigene Kopie der Vorlagendateien für Anpassungszwecke haben.

add_tt_args

Argumente: [%constructor_arguments]

Stellt sicher, dass das Hash-Ref-Argument mit jedem bestehenden Hash-Ref-Wert von "tt_args" verschmolzen wird.

tt_module

Standardwert: Vorlage

Das Modul, das verwendet wird, wenn "render_method" auf tt gesetzt ist. Sollte eine mit der Vorlage kompatibele Schnittstelle bereitstellen.

render_data

Normalerweise implizit von "rendern" bezeichnet. Gibt die Datenstruktur zurück, die normalerweise an die string oder tt Render-Methoden übergeben wird.

Wie bei "Render" müssen Sie nach dem Erstellen des Formulars und bevor Sie "render_data" aufrufen.

render_data_non_recursive

Wie "render_data", enthält aber die Daten nicht für Kinderelemente.

SELBSTBEOBACHTUNG

get_fields

Argumente: [%Optionen]

Rückgabewert: @elements

Gibt alle Felder in der Form zurück (insbesondere alle Elemente, die ein wahres "is_field" in html :: formfu :: elementalwert haben).

Akzeptiert sowohl name als auch type , um die zurückgegebenen Ergebnisse einzugrenzen.

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

Akzeptiert auch einen Regexp, um nach Ergebnissen zu suchen.

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

get_field

Argumente: [%Optionen]

Rückgabewert: $ Element

Akzeptiert die gleichen Argumente wie "get_fields", gibt aber nur das erste gefundene Feld zurück.

get_elements

Argumente: [%Optionen]

Rückgabewert: @elements

Gibt alle Elemente der obersten Ebene in der Form zurück (nicht rekursiv). Eine rekursive Version finden Sie "get_all_elements".

Akzeptiert sowohl name als auch type , um die zurückgegebenen Ergebnisse einzugrenzen.

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

Akzeptiert auch einen Regexp, um nach Ergebnissen zu suchen.

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

get_element

Argumente: [%Optionen]

Rückgabewert: $ Element

Akzeptiert dieselben Argumente wie "get_elements", gibt aber nur das erste gefundene Element zurück.

Eine rekursive Version "get_all_element" finden Sie in einer rekursiven Version.

get_all_elements

Argumente: [%Optionen]

Rückgabewert: @elements

Gibt alle Elemente in der Form rekursiv zurück.

Akzeptiert optional sowohl name als auch ein, um Argumente type , um die zurückgegebenen Ergebnisse einzugrenzen.

 # return all Text elements

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

Akzeptiert auch einen Regexp, um nach Ergebnissen zu suchen.

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

Eine nicht rekursive Version "get_elements" finden Sie.

get_all_element

Argumente: [%Optionen]

Rückgabewert: $ Element

Akzeptiert dieselben Argumente wie "get_all_elements", gibt aber nur das erste gefundene Element zurück.

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

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

Akzeptiert auch einen Regexp, um nach Ergebnissen zu suchen.

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

Eine nicht rekursive Version "get_all_elements" finden Sie.

get_deflators

Argumente: [%Optionen]

Rückgabewert: @deflators

Gibt alle Deflatoren auf höchstem Niveau aus allen Feldern zurück.

Akzeptiert sowohl name als auch type , um die zurückgegebenen Ergebnisse einzugrenzen.

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

get_deflator

Argumente: [%Optionen]

Rückgabewert: $ Element

Akzeptiert dieselben Argumente wie "get_deflators", gibt aber nur den ersten gefundenen Deflator zurück.

get_filters

Argumente: [%Optionen]

Rückgabewert: @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.

Klon

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

KOCHBUCH

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 .