HTML FormFu скачать - скачать исходный код HTML FormFu

Синопсис

Примечание: эти примеры используют html :: formfu :: model :: dbic. Начиная с HTML::FormFu v02.005, модуль html :: formfu :: model :: dbic не связан с HTML::FormFu и доступен в отдельном распределении.

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

Если вы используете катализатор, может быть более подходящий пример:

 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;

}

Примечание: потому что «процесс» автоматически требуется для вас контроллером катализатора; Если вы вносите какие -либо изменения в форму в рамках вашего метода действия, такие как добавление или изменение элементов, добавление ограничений и т. Д; Вы должны снова позвонить в «процесс», прежде чем использовать «Opported_and_valid», любой из методов, перечисленных в разделе «Представленные значения и ошибки формы» или «изменение отправленной формы», или рендеринг формы.

Вот пример файла конфигурации для создания основной формы входа в систему (все примеры здесь - YAML, но вы можете использовать любой формат, поддерживаемый Config :: Any), вы также можете создавать формы непосредственно в вашем коде Perl, а не использовать внешний файл конфигурации.

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

ОПИСАНИЕ

HTML :: FormFU - это структура формы HTML, целью которой является максимально проще использовать для основных веб -форм, но с мощностью и гибкостью, чтобы сделать все остальное, что вы можете сделать (до тех пор, пока он включает в себя формы).

Вы можете настроить практически любую часть поведения и вывода Formfu. По умолчанию Formfu отображает «xhtml 1.0 строгой», соответствующей соответствующей разметке, с максимально небольшей дополнительной разметкой, но с достаточными именами классов CSS, чтобы позволить широкомасштабному стилям вывода, которые будут генерироваться путем изменения только CSS.

Все методы, перечисленные ниже (кроме «нового»), можно назвать как обычный метод на вашем объекте $form , либо в качестве опции в вашем файле конфигурации. Примеры будут в основном показаны в синтаксисе конфигурации YAML.

Эта документация следует за соглашением о том, что аргументы метода, окруженные квадратными скобками [] являются необязательными , и все остальные аргументы требуются.

Создание формы

новый

Аргументы: [%варианты]

Возвращаемая стоимость: $ form

Создайте новый объект html :: formfu.

Любой метод, который можно вызвать на объекте html :: formfu, может быть передан в качестве аргумента «новой».

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

load_config_file

Аргументы: $ filename

Аргументы: @filenames

Возвращаемая стоимость: $ form

Принимает имя файла или список имен файлов, филетипы которых должны быть в любом формате, распознаваемом Config :: Any.

Содержание каждого файла конфигурации передается «Заполнение», и поэтому добавляется в форму.

«LOAD_CONFIG_FILE» может быть вызвана в самом файле конфигурации, чтобы позволить хранить общие настройки в одном файле конфигурации, который может быть загружен любой формой.

 ---
load_config_file:
  - file1
  - file2

Ямл несколько документов в одном файле. Маркер начала документа - это линия, содержащая 3 тире. В порядке будет применяться несколько документов, как если бы было дано несколько имен файлов.

В следующем примере используются несколько документов, чтобы загрузить другой файл конфигурации после добавления элементов. (Если бы это был единственный документ, то load_config_file был бы вызван перед elements , независимо от его позиции в файле).

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

---
load_config_file: ext.yml

Относительные пути разрешаются из каталога "config_file_path", если он установлен, в противном случае из текущего рабочего каталога.

См. «Лучшие практики» для совета по организации файлов конфигурации.

config_callback

Аргументы: %варианты

Если определены, аргументы используются для создания Data :: Visitor :: Callback объект во время "LOAD_CONFIG_FILE", который может использоваться для предварительного обработки конфигурации до того, как он будет отправлен в «Заполнение».

Например, приведенный ниже код добавляет обратный вызов к форме, которая динамически изменяет любое значение конфигурации, заканчивающее «.yml», чтобы закончить в «.yaml», когда вы называете «load_config_file»:

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

