NAME

JSAN::ServerSide - Manage JSAN dependencies server side instead of with XMLHttpRequest

SYNOPSIS

use JSAN::ServerSide;

my $js = JSAN::ServerSide->new( js_dir     => '/usr/local/js',
                                uri_prefix => '/js',
                              );

$js->add('DOM.Ready');
$js->add('DOM.Display');
$js->add('My.Class');

In a template ...

<script type="text/javascript">
 JSAN = {};
 JSAN.use = function () {};
</script>

% for my $uri ( $js->uris() ) {
 <script src="<% $uri | %>" type="text/javascript"></script>
% }

Or use it to create a single combined file:

my $combined = combine $js->files() );

DESCRIPTION

The JSAN Javascript library allows you to import JSAN libraries in a similar way to as Perl's use. This module provides a server-side replacement for the JSAN library's importing mechanism.

The JSAN library's importing mechanism, which uses XMLHttpRequest, has several downsides. Some browsers (including Firefox) do not respect caching headers when using XMLHttpRequest, so files will always be re-fetched from the server.

After a library is retrieved, JSAN uses Javascript's eval to compile the Javascript libraries, which can cause the browser to report errors as if they were coming from JSAN, not the library that was fetched.

This module lets you create an object to manage dependencies on the server side. You tell it what libraries you want to use, and it finds their dependencies and makes sure they are loaded in the correct order.

Each Javascript file will be parsed looking for JSAN use lines in the form of JSAN.use("Some.Library") .

Then when you call $js-uris() >, it returns a list of uris in the necessary order to satisfy the dependencies it found.

You can also use this module to genereate a single combined Javascript file with the included files in the correct order. Simply call $js-files() > and combine them in the order they are returned.

Caching

Dependency information is cached in memory in the object. If you want to preserve this information in a persistent environment such as mod_perl or FastCGI, you'll need to hold on to a reference to the JSAN::ServerSide object across multiple requests.

METHODS

This class provides the following functions:

• Javascript::ServerSide->new(...)

  This method accepts two parameters:

  o js_dir

  This parameter is required. It is the root directory of your JSAN-style Javascript libraries.

  o uri_prefix

  This parameter is required. It is the prefix to be prepended to generated URIs.

• $js->add('Class.Name')

  This method accepts a JSAN-style library name (like "DOM.Ready") and adds it to the object's list of libraries.

• $js->uris()

  Returns a list of URIs, generated by turning the given JSAN library names into URIs, along with any dependencies specified by those libraries. The list comes back in the proper order to ensure that dependencies are loaded first.

• $js->files()

  Returns a list of files, generated by turning the given JSAN library names into paths, along with any dependencies specified by those libraries. The list comes back in the proper order to ensure that dependencies are loaded first.

MOCKING JSAN.js

If you use this module, you will need to mock out JSAN in your generated HTML/JS. Since the libraries being parsed contain a JSAN.use() call, this interface must be mocked in order to prevent an error.

In the future, I hope JSAN will support a usage mode that only provides exporting, without attempting to load libraries.

Mocking JSAN can be done with the following code:

JSAN = {};
JSAN.use = function () {};

CIRCULAR DEPENDENCIES

Currently, this module allows for circular dependencies because they may not be a problem, depending on how the dependent classes are used.

For example, if "A" depends on "B" and vice versa, then A could still work as long as it does not try to use B immediately at load time, but rather defers that use until it is called by other code.

In Perl, this is never a problem because of the separate between compile and run time phases.

In the future, this module may offer some sort of circular dependency detection.

SEE ALSO

http://www.openjsan.org/, JSAN::Parse::FileDeps, JSAN.pm

AUTHOR

Dave Rolsky, <autarch@urth.org>

BUGS

Please report any bugs or feature requests to bug-jsan-serverside@rt.cpan.org, or through the web interface at http://rt.cpan.org. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

COPYRIGHT & LICENSE

Copyright 2005-2007 Dave Rolsky, All Rights Reserved.

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