4.7. Script Filenames and Locations in Detail

4.7.1. The main Application Script File

When an application instance starts, it looks for a main script file to run. The file can have one of two names and can be stored in one of two locations. The file can be named main with either an .asc or .js extension (main.asc or main.js) or it can have the same name as the application's home directory with either extension. For example, if the application's home directory name is courseChat and if no main.asc file exists, the courseChat.asc file will be loaded. The main file can be stored in one of two places: in the application's home directory or in a subdirectory of the home directory named scripts. Files with the .asc extension take precedence over .js files.

4.7.2. Using load( ) to Include Other Script Files

Once the main file has been loaded and any global code (code defined outside event handlers such as onConnect( )) within it is executed, other source files can be loaded. The load( ) method accepts the relative path of the external file to be compiled and executed. For example, a main.asc file in an application's home directory could load a file in the scripts directory this way:

load("scripts/myFile.asc");

The relative paths cannot include the ".." characters to indicate moving up a level in the directory tree, so there has to be another way to load source files that are common to more than one application. The FlashCom installer creates a directory named scriptlib where the common script files provided by Macromedia are placed. The scriptlib directory contains the files required for Flash Remoting and the communication components. If a file is not found in a path relative to the file that loads it, the server will attempt to find it in a relative path starting from the scriptlib directory. For example, when a main file loads the communication components, it calls:

load("components.asc");

Files can also be placed in subdirectories of the scriptlib directory. For example, the .asc source files for the individual communication components are found in the scriptlib/components directory.

The location of the scriptlib directory can be changed using the <ScriptLibPath> tag of an Application.xml file, and additional paths to other script library directories can be added to it. For example, an Application.xml file can be placed in the home directory of an application. The default tag might look something like this depending on where the server was installed:

<ScriptLibPath>
C:\Program Files\Macromedia\Flash Communication Server MX\scriptlib
</ScriptLibPath>

It could be modified to add a second path, separated from the first one with a semicolon (note that line breaks have been introduced for readability):

<ScriptLibPath>
C:\Program Files\Macromedia\Flash Communication Server MX\scriptlib;
C:\Program Files\Macromedia\Flash Communication Server MX\securitylib
</ScriptLibPath>

Appending a path in the <ScriptLibPath> tag has a number of advantages. You can build your own common library of scripts without placing anything in the scriptlib directory and possibly editing or overwriting the files supplied by Macromedia. By placing individual Application.xml files in the home directory of individual applications, you can make libraries available for only those applications. If you want to add a library for all applications within a virtual host, add a path in the Application.xml file in the virtual host directory.

Figure 4-8 shows the location of a number of source files for an application named courseChat. The securitylib directory was created to hold custom scripts that could be used by any application, and the scripts folder was created to hold scripts just for the courseChat application.

Figure 4-8. Script file locations

The first two lines of the following SSAS source code load in the files required to use Flash Remoting and the communication components. The remaining statements load in source files from the scripts and securitylib directories (the latter is configured via the <ScriptLibPath> tag in the Application.xml file):

// Load files from the scriptlib directory.
load("netservices.asc"); // Load the files required for Remoting
load("components.asc");  // Load the component framework and components

// Load a file from the scripts directory.
load("scripts/ChatClass.asc");

// Load files from the securitylib directory.
load("UserClass.asc");
load("AuthenticationControllerClass.asc");
load("AuthorizationControllerClass.asc");

A scripts directory is not required. All the source files can be kept in the home directory of the application.

4.7.2.1 Dynamically loading script files

The fact that a file is compiled and executed before other files are loaded into it leads to an interesting feature. It is possible to write global code in a file that decides what files to load based on the application's instance name or other factors. For example, suppose you want the _definst_ instance to behave as a lobby while every other instance of the application behaves as a room. The entire main.asc file could contain just a single if statement like this:

if (application.name == "courseChat/_definst_") {
  load("lobby.asc");
}
else {
  load("room.asc")
}

The lobby.asc and room.asc files would then each define a different set of application methods and therefore make the _definst_ instance behave differently from all the others.