Значение по умолчанию: не определено

Этот метод представляет собой специальный «унаследованный доход», что означает, что его можно установить на форму, элемент блока или один элемент. Когда значение считывается, если не определено значение, оно автоматически пересекает иерархию элемента родителей, через любые элементы блока и в соответствии с формой, ища определенного значения.

заполнять

Аргументы: %варианты

Возвращаемая стоимость: $ form

Каждая клавиша/значение опции может быть любым именем и аргументами HTML :: Formfu.

Предоставляет простой способ установить несколько значений или добавить несколько элементов в форму с одним вызовом метода.

Попытки позвонить в имена метода в полуэтъемке порядка (источник opulate () в HTML::FormFu::ObjectUtil для деталей).

default_values

Аргументы: %по умолчанию

Возвращаемая стоимость: $ form

Установите значения по умолчанию нескольких поля из одного хеш-реф.

Ключи хеш-реф соответствуют имени поля формы, и значение передается методу по умолчанию поля.

Это должно быть вызвано после того, как все поля были добавлены в форму, и до того, как «процесс» будет вызван (в противном случае, образуйте «процесс», еще раз перед тем как рендеринг формы).

config_file_path

Аргументы: $ DICERETORY_NAME

«config_file_path» определяет, где будут искать файлы конфигурации, если абсолютный путь не будет предоставлен "load_config_file".

Значение по умолчанию: не определено

Это наследственный аксессу.

индикатор

Аргументы: $ field_name

Аргументы: & coderef

Если «Индикатор» установлен на имя FieldName », отправлено» вернет True, если будет представлено значение для этого имени FieldName.

Если «индикатор» устанавливается на код-реф, он будет вызван как подпрограмма с двумя аргументами $form и $query , а его возвратное значение будет использоваться в качестве возврата для «отправленного».

Если «Индикатор» не установлен, отправлено »вернет true, если будет представлено значение для любого известного имени FieldName.

auto_fieldset

Аргументы: 1

Аргументы: %варианты

Возвращающаяся стоимость: $ fieldset

Эта настройка подходит для большинства основных форм и означает, что вы обычно можете игнорировать добавление Fieldsetes самостоятельно.

Вызов $form->auto_fieldset(1) немедленно добавляет элемент поля в форму. После этого $form->elements() добавят все элементы (кроме поля) в этот поле, а не непосредственно в форму.

Чтобы быть конкретным, элементы добавляются к последнему поле в форме, поэтому, если вы добавите еще один поле, любые дополнительные элементы будут добавлены к этому поле.

Кроме того, вы можете передать Hashref в Auto_fieldset (), и это будет использоваться для установки дефолтов для первого созданного полета.

Несколько примеров и их результатов, чтобы продемонстрировать:

2 элемента без полета.

 ---
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 элемента с «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>

3 -й элемент находится в новом поле

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

Из -за этого поведения, если вы хотите вложенных полевых наборов, вам придется добавить каждый вложенный поля непосредственно к его предполагаемому родителю.

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

$parent->element('fieldset');

form_error_message

Аргументы: $ строка

Обычно ошибки ввода вызывают отображение сообщения об ошибке вместе с подходящим полевым полем. Если вы также хотите, чтобы общее сообщение об ошибке было отображено в верхней части формы, вы можете установить сообщение с помощью "form_error_message".

Чтобы установить класс CSS для сообщения, см. «Form_error_message_class».

Чтобы изменить разметку, используемую для отображения сообщения, отредактируйте файл шаблона form_error_message . Смотрите "render_method".

Это выходной доступ.

force_error_message

Если True, вынуждает отображение «form_error_message», даже если нет ошибок поля.

default_args

Аргументы: %по умолчанию

Установите значения по умолчанию, которые будут добавлены в каждый элемент, ограничение и т. Д. Удачного типа, который впоследствии добавляется в форму.

