/ 
Net-SAJAX-0.107
River stage one • 1 direct dependent • 1 total dependent
/ Net::SAJAX

NAME

Net::SAJAX - Interact with remote applications that use SAJAX.

VERSION

This documentation refers to version 0.107

SYNOPSIS

# Construct a SAJAX interaction object
my $sajax = Net::SAJAX->new(
  url => URI->new('https:/www.example.net/my_sajax_app.php'),
);

# Make a SAJAX call
my $product_name = $sajax->call(
  function  => 'GetProductName',
  arguments => [67632],
);

print "The product $product_name is out of stock\n";

# Make a SAJAX call using POST (usually for big or sensitive data)
my $result = $sajax->call(
  function  => 'SetPassword',
  method    => 'POST',
  arguments => ['My4w3s0m3p4sSwOrD'],
);

if ($result->{result} == 1) {
  print "Your password was successfully changed\n";
}
else {
  printf "An error occurred when setting your password: %s\n",
    $result->{error_message};
}

DESCRIPTION

Provides a way to interact with applications that utilize the SAJAX library found at http://www.modernmethod.com/sajax/.

CONSTRUCTOR

This is fully object-oriented, and as such before any method can be used, the constructor needs to be called to create an object to work with.

new

This will construct a new object.

new(%attributes)

%attributes is a HASH where the keys are attributes (specified in the "ATTRIBUTES" section).

new($attributes)

$attributes is a HASHREF where the keys are attributes (specified in the "ATTRIBUTES" section).

ATTRIBUTES

autoclean_garbage

Added in version 0.102; be sure to require this version for this feature.

This is a Boolean of whether or not to try and automatically clean any garbage from the SAJAX response. Sometime there are just bad web programmers out there and there may be HTML or other data above the SAJAX response (most common in PHP applications). If the stripping fails, then it will work just like normal. The default value is 0, which will mimic the expected SAJAX behavior.

has_target_id

This is a Boolean of whether or not the object has a "target_id" set.

javascript_engine

This is a JE object that is used to evaluate the JavaScript data received. Since this is a custom engine in Perl, the JavaScript executed should not have any security affects. This defaults to JE->new(max_ops => 1000).

send_rand_key

This is a Boolean of if to send a random key with the request. This is part of the SAJAX library and is provided for use. The default for the SAJAX library is to send the random key, but that is an unnecessary method to get around caching issues, and so is it off by default.

# Enable sending of a random key
$sajax->send_rand_key(1);

# Toggle the setting
$sajax->send_rand_key(!$sajax->send_rand_key());

target_id

This is a string that specified the target element ID that the response would normally be added to. This is completely unnecessary in this library, but since it is send with the request, it is possible this could affect the data that is returned. This defaults to nothing and no target ID is sent with the request.

# Change the target ID
$sajax->target_id('content');

# Clear the target ID (restoring default behavior)
$sajax->clear_target_id();

Using "has_target_id", it can be determined if a target ID is currently set on the object. Using "clear_target_id" the target ID will be cleared from the object, restoring default behavior.

url

Required. This is a URI object of the URL of the SAJAX application.

user_agent

This is the LWP::UserAgent object to use when making requests. This is provided to handle custom user agents. The default value is LWP::UserAgent constructed with no arguments.

# Set a low timeout value
$sajax->user_agent->timeout(10);

METHODS

call

This method will preform a call to a remote function using SAJAX. This will return a Perl scalar representing the returned data. Please note that this by returning a scalar, that includes references.

# call may return an ARRAYREF for an array
my $array_ref = $sajax->call(function => 'IReturnAnArray');
print 'Returned: ', join q{,}, @{$array_ref};

# call may return a HASHREF for an object
my $hash_ref = $sajax->call(function => 'IReturnAnObject');
print 'Error value: ', $hash_ref->{error};

# There may even be a property of an object that is an array
my $object = $sajax->call(function => 'GetProductInfo');
printf "Product: %s\nPrices: %s\n",
  $object->{name},
  join q{, }, @{$object->{prices}};

This method takes a HASH with the following keys:

arguments

This is an ARRAYREF that specifies what arguments to send with the function call. This must not contain any references (essentially only strings and numbers). If not specified, then no arguments are sent.

function

Required. This is a string with the function name to call.

method

This is a string that is either "GET" or "POST". If not supplied, then the method is assumed to be "GET", as this is the most common SAJAX method.

clear_target_id

This will clear out the "target_id" set for this object which will cause the object to no longer send a "target_id" with the request.

DIAGNOSTICS

This module, as of version 0.102, will throw Net::SAJAX::Exception objects on errors. This means that all method return values are guaranteed to be correct. Please read the relevant exception classes to find out what objects will be thrown. Depend on at least 0.102 if you want to use object-based exception.

VERSION NUMBER GUARANTEE

This module has a version number in the format of \d+\.\d{3}. When the digit to the left of the decimal point is incremented, this means that this module was changed in such a way that it will very likely break code that uses it. Please see Net::SAJAX::VersionGuarantee.

DEPENDENCIES

AUTHOR

Douglas Christopher Wilson, <doug at somethingdoug.com>

BUGS AND LIMITATIONS

Please report any bugs or feature requests to bug-net-sajax at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-SAJAX. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

I highly encourage the submission of bugs and enhancements to my modules.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Net::SAJAX

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2009 Douglas Christopher Wilson.

This program is free software; you can redistribute it and/or modify it under the terms of either:

  • the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or

  • the Artistic License version 2.0.