Active Script Library
Help

Project Homepage hosted by SFLOGO
Index



General Setup

N.B. For an overview of the concepts behind this application, read the article on Dynamic JavaScript in the September 1999 edition of DominoPower magazine.

URL: http://www.dominopower.com/issues/issue199909/java001.html

Adding Scripts

Create Script documents from the Notes Create menu. Each Script document contains a package of script functions.

You may have as many functions as you like in each script document, up to a maximum of 64,000 characters . Each script should have a unique name, a language (default JavaScript ), a language version (default All ) and optionally a script version and comments. Use the Script Import action, or type/paste your script code into the box provided.

For ease of reference, use the Build Function List to automatically analyze the script code and extract a list of function names. A separate view by function will let you cross-reference functions by scripts.

Also, you may use the Compress Code button to further reduce the size of script libraries. This strips out all blank lines, comments, and initial white space. Typically, 30% to 40% reductions are possible (depending on how well documented your code is!). For ease of debugging, the line number of the compressed code will be shown to the left of the editable code. N.B. On R4 clients, code must be smaller than 32,000 characters for compression to work.

To maintain a copyright notice on public code, use the CopyRight field. Any text entered here will always be included in downloaded script libraries, regardless of whether compression is used.

There are four sets of version control present:


Registering Sites

Active Script Library registers each web page which requires scripts. This allows you to to track script usage, and also to pre-assign a list of scripts which a page will need. Site control also gives you security against unauthorized script usage.

You may add sites in two ways:

N.B. If you choose to have the Automatically Generate Sites option switched off in the Settings document, you must create each Site from within Notes.

If not, you can both dynamically create Site documents or request scripts without Site documents at all (using the &S agent parameter)

Each site has an account and a URL . There's no reason why the account cannot be the same as the URL, but for ease of administration it's usually better to have simple account names, such as HomePage or RegisterPage .

Also, accounts allow you to have multiple script libraries built for the same page. In this case you would have a number of Site documents, each with a different account name, but with the same URL.

Finally, every site has a list of Scripts which should be included in the dynamically built JavaScript library.You do not specify which languages or versions here, simply the names. The language and language version are determined whenever the script library is requested.

Site documents give you two major methods of control as a web developer:

If you frequently use the same routines, specify the Default Scripts in the Settings document. These scripts will be selected whenever a new Site is created, either manually or automatically. Making use of this means that if a new page, previously unregistered, requests a library, it will receive the default code.

Requesting Libraries from Web Pages

To request a script library use the following code, ideally in the <HEADER> of the document:
Tip Depending on your version of Domino, you may be able to dispense with the ?OpenAgent suffix to the URL, so long as you do not need to supply parameters to the agent. If your browsers insist on a .js termination to the URL, then add a dummy parameter, e.g. &Z=.js to the end of the agent URL.

If the script is called without parameters, the DASL agent will look up the referring web page in it's list of Site document URLs. If the Site is registered, a script library will be returned with the code of all the agents specified for that site.

If the site URL is not found, a new Site document will be automatically created in the database, unless you have switched off Automatic Site Generation in the Settings document, in which case a 'no access' error will be returned. The new site document will be given the default list of scripts , as determined in the Settings document.

Additional parameters may also be specified on the agent URL:

&debug Switch on debugging, and return a HTML formatted debugging report rather than a script library.
&X Specify a site account. Required if multiple script libraries are being loaded onto the same page.
&L Specify a specific language. Defaults to JavaScript
&S Ad hoc script request. If no site restrictions are in place, a web page can request any set of scripts without having a pre-defined site document. For multiple scripts, separate out with commas, and use + signs for spaces.
&V Specify a specific language version. Defaults to All. If a script in the version selected cannot be found in the database, the All version will be used instead.
&Alpha Select alpha versions of code, wherever available, and the script build number is higher than equivalent beta or gold code. Where alpha routines not available, gold code will be used.
&Beta As for &alpha, but selecting beta code.

If neither &V or &L are supplied, the best match of language and script for the browser will be made by auto-detecting the browser model and version, and matching this to the available scripts.

If both &V and &L are supplied, then autodetection is switched off and only the scripts which exactly match this language and version will be returned.

If the language is given but not the version, the agent will auto detect the browser and check for scripts matching the versions of that language listed in the Browser document (see below). If none of those match, finally it will look for a script which matches the language and has a language version of All .

Ad Hoc Script Requests

Ad hoc script requests allows script libraries to be generated without either having a Site document pre-defined, or creating a Site document on the fly. Simply list the script packages to be returned using the &S parameter, e.g.

http://www.myserver.com/DomScript.nsf/LoadLibrary?OpenAgent&S=Sniffer,Dialog,Toolbar