Например, чтобы каждый Text элемент автоматически имел размер 10 , и сделать каждый дефлятор Strftime автоматически устанавливает свой strftime на %d/%m/%Y :

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

Пример, чтобы сделать все элементы DateTime автоматически получить соответствующий дефлятор Strftime и надув DateTime:

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

Псевдо типы

В качестве особого случая вы также можете использовать Block клавиш elements , Field и Input , чтобы соответствовать любому элементу, который наследует от html :: formfu :: element :: block или что does html :: formfu :: lement :: element :: field или html :: formfu :: lement :: element :: input.

Альтернативы

Каждый ключ elements может содержать any список, используя | Разделитель: например,

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

Совместный предок

Каждый список ключей elements может содержать тип, начинающийся с + чтобы соответствовать элементам только с предком данного типа: например,

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

Не сопоставляйте предка

Каждый список ключей elements может содержать тип, начиная с - только для сопоставления элементов, у которых нет предка данного типа: например,

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

Заказ

Аргументы применяются в самом конкретном порядке: Block , Field , Input , $type . Внутри каждого из них аргументы применяются в порядке кратчайшего первого до самого длинного.

Ключ type должен соответствовать значению, возвращаемому type , например, «Тип» в html :: formfu :: element. Если, например, у вас есть пользовательский элемент за пределами HTML::FormFu::Element::* namespace, который вы загружаете через $form->element({ type => '+My::Custom::Element' }) , ключ, данный «default_args», не должен включать в себя лидирует + , как то, что урезано от возвращаемого type() значения. Пример:

 # 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

Столкновения

«default_args» генерирует один хэшреф для передачи «заполняет», объединяя аргументы для каждого типа по очереди - значение «заполнение» называется только один раз в общем случае - не один раз для каждого типа. Поскольку скалярные значения не объединены - это означает, что более поздние значения переопределяют более ранние значения: например,

 # 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

Строгость

ПРИМЕЧАНИЕ. В отличие от правильных методов, которые имеют псевдонимы, например, «элементы», что является псевдонимом для «элемента» - ключи, данные default_args должны быть во множественном числе, например:

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

JavaScript

Если установлено, содержимое будет отображаться в теге script , внутри верхней части формы.

javascript_src

Аргументы: $ url

Аргументы: @urls

Добавляет тег script для каждого URL, непосредственно перед любому разделу «JavaScript».

хранение

Аргументы: [%private_stash]

Возвращение значения: %хранения

Предоставляет хеш-реф, в котором вы можете хранить любые данные, которые вы можете связать с формой.

 ---
stash:
  foo: value
  bar: value

элементы

элемент

Аргументы: $ Тип

Аргументы: %варианты

Возвращающаяся стоимость: $ element

Аргументы: @arrayref_of_types_or_options

Возвращаемое значение: @Elements

Добавляет новый элемент в форму. См. «Поля основной формы» в html :: formfu :: element и «Другие элементы основного» в html :: formfu :: element для списка основных элементов.

Если вы хотите загрузить элемент из пространства имен, отличных от HTML::FormFu::Element:: , вы можете использовать полностью квалифицированное имени пакета, префикс его с помощью + .

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

Если type не указан в %options , будет использоваться Text по умолчанию.

«Элемент» - это псевдоним для «элементов».

дефляторы

дефлятор

Аргументы: $ Тип

Аргументы: %варианты

Возвращающаяся стоимость: $ deflator

Аргументы: @arrayref_of_types_or_options

Возвращаемое значение: @deflators

Дефлятор может быть связан с любым полем форм и позволяет предоставить $ Field-> Default со значением, которое может быть объектом.

Если объект не обращается к подходящему значению для отображения, дефлятор может убедиться, что поле формы получает подходящее строковое значение.

См. «Основные дефляторы» в html :: formfu :: deflator для списка ядра.

Если атрибут name не предоставлен, новый дефлятор создается и добавляется в каждое поле в форме.

