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 the data as JSON. The json_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.

cpanm HTML::FormHandlerX::Field::JavaScript

perl -MCPAN -e shell
install HTML::FormHandlerX::Field::JavaScript