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

This documentation refers to Net::SAJAX version 0.106

  # 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};
  }

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

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.

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).

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.

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

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).

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());

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.

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

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);

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.

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.

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.

* Net::SAJAX::Exception for general exceptions not in other categories and the base class.

* Net::SAJAX::Exception::JavaScriptConversion for errors during the conversion of JavaScript structure to native Perl structure.

* Net::SAJAX::Exception::JavaScriptEvaluation for errors during the evaluation of JavaScript returned by the server.

* Net::SAJAX::Exception::MethodArguments for errors related to the values of arguments given to methods.

* Net::SAJAX::Exception::RemoteError for remote errors returned by SAJAX itself.

* Net::SAJAX::Exception::Response for errors in the HTTP response from the server.

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.

* English

* HTTP::Request::Common 5.814

* JE 0.033

* List::MoreUtils

* LWP::UserAgent 5.819

* Moose 0.77

* MooseX::StrictConstructor 0.08

* MooseX::Types::URI 0.02

* URI 1.22

* URI::QueryParam

* namespace::clean 0.04

Douglas Christopher Wilson, <doug at somethingdoug.com>

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.

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

  perldoc Net::SAJAX

You can also look for information at:

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-SAJAX

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Net-SAJAX

* CPAN Ratings

http://cpanratings.perl.org/d/Net-SAJAX

* Search CPAN

http://search.cpan.org/dist/Net-SAJAX/

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.