/ 
Form-Tiny-2.25
River stage one • 2 direct dependents • 2 total dependents
/ Form::Tiny::Meta

NAME

Form::Tiny::Meta - main class of the Form::Tiny metamodel

SYNOPSIS

my $meta_object = FormClass->form_meta;

DESCRIPTION

This documentation lists attributes and methods of the metamodel class of a Form::Tiny form. For an overview, see Form::Tiny::Manual::Internals.

ADDED INTERFACE

This section describes the interface added to your class after mixing in the Form::Tiny role.

ATTRIBUTES

Each of the attributes can be accessed by calling its name as a function on Form::Tiny::Meta object.

package

Contains the name of a package this metaobject belongs to. May be empty if the form is anonymous.

Setting the package will automatically install a form_meta method for it, if it doesn't exist already.

predicate: has_package

writer: set_package

fields

Array reference of fields defined for this form. Each field can be either of class Form::Tiny::FieldDefinition (if it is static) or Form::Tiny::FieldDefinitionBuilder (if dynamic).

Don't use this attribute if you want to obtain finished fields for a particular form object - use "resolved_fields" for that instead.

writer: set_fields

hooks

Array reference of hooks defined for this form. Each will be an instance of Form::Tiny::Hook.

writer: set_hooks

complete

Boolean flag used to keep track whether the form building has finished. The form is considered finished after setup method was fired.

A finished form is done with inheritance and ready to be customized. This should usually not be a concern since form bootstrapping is done as soon as possible.

meta_roles

A list of roles which have been applied to this metaobject. Children forms will use it to apply the same roles to themselves. It is also used to apply meta_roles from Form::Tiny::Plugin.

writer: set_meta_roles

form_roles

A list of roles which have been applied to the "package". Since the form packages inherit from one another, this is not inherited from the parent's metaobject. It is used to apply roles from Form::Tiny::Plugin.

writer: set_form_roles

messages

A list of messages used for creating errors in "build_error". The values are usually set with "form_message" in Form::Tiny.

is_flat

Boolean flag used to keep track whether the form is flat. Form is considered flat if it has no nested or dynamic fields.

writer: set_flat

is_dynamic

Boolean flag used to keep track whether the form is dynamic. Form is considered dynamic if it has dynamic fields. Note that a form cannot be flat and dynamic at the same time.

writer: set_dynamic

METHODS

This section describes standalone methods available in the module - they are not directly connected to any of the attributes.

new

This is a Moose-flavored constructor for the class. It accepts a hash or hash reference of parameters, which are the attributes specified above.

build_error

my $error = $meta->build_error($class => %params);

Builds an error of class "Form::Tiny::Class::$class" and uses %params to contsruct it. If a custom message was defined for this type, it will be used instead of any error passed in %params.

run_hooks_for

$meta->run_hooks_for($stage => @data);

Runs hooks for a given $stage. @data should contain all a hook type need for running.

bootstrap

$meta->bootstrap;

Main metaobject initialization routine. It only runs if the model is not yet complete. Performs inheritance and runs "setup" after it's done.

setup

$meta->setup;

Sets the form as complete and does nothing otherwise. It is meant to be used as a checkpoint for any extensions where they can safely hook in and install their custom behavior, for example:

after 'setup' => sub {
	my ($self) = @_;

	$self->add_hook(...);
};

resolved_fields

my $result_aref = $meta->resolved_fields($form_object);

Returns field objects resolved for given $form_object. The resulting array reference will only contain instances of Form::Tiny::FieldDefinition built for given form.

add_field

Adds a new field to the form.

add_field_validator

Adds a new field validator to the form's field.

add_hook

Adds a new hook to the form.

add_message

Adds a new error message to the form.

inherit_roles_from

$meta->inherit_roles_from($parent);

Inherits and applies various roles. If an extension would alter the way roles are treated, this is the place to hook into.

inherit_from

$meta->inherit_from($parent);

Inherits all the form attributes from $parent. If an extension introduces new fields and you want them to be inherited, you must hook to this method, like:

after 'inherit_from' => sub {
	my ($self, $parent) = @_;

	$self->set_my_field([@{$self->my_field}, @{$parent->my_field}]);
};

static_blueprint

blueprint

# for dynamic forms or when
# it is not known whether the form in dynamic
$blueprint = $meta->blueprint($form_object, %options);

# for static forms
$blueprint = $meta->blueprint(%options);

For blueprint explanation, see "Form blueprint" in Form::Tiny::Manual::Internals.

For static forms without extra options, the blueprint will be cached and reused on the next call. Otherwise, it has to be generated each time, which will impose a performance hit if it is called frequently.

Additionally, the blueprint method can accept a hash of options. Currently supported options are:

  • recurse => Bool

    If passed 0, subforms will not be turned into their own blueprints, but will end up as a Form::Tiny::FieldDefinition object instead. 1 by default.

  • transform => sub ($field_definition, $default_handler)

    This option enables a way to specify a custom handler which will be used to turn $field_definition into a blueprint value. This subroutine reference is expected to return a scalar value - a new blueprint value.

    In case you want to turn back into the default handler, call $default_handler->($field_definition).

inline_hooks

Internal, implementation specific - returns flattened hook runners for runtime optimization.