Javascript Library

Author: Kevin K.M. Chiu
Copyright 2000, Cobalt Networks.  All rights reserved.
$Id: jsLibrary.txt,v 1.2 2000/08/06 21:59:43 kevin Exp $

Overview
========

Javascript is a crucial technology for browser-side manipulation. To make
maintainence of Javascript easier, a Javascript library system is designed.
Its goal is to simplify the addition, removal and access of Javascript from
within the user interface navigation system (See navigation.txt)

Javascript File
===============

Javscript files are files with .js extension and contain Javascript code. Note
that the extension is case sensitive. The Javascript loading system only
recognizes all lowercase .js extenstion. If you do not want your Javascript
file to be handled by the loading system, name it with the all uppercase .JS
extension.

Addition And Removal
====================

To add a Javascript file to the system, simply drop the file under the web
directory as defined as the "webDir" parameter in the user interface
configuration file (i.e. <palette>/conf/ui.cfg).

To remove a Javascript file, remove that file from the directory.

When the navigation system is loaded to the web browser, the whole web
directory and its sub-directories are scanned by the Javascript loading system
and all .js files are loaded to the web browser automatically.

Access
======

Accessing Javascript functions and variables within the navigation system can
be achieved by using the reference "top.code.<function name>" and
"top.code.<variable name>", respectively.

For example, if example.js looks like:

var foo = 10;
function bar() {
  return foo+20;
}

foo and bar can be accessed through top.code.foo and top.foo.bar no matter
what frame the reference is being used.

Ordering
========

Load ordering matters when code in one Javascript file needs to access the other. The
one to be accessed must be loaded before the one that access it. The loader sorts all
Javscript files with their file names (not full path names) in alphabetical order to
determine the loading sequence. Therefore, name your Javascript files according.

Namespace Preservation
======================

Name conflicts can occur when Javascript files use the same name more than
once.

For example, bad1.js is:

function foo() {
  return 10;
}

bad2.js is

var bar = 20;
function foo() {
  return bar;
}

top.code.foo is an unresolvable reference.

Namespace conflicts can be reduced by following this naming convention:
- Prefix the names with the module name of the Javascript file separated by an
  underscore.
- For global variables outside the functions, prefix with an underscore, the
  module name of the Javascript file and another underscore.

bad1.js then becomes:
function bad1_foo() {
  return 10;
}

bad2.js becomes:
var _bad2_bar = 20;
function bad2_foo() {
  return _bad2_bar;
}