Если вы хотите загрузить дефлятор в пространство имен, отличное от HTML::FormFu::Deflator:: , вы можете использовать полностью квалифицированное пейзаж, префиксируя его + .

«Дефлятор» - это псевдоним для «дефляторов».

INSERT_BEFOR

Аргументы: $ new_element, $ ESCENING_ELEMENT

Возвращение значения: $ new_element

1 -й аргумент должен быть элементом, который вы хотите добавить, 2 -й аргумент должен быть существующим элементом, который новый элемент должен быть размещен ранее.

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

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

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

В первой строке вышеупомянутого примера $new первоначально добавляется к окончанию формы. Тем не менее, метод insert_before Предоставляет $new элемент, так что он больше не будет в конце формы. Из -за этого, если вы попытаетесь скопировать элемент из одной формы в другую, он «украдет» элемент, вместо того, чтобы копировать его. В этом случае вы должны использовать 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

Аргументы: $ new_element, $ ESCENING_ELEMENT

Возвращение значения: $ new_element

1 -й аргумент должен быть элементом, который вы хотите добавить, 2 -й аргумент должен быть существующим элементом, который должен быть помещен новый элемент.

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

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

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

В первой строке вышеупомянутого примера $new первоначально добавляется к окончанию формы. Тем не менее, метод insert_after возместит $new , поэтому он больше не будет находиться в конце формы. Из -за этого, если вы попытаетесь скопировать элемент из одной формы в другую, он «украдет» элемент, вместо того, чтобы копировать его. В этом случае вы должны использовать clone :

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

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

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

remove_element

Аргументы: $ element

Возвращающаяся стоимость: $ element

Удаляет $element из формы или массива блока детей.

 $form->remove_element( $element );

Сиротажный элемент не может быть использован для чего-либо, пока он не будет привлечен к форме или блоке с «INSERT_BEFOR» или «INSERT_AFTER».

Логика формы и проверка

HTML :: FormFU предоставляет несколько этапов для того, что традиционно описывается как проверка . Это:

Html :: formfu :: filter
Html :: formfu :: ограничение
Html :: formfu :: Inflator
Html :: formfu :: varidator
Html :: formfu :: transformer

Это наследственный аксессу.

force_errors

Заставляйте ограничение для сбоя, независимо от ввода пользователя.

Если это вызвано во время выполнения, после того, как форма уже была обработана, вы должны назвать «процесс» в HTML :: Formfu снова, прежде чем перераспределить форму пользователю.

Значение по умолчанию: false

Этот метод представляет собой специальный «унаследованный доход», что означает, что его можно установить на форму, элемент блока, элемент или одно ограничение. Когда значение считывается, если не определено значение, оно автоматически пересекает иерархию элемента родителей, через любые элементы блока и в соответствии с формой, ища определенного значения.

Это наследственный аксессу.

params_ignore_underscore

Если true, вызывает «Params», «Param» и «Value», чтобы игнорировать любые поля, чье имя начинается с подчеркивания _ .

Поле все еще обрабатывается как обычно, и ошибки приведут к «отправке» и «Валид» вернуть false.

Значение по умолчанию: false

Атрибуты формы

Все атрибуты добавляются в начальный тег визуализированной формы.

атрибуты

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

Получить или установить атрибут заголовка формы.

Это атрибут короткий вырез.

CSS -классы

form_error_message_class

Атрибут класса для сообщения об ошибке, отображаемого в верхней части формы.

См. "Form_error_message"

Локализация

языки

Аргументы: [ @languages]

Список языков, которые будут переданы объекту локализации.

Значение по умолчанию: ['en']

Localize_class

Аргументы: [$ class_name]

Имя класса, которое будет использоваться для объекта локализации по умолчанию.

Значение по умолчанию: 'html :: formfu :: i18n'

локализовать

лок

Аргументы: [$ key, @arguments]

Совместим с методом maketext в Locale :: MakeText.

локаль

Аргументы: $ locale

