NAME

JQuery::DataTables::Request - represents a DataTables server-side request

SYNOPSIS

 my $dt_req = JQuery::DataTables::Request->new( $client_parameters );
 if ( $dt_req->column(0)->{searchable} ) {
   # do something
 }

 $dt_req->search->{value}; # the global search value
 if ($dt_req->search->{regex}) {
   # global search is set to regex
 }

 # find the column definition with the name 'col_name'
 my $cols = $dt_req->find_columns( by_name => 'col_name' );

 $dt_req->draw; #sEcho or draw parameter
 $dt_req->start; #iDisplayStart or start parameter

DESCRIPTION

This module represents a DataTables server-side request originating from the DataTables client side JS library. There are two major versions of DataTables(v1.9 and v1.10) that send differently named parameters server-side for processing. This module only provides an API that corresponds to the v1.10 parameters but maps the v1.9 parameters to the corresponding v1.10 parameters.

The DataTable parameters are documented at the following locations:

Version 1.10 server-side parameters

Version 1.9 server-side parameters

Each column parameter is represented as a HashRef like so:

 {
   name => 'col_name',
   data => 'col_name',
   orderable => 1,
   searchable => 1,
   search => {
     value => 'search string',
     regex => 0,
   }
 }

e.g.

 $dt_req->column(0)->{search}{value}

Order parameters look like this:

 {
   dir => 'asc',
   column => 1
 }   

e.g.

 $dt_req->order(0)->{dir}

The order and column accessors are indexed the same way as your column parameters so $req->column(0) returns the column in the client_params [columns][0] column.

order is similar in that $req->order(0) returns the order[0] parameter data.

METHODS

new

Creates a new JQuery::DataTables::Request object.

 my $dt_request = JQuery::DataTables::Request->new( client_params => $c->parameters );

Accepts the following parameters

client_params

This is a HashRef that should contain your DataTables parameters as provided by the DataTables JS library. Any parameters provided that are not recognized as DataTables request are silently ignored.

new will confess/croak on the following scenarios:

client_params is not provided

client_params is not a HashRef

client_params isn't recognized as containing DataTables parameters

You should catch these if you are worried about it.

column

 my \%column = $request->column(0);

Returns a single column definition of the requested index

columns

 my \@columns = $request->columns([0,1]);

Returns column definitions for the requested indexes. Can accept either an arrayref of scalars or a single column scalar. If no column index is provided all columns are returned.

columns_hashref

Get all column definitions as a Hashref, with the column index as the key

find_columns

 $request->find_columns( %options )

where %options hash accepts the following parameters:

by_name

by_name accepts a scalar or arrayref of values and returns an arrayref of column definitions

 my \@columns = $request->find_columns( by_name => ['col_name','col_name2'] );

Searchs the columns data and/or name parameter.

search_field

 my \@columns = $request->find_columns( by_name => 'something', search_field => 'name' );

Set to either name or data to search those respective fields when doing a by_name seach. If no search_field is specified, by_name searches that match either field will be returned (i.e. defaults to search both fields)

by_idx

 my \@columns = $request->find_columns( by_idx => $col_idx )

This is just a passthrough to $request->columns( $col_idx );

order

 $req->order(0)->{dir}

Returns the order data at provided index.

orders

 $req->orders([0,1]);

Returns an arrayref of the order data records at the provided indexes. Accepts an arrayref or scalar. ->orders([0,1]) will get orders[0] and orders[1] data.

version

 my $version = $request->version( \%client_params? )

Returns the version of DataTables we need to support based on the parameters sent. v1.9 version of DataTables sends different named parameters than v1.10. Returns a string of '1.9' if we think we have a 1.9 request, '1.10' if we think it is a 1.10 request or undef if we dont' think it is a DataTables request at all.

This can be invoked as a class method as well as an instance method.

PRIVATE METHODS

_process_v1_9_params

Processes v1.9 parameters, mapping them to 1.10 parameters

 $self->_process_v1_9_params( \%client_params )

where \%client_params is a HashRef containing the v1.9 parameters that DataTables client library sends the server in server-side mode.

_process_v1_10_params

 $self->_process_v1_10_params( \%client_params );

where \%client_params is a HashRef containing the v1.10 parameters that DataTables client library sends the server in server-side mode.

_validate_and_convert

Validates parameters are set properly and does boolean conversion

AUTHOR

Mike Wisener <xmikew_cpan_org>

COPYRIGHT AND LICENSE

Copyright © 2014 by Mike Wisener

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm JQuery::DataTables::Request

perl -MCPAN -e shell
install JQuery::DataTables::Request