NAME
HTML::FormHandlerX::Field::JSON - a script tag which sets a var using JSON data
, encoded from perl data supplied via field for HTML::FormHandler.
VERSION
version 0.004
SYNOPSIS
This class can be used for fields that need to supply JSON data for use by scripts in the form. It will JSONify and render the value returned by a form's data_<field_name>
method, or the field's data
attribute.
has_field 'user_addresses' => ( type => 'JSON',
data => { john => 'john@example.com', sarah => 'sarah@example.com' } );
or using a method:
has_field 'user_addresses' => ( type => 'JSON' );
sub data_user_addresses {
my ( $self, $field ) = @_;
if( $field->value == 'foo' ) {
return { john => 'john@example.com', sarah => 'sarah@example.com' };
} else {
return [ 'john@example.com', 'sarah@example.com' ];
}
}
#----
has_field 'usernames' => ( type => 'JSON' );
sub data_usernames {
my ( $self, $field ) = @_;
return [ qw'john sarah' ];
}
or set the name of the data generation method:
has_field 'user_addresses' => ( type => 'JSON', set_data => 'my_user_addresses' );
sub my_user_addresses {
....
}
or provide a 'render_method':
has_field 'user_addresses' => ( type => 'JSON', render_method => \&render_user_addresses );
sub render_user_addresses {
my $self = shift;
....
return q(
<script type="text/javascript">
// JSON assignment here
var myVar = 'abc';
</script>);
}
The data generation methods should return a scalar (hashref or arrayref), which will be encoded as JSON, given a variable assignment, and wrapped in script tags. If you supply your own 'render_method' then you are responsible for calling $self->deflator
or $self->wrap_data
yourself.
FIELD OPTIONS
We support the following additional field options, over what is inherited from HTML::FormHandler::Field
- data
-
Scalar (hashref or arrayref) holding the data to be encoded as JSON.
- set_data
-
Name of method that gets called to generate the data.
- data_key
-
Name of JavaScript variable that will be assigned the JSON object. See "JavaScript variable names"
- do_minify
-
Boolean to indicate whether code should be minified using JavaScript::Minifier::XS
- json_opts
-
Hashref with 3 possible keys;
pretty
,relaxed
,canonical
. The values are passed to JSON when encoding the data.
FIELD METHODS
The following methods can be called on the field.
- deflator
-
The
deflator
method is called to encode thedata
as JSON. Thejson_opts
attribute is used to control options for JSON encode. - wrap_data
-
The
wrap_data
method calls$self->deflator
, sets the variable assignment using the JSON object, minifies the code, and wraps the code in script tags.
JavaScript variable names
By default, the name of the variable being assigned is same as the field name. The variable name can be changed with the data_key attribute. If the field name (or data_key value) is a simple string (no dot separator) then the variable will be defined with var varName;
:
has_field 'user_addresses' => ( type => 'JSON',
data => [ qw'john@acme.org sarah@acme.org' ],
);
will render as:
<script type="text/javascript">
var user_addresses = [ "john@acme.org", "sarah@acme.org" ];
</script>);
Otherwise it is assumed the variable is already defined:
has_field 'user_addresses' => ( type => 'JSON',
data_key => 'user_addresses.names',
data => [ qw'john sarah' ],
);
will render as:
<script type="text/javascript">
user_addresses.names = [ "john", "sarah" ];
</script>);
The data_key can begin or end with a dot, in which case the field name is either appended or prepended to the data_key.
has_field 'user_addresses' => ( type => 'JSON',
data_key => '.email',
data => [ qw'john@acme.org sarah@acme.org' ],
);
Will render as:
<script type="text/javascript">
user_addresses.email = [ "john@acme.org", "sarah@acme.org" ];
</script>);
AUTHOR
Charlie Garrison <garrison@zeta.org.au>
COPYRIGHT AND LICENSE
This software is copyright (c) 2014 by Charlie Garrison.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.