В настоящее время используется только html :: formfu :: deflator :: formatnumber и html :: formfu :: filter :: formatnumber.

Это наследственный аксессу.

Обработка формы

запрос

Аргументы: [$ Query_object]

Аргументы: %Params

Предоставьте CGI-совместимый объект запроса или хеш-реф представленных имен/значений. В качестве альтернативы объект запроса может быть передан непосредственно к объекту «процесса».

Query_type

Аргументы: [$ Query_type]

Установите, какой модуль используется для обеспечения «запроса».

Catalyst :: Controller :: html :: formfu автоматически устанавливает это в Catalyst .

Допустимыми значениями являются CGI , Catalyst и CGI::Simple .

Значение по умолчанию: 'cgi'

процесс

Аргументы: [$ Query_object]

Аргументы: [%params]

Обработайте предоставленный объект запроса или входные значения. process должен быть вызван перед вызовом какого -либо из методов, перечисленных в разделе «Представленные значения и ошибки формы» и «изменение представленной формы».

process также должен быть вызван как минимум один раз перед тем, как распечатать форму или вызов «рендеринг» или «render_data».

Примечание пользователям Catalyst :: Controller :: HTML :: FormFu: Потому что «процесс» автоматически требуется для вас контроллером катализатора; Если вы вносите какие -либо изменения в форму в рамках вашего метода действия, такие как добавление или изменение элементов, добавление ограничений и т. Д; Вы должны снова позвонить в «процесс», прежде чем использовать «Opported_and_valid», любой из методов, перечисленных в разделе «Представленные значения и ошибки формы» или «изменение отправленной формы», или рендеринг формы.

Представленные значения формы и ошибки

поданный

Возвращает True, если форма была отправлена. См. «Индикатор» для получения подробной информации о том, как это вычисляется.

Отправлено_and_valid

Shorthand для $form->submitted && !$form->has_errors

параметры

Возвращение значения: %params

Возвращает хеш-реф из всех действительных вводов, для которого не было ошибок.

param_value

Аргументы: $ field_name

Более надежная, рекомендуемая версия "Param". Гарантированно всегда возвращает одно значение, независимо от того, называется ли оно в контексте списка или нет. Если было отправлено несколько значений, это только возвращает первое значение. Если значение является недействительным или форма не была представлена, оно возвращает undef . Это делает его подходящим для использования в контексте списка, где требуется одно значение.

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

param_array

Аргументы: $ field_name

Гарантированно всегда возвращает массив значений, независимо от контекста и независимо от того, были ли представлены несколько значений или нет. Если значение является недействительным или форма не была представлена, оно возвращает пустой массив-реф.

param_list

Аргументы: $ field_name

Гарантированно всегда возвращает список значений, независимо от контекста. Если значение является недействительным или форма не была отправлена, оно возвращает пустой список.

парамет

Аргументы: [$ field_name]

Возвращение значения: $ input_value

Возвращаемое значение: @Valid_Names

Больше не рекомендуется для использования, так как его поведение трудно предсказать. Вместо этого используйте "param_value", "param_array" или "param_list".

(Readonly) метод, аналогичный методу CGI.

Если указано имя поле, в списке-контексте возвращает любые допустимые значения, представленные для этого поля, а в скалярном контексте возвращает только первые из любых допустимых значений, представленных для этого поля.

Если аргумент не указан, возвращает список всех действительных имен поля ввода без ошибок.

Прохождение более 1 аргумента является фатальной ошибкой.

действительный

Аргументы: [$ field_name]

Возвращаемое значение: @Valid_Names

Возвращающаяся стоимость: $ bool

Если имя поля, если дано, возвращает true если у этого поля не было ошибок и false , если были ошибки.

Если аргумент не указан, возвращает список всех действительных имен поля ввода без ошибок.

has_errors

Аргументы: [$ field_name]

Возвращаемое значение: @names

Возвращающаяся стоимость: $ bool