A special syntax exsts for requesting a single file, using the && parameter:

http://www.myserver.com/DomScript.nsf/LoadLibrary?OpenAgent&&PortalStyleSheet.xsl

DASL will interpret the file extension as the script language, and search it's script store for a matching name.
Dynamic Javascript

There are two methods of generating dynamic Javascript code (rather than simply dynamically stitching together static JavaScript code into a library): built-in script packages , and generating script from Notes formula language using library compiler directives .

Builtin Script Packages

These internal sets of dynamic JavaScript code can be selected for a site in the same fashion as one of your own script packages. The code itself does not exist in any Script document, but is generated on the fly by Active Script Library when a browser requests a script library. Currently there are two such packages available:

DASL_NotesInternational

This script package exposes the standard Notes class NotesInternational to the browser, using the settings of the current Domino server. These provide an easy, and efficient, way to localize javascript across the world.

Example generated code:
// Domino Active Script Library
// DASL_NotesInternational Package
// Copyright (c) 1999 Rhizomatics
var AMString='AM'
var CurrencyDigits= 2
var CurrencySymbol='&pound;'
var DateSep='/'
var DecimalSep='.'
var IsCurrencySpace = false
var IsCurrencySuffix = false
var IsCurrencyZero = true
var IsDateDMY = true
var IsDateMDY = false
var IsDateYMD = false
var IsDST = true
var IsTime24Hour = true
var PMString='PM'
var ThousandsSep=','
var TimeSep=':'
var TimeZone= 0
var Today='Today'
var Tomorrow='Tomorrow'
var Yesterday='Yesterday'

DASL_ Sniffer

This code contains standard client detection internal variables and uses Autodetect to work out its capabilities.

Variables available in this release are:-

is_major,is_minor
is_opera,is_webtv,
is_nav,is_nav2,is_nav3,is_nav4, is_nav4up, is_nav5, is_nav5up, is_navonly
is_ie, is_ie2, is_ie3, is_ie4, is_ie5, is_ie4up, is_ie5up
is_aol, is_aol2, is_aol3
is_js
is_win, is_win95, is_win16, is_win31, is_win98, is_winnt, is_win32
is_os2
is_mac, is_mac68k, is_macppc
is_sun, is_sun4, is_sun5, is_suni86
is_irix, is_irix5, is_irix6
is_hpux, is_hpux9, is_hpux10
is_aix, is_aix1, is_aix2, is_aix3, is_aix4
is_linux
is_sco
is_unixware
is_mpras
is_reliant
is_dec
is_sinix
is_freebsd
is_bsd
is_unix
is_vms
is_desc
is_frames
is_xml
is_css

Since the code is dynamically generated, it is small and fast. Here's an example of the code returned to a Netscape Navigtor 4.61 browser:
// Domino Active Script Library
// Dynamic JavaScript variables
// Copyright (c) 1999 Rhizomatics
var is_major = 4
var is_minor = 61
var is_opera = false
var is_webtv = false
var is_nav = true
var is_nav2 = false
var is_nav3 = false
var is_nav4 = true
var is_nav4up = true
var is_nav5 = false
var is_nav5up = false
var is_navonly = false
var is_ie = false
var is_ie2 = false
var is_ie3 = false
var is_ie4 = false
var is_ie5 = false
var is_ie4up = false
var is_ie5up = false
var is_aol = false
var is_aol2 = false
var is_aol3 = false
var is_js = 1.3
var is_win = true
var is_win95 = false
var is_win16 = false
var is_win31 = false
var is_win98 = true
var is_winnt = false
var is_win32 = true
var is_os2 = false
var is_mac = false
var is_mac68k = false
var is_macppc = false
var is_sun = false
var is_sun4 = false
var is_sun5 = false
var is_suni86 = false
var is_irix = false
var is_irix5 = false
var is_irix6 = false
var is_hpux = false
var is_hpux9 = false
var is_hpux10 = false
var is_aix = false
var is_aix1 = false
var is_aix2 = false
var is_aix3 = false
var is_aix4 = false
var is_linux = false
var is_sco = false
var is_unixware = false
var is_mpras = false
var is_reliant = false
var is_dec = false
var is_sinix = false
var is_freebsd = false
var is_bsd = false
var is_unix = false
var is_vms = false
var is_desc = 'Netscape Communicator 4.6'
var is_frames = true
var is_xml = false
var is_css = true

Generating Script from Notes formulae

Two special directives can be used to generate script at run-time from Notes formula language. Both of them will handle multi-value or single value Notes values, and have the same rules for construction as the LotusScript 'Evaluate' function:

For example, the following lines in your script code:

#Evaluate @if(@platform="Windows/32";"document.write('Windows Server')";"document.write(Non-Microsoft Server')")
#Assign NotesServer @PlatForm
#Assign ScriptDescription @dbcolumn("";"";"Scripts";1)

will generate these lines of dynamic JavaScript (presuming Domino Active Script Library is running on a Windows 32 server):

document.write('Windows Server')
var NotesServer  = 'Windows/32'
 var ScriptDescription = new Array()
var ScriptDescription[0] = 'Dialog Widget'
var ScriptDescription[1] = 'graph builder'
var ScriptDescription[2] = 'HelloWorld'

Note that multivalue return values are automatically detected and JavaScript arrays built rather than simple variables. For #Evaluate directives, each multiple value is written as a separate line of script.

If you wish to ensure that arrays are always returned, regardless of whether the Notes formula returns a multi-value or single value field, indicate so by putting brackets at the end of the variable name, e.g.

#Assign NotesServer() @PlatForm

will return

var NotesServer  = new Array()
var NotesServer[0] = 'Windows/32'
If there are any errors in the Notes formulae, these will not halt the web agent, but will be reported as comments within the generated code.

Browser Capability Detection

For simpler JavaScript coding, and ease of library loading, it is worthwhile setting up browser capability autodetection. To do so, create Browser documents from the Notes Create menu.

Setting Up

Each Browser document should have a browser model identifier to match on, and optionally a meaningful description of that browser model.

The identifier can either be a precise model, such as MSIE 4.01 , Mozilla/4.65 or a partial identifier to match a variety of sub versions, e.g. MSIE 3 , Opera , Mozilla/4, Lotus-Notes/4.

The library builder will start with the most specific match and work it's way through to the least specific matches, i.e. if you have MSIE 4.02 and MSIE 4, a MSIE 4.01 browser would match to MSIE 4, but a MSIE 4.02 would always be detected as exactly a MSIE4.02.
Tip. As a catch-all, create a browser document and leave the identifier blank.

For a full list of every known browser, including worms and other bots, download a current BROWSCAP.INI file. The best maintained version is available from http://www.cyscape.com/

The next stage in registering a browser is to declare whether it is scriptable . If not, the library building will be immediately terminated. Optionally, you can also specify its capabilities for XML , CSS and Frames .

If it is a scriptable browser, next list the script languages and language versions of which it is capable (and of which you wish to make use). Do this in order of preference. So for example, a MSIE 5 document might have JavaScript 1.3 as the preferred language/version, with JavaScript 1.2 next and so on.

Finally, specify a fall-back language and version , to be used if there are no versions of the scripts in the database for any of the preferred script languages. Usually the fallback version will be All .


Operation

The library builder will look for versions of each script package in the order specified in the appropriate browser document, and use the best one it can find. If it exhausts the preferred languages, it will hunt for a script using the default version. If even that cannot be found, the script will not be included in the library.

If a language has been supplied (using &L parameter) but no version, the library build agent will restrict it's matching to that language alone. If the default language set in the Browser document does not match the supplied language, then the default version will be set to All .
Example
If the browser is MSIE 5 and the agent is called with &L=JScript, the agent will search for the highest version of JScript supported by MSIE 5, and ignore all JavaScript packages.

If it cannot find any of the listed JScript versions, it will finally look for a script with version All.
HTTP Header Control

The HTTP header precedes every web page sent by a web server, and contains the most powerful controls available to you over how your pages are treated by remote browsers and proxy caches.

META tags in HTML headers are only respected by certain web browsers, and will generally be ignored by proxy and in-line caches. HTTP headers allow you much more precise control, including the ability to separately indicate how proxy and browser caches should handle your pages.
Sample HTTP Header
HTTP/1.1 200 OK
Server: Lotus-Domino/Release-4.6.7(Intl)
Date: Mon, 29 May 2000 12:44:09 GMT
Content-Type: text/plain
Content-Length: 218
Content-Type:text/html
Expires: Mon, 29 May 2000 12:44:39 GMT
Last-Modified: Mon, 29 May 2000 12:44:09 GMT
Cache-Control: smax-age=60, proxy-revalidate, no-cache
ETag: "943B30C845D25B52802568EE003DD680"
Connection: Close

The HTTP cache expiry counts in seconds how long the page should live in such a cache before being refreshed. DASL will automatically generate an Expires header (HTTP 1.0 compatible) and a max-age setting (HTTP 1.1 only). In addition, it allows you to specify a separate expiry for proxy caches (which generates a smax-age setting) and will always include a Last-Modified date, which enables proxies and browser caches to make better cache decisions.

Additionally, you can discriminate between public caches (such as that of a corporations proxy server, or an in-line cache used by an ISP) and private caches on the browser or mobile device. The private keyword selected in Cache Control specifies that the expiry period applies only to private caches, rather than public ones.

Of the other cache control keywords available, no-store switches off all caching and no-cache is the equivalent of setting the expiry to zero seconds, i.e. the image will still be cached, but will expire immediately.

The reason for separately controlling public and private caches is that some web material times out for everyone (like today's news), whereas other personalized content times out for individual users. If you wish to ensure that every hit to your page gets a fresh script build, then select no-store . If you want to have freshened script pakages, but don't want to supply new scripts quite that often, tune the timings for the expiry counter.

A new addition to HTTP 1.1 is the ETag - this allows down-stream browsers and caches to be object-aware; it is possible using ETags to discriminate between multiple scripts sent using the same HTML address. When switched on, DASL will generate an ETag using the Universal ID of the Site document, together with the browser model and script version; if no site is registered, the requested script list will be used in place of the Universal ID. This ETag will assist intelligent cacheing of particular packages of scripts for individual sites and browsers. Another HTTP 1.1 addition is Connection Control - DASL allows you to close this, to prevent an expectation of a persistent connection.

HTTP Headers are not visible from web browsers, even when using the "View Source" option - this will show only the HTML header. A useful tool for viewing both types of header is gethttp.exe , also supplied by Rhizomatics .

N.B. The cache control offered by Domino Active Script Library is far in advance of what is available from the Domino server itself (which is often criticized by webmasters for its poor caching support).

Further information
Page Testing Service http://www.mnot.net/cacheability/
Tutorial http://www.mnot.net/cache_docs/
Cache Friendly Design http://www.casheflow.com/friendly/cflow-friendly.html
Caching News http://www.web-caching.com/
Mobile Device Caching http://avantgo.com/builder/caching.html
FAQ

What does it cost?

Nothing. Rhizomatics reserve the right to charge for any future enhanced version, if this system one day evolves into a complete development control system. Whether or not that happens, you may continue to use this current database for the rest of your Domino-using life. If you really feel appreciative, then a little acknowledgement with a link back to us would be sweet.

What version of Domino does it require?

It has been developed for v4.6, but should work happily with v4.5 thru v5. All coding is in LotusScript, so there are no restrictions on which server platform is used.

How does the web agent choose which scripts to include?

From the browser detection, the script builder should know what the client browser is, and what the preferred, secondary and default script languages are. It will also know from the agent parameters if beta or alpha code is to be included in the search.

First step is to search for the best code matching the browser preferred script language, e.g. JavaScript 1.3. If that can't be found, it will work through the secondary preferences, and if none of those can match, will try the default preference, usually simply 'JavaScript'.

In each of those matches, the script builder agent will query for the set of scripts which match the script name, language and language version. If the &Alpha or &Beta switches were set on the agent call, alpha and beta code will be included in the query set; otherwise it will be restricted to gold code only.

Once the set of possible scripts is returned, the web agent checks through them for the best match with the browser, and within that, for the highest script version number. So for example, for a MSIE v5 browser, it will pick the 'MSIE 5' code in preference to 'MSIE' or a generic script. If there are several scripts with the same name and langauge for 'MSIE 5', it will choose the highest script version number. It would not choose the script with the higher version number if it was specifically for Netscape.

This process seems long to a human, but the agent can do it in microseconds. Internal caching improves results, and you can maximize performance further by ensuring that all the older versions of scripts you no longer need are marked as Obsolete.


Why aren't the LSS files for the script libraries included in the ZIP distribution?

Domino Active Script Library is currently distributed free for use in any situation. However, it makes use of techniques and code which are the commercial property of Rhizomatics and is reserved for future products. Release of source code will, be granted for co-development work, or for security/audit purposes.

Note, these source code files are not required for the operation of Domino Media Script Library . The only effect is that you cannot edit the web agent itself; however, all other agents, views, forms and other elements are totally unlocked and available for your inspection or modification. This structure also minimizes script library size and boosts agent performance.

Where can I find out more about script language/browser compatibility?

Try the following recommended articles:

http://www.ne-dev.com/netscapeworld/nw-08-1997/nw-08-crossbrowser.t.html
http://www.infohiway.com/javascript/detectwars.htm
http://www.cyscape.com/developer/workshop/

Updates

For updates to this product, check:-

http://www.rhizomatics.demon.co.uk/software/

Disclaimer

LIMITED WARRANTY


COPYRIGHT AND LICENSE


Acknowledgements
----------------

Domino is a registered trademark of Lotus, a subsidiary of IBM
GIF is a registered trademark of CompuServe and UniSys