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

SYNOPSIS
      use JSAN::ServerSide;

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

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

    In a template ...

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

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

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 "uris()", it returns a list of uris in the necessary
    order to satisfy the dependencies it found.

  Caching
    Dependency information is cached in memory in the *class* in such a way
    as to preserve this information across requests under mod_perl, meaning
    you can create a new "JSAN::ServerSide" object for each request and
    Javascript files which have not changed will not be re-parsed.

METHODS
    This class provides the following functions:

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

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

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

MOCK JSAN
    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 that
    could work, 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 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.