Если имя поля, если дано, возвращает true если у этого поля были ошибки и false , если не было ошибок.

Если аргумент не указан, возвращает список всех имен поля ввода с ошибками.

get_errors

Аргументы: [%варианты]

Возвращаемое значение: @errors

Возвращает массив объектов исключения из всех областей в форме.

Принимает как name , type , так и stage аргументы, чтобы сузить возвращенные результаты.

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

get_error

Аргументы: [%варианты]

Возвращаемое значение: $ ошибка

Принимает те же аргументы, что и «GET_ERRORS», но возвращает только первую обнаруженную ошибку.

Взаимодействие модели / базы данных

См. HTML :: Formfu :: Модель для получения дополнительной информации и доступных моделей.

default_model

Аргументы: $ model_name

Значение по умолчанию: 'dbic'

модель

Аргументы: [$ model_name]

Возвращающаяся стоимость: $ model

model_config

Аргументы: %config

Изменение представленной формы

add_valid

Аргументы: $ name, $ value

Возвращаемая стоимость: $ value

Предоставленное значение заменяет любое текущее значение для названного поля. Это значение будет возвращено в последующих вызовах «Params» и «param», а названное поле будет включено в расчеты для «допустимых».

clear_errors

Удаляет все ошибки из представленной формы.

Рендеринг формы

оказывать

Возвращаемое значение: $ строка

Вы должны назвать «процесс» один раз после построения формы и перед вызовом «рендерингом».

начинать

Возвращаемое значение: $ строка

Возвращает тег начала формы и любой вывод "form_error_message" и "javaScript".

конец

Возвращаемое значение: $ строка

Возвращает тег End Form.

hidden_fields

Возвращаемое значение: $ строка

Возвращает все полные поля скрытой формы.

Система плагина

HTML::FormFu предоставляет плагин-систему, которая позволяет легко добавлять плагины в форму или элемент, чтобы изменить поведение или вывод по умолчанию.

Смотрите HTML :: Formfu :: Плагин для деталей.

Продвинутая настройка

По умолчанию, Formfu делает «xhtml 1.0 строгой», соответствующей совместимой, с максимально возможной дополнительной наценкой. Многие крючки предоставляются для добавления программно сгенерированных имен классов CSS, чтобы позволить генерировать широкий диапазон стилей вывода путем изменения только CSS.

Основная настройка разметки возможна с помощью методов макета и multi_layout. Это позволяет вам переупорядочить положение различных частей каждого поля - например, метка, комментарии, сообщений об ошибках и входного тега, а также вставка любых других произвольных тегов, которые вы можете пожелать.

Если этого недостаточно, вы можете полностью персонализировать разметку, сообщив HTML :: Formfu использовать внешний двигатель рендеринга, такой как Template Toolkit или шаблон :: сплав. Для получения подробной информации см. «Render_method» и «tt_module».

Даже если вы установите HTML :: Formfu для использования Template :: Toolkit to рендеринг, формы, html :: formfu все еще можно использовать в сочетании с какой-либо другой системой шаблонов, которую вы предпочитаете использовать для собственных макетов страницы, будь то HTML :: Template: <TMPL_VAR form> , petal: <form tal:replace="form"></form> или template:  .

По состоянию на HTML::FormFu v1.00 , TT больше не указан необходимым обязательным условием - поэтому вам нужно установить его вручную, если вы хотите использовать файлы шаблонов.

render_method

Значение по умолчанию: string

Может быть установлен в tt для генерации формы с помощью внешних шаблонов.

Чтобы настроить разметку, вам понадобится копия файлов шаблонов, локальная для вашего приложения. См. «Установка шаблонов TT» в HTML :: Formfu :: ancual :: Кулинарная книга для получения дополнительной информации.

Вы можете настроить разметку для одного элемента, установив «render_method» этого элемента на tt , в то время как в остальной части формы используются строковая метод string по умолчанию. Обратите внимание, что если вы попытаетесь установить форму или «render_method» tt , а затем установите «render_method» дочернего элемента на string , эта настройка будет проигнорирована, и детские элементы все равно будут использовать Render-Method tt .

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

  - name: bar

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

Это наследственный аксессу.

имя файла

Измените шаблонное имя файла, используемое для формы.

Значение по умолчанию: "форма"

tt_args

Аргументы: [%constructor_arguments]

Принимает хеш-реф аргументов, переданные «render_method», который внутри «рендерин» называется.

В пределах TT_ARGs, RELATIVE и RECURSION которые всегда переопределены, чтобы всегда быть истинными, так как они являются основным требованием для шаблонного двигателя.

Системный каталог, содержащий файлы шаблонов HTML :: Formfu, всегда добавляется в конец INCLUDE_PATH , так что будут найдены файлы шаблонов основных шаблонов. Вам нужно установить это самостоятельно, только если у вас есть собственная копия файлов шаблонов для целей настройки.

add_tt_args

Аргументы: [%constructor_arguments]

Гарантирует, что аргумент хеш-реф объединен с любым существующим значением хеш-реф «TT_ARGS».

tt_module

Значение по умолчанию: шаблон

Модуль, используемый, когда «render_method» установлен на tt . Должен обеспечить интерфейс, совместимый с шаблоном.

render_data

Обычно называется неявно «рендерингом». Возвращает структуру данных, которая обычно передавалась на string или tt рендер-методы.

Как и в случае с «рендерингом», вы должны назвать «процесс» один раз после создания формы и перед тем, как называть «render_data».

render_data_non_recursive

Как "render_data", но не включает данные для каких-либо детей.

Самоанализ

get_fields

Аргументы: [%варианты]

Возвращаемое значение: @Elements

Возвращает все поля в форме (в частности, все элементы, которые имеют истинную "is_field" в html :: formfu :: alement value).

Принимает как name , так и аргументы type , чтобы сузить возвращенные результаты.

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

Принимает также regexp для поиска результатов.

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

get_field

Аргументы: [%варианты]

Возвращающаяся стоимость: $ element

Принимает те же аргументы, что и «get_fields», но возвращает только первое поле.

get_elements

Аргументы: [%варианты]

Возвращаемое значение: @Elements

Возвращает все элементы верхнего уровня в форме (не рекурсивный). Смотрите «get_all_elements» для рекурсивной версии.

Принимает как name , так и аргументы type , чтобы сузить возвращенные результаты.

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

Принимает также regexp для поиска результатов.

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

get_element

Аргументы: [%варианты]

Возвращающаяся стоимость: $ element

Принимает те же аргументы, что и «get_elements», но возвращает только первый найденный элемент.

См. «Get_all_element» для рекурсивной версии.

get_all_elements

Аргументы: [%варианты]

Возвращаемое значение: @Elements

Возвращает все элементы в форме рекурсивно.

При желании принимает как name и type аргументов, чтобы сузить возвращенные результаты.

 # return all Text elements

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

Принимает также regexp для поиска результатов.

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

См. «GET_ELEMENTS» для нерекурсирующей версии.

get_all_element

Аргументы: [%варианты]

Возвращающаяся стоимость: $ element

Принимает те же аргументы, что и «get_all_elements», но возвращает только первый найденный элемент.

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

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

Принимает также regexp для поиска результатов.

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

См. «GET_ALL_ELEMENTS» для нерекурсирующей версии.

get_deflators

Аргументы: [%варианты]

Возвращаемое значение: @deflators

Возвращает все дефляторы верхнего уровня из всех полей.

Принимает как name , так и аргументы type , чтобы сузить возвращенные результаты.

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

get_deflator

Аргументы: [%варианты]

Возвращающаяся стоимость: $ element

Принимает те же аргументы, что и «get_deflators», но возвращает только первый найденный дефлятор.

get_filters

Аргументы: [%варианты]

Arguments: [%options]

Return Value: @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.

клон

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 .