Dave Rolsky > JSAN-ServerSide-0.06 > JSAN::ServerSide

Download:
JSAN-ServerSide-0.06.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.06   Source  

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:

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.

syntax highlighting: