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.