mozdev.org

• Monday May 12th 2008
• Do you want fries with that project?

Skip to Content

JSLib

Page Updated: June 16, 2005 Latest Version: 0.1.359

	Debug | Install | File I/O | RDF | Network | Sound | Utils | XUL | Zip
	Home | Mailing List | Install | Source Code | Downloads | Bugs | docs | clients

JSLib User Manual

• Introduction
• Where JSLib is installed on your system
• Using JSLIb in your application
• Using JSLIb in xpcshell
• Module Idenifiers
• Installing jslib w/ your application
• JSLib samples
• Turning SDTOUT Dump On and Off
• XPCOM Methods
• Using jsLib from a local "file://"

Introduction

JSLib is an evolving project still currently under development. It has one simple goal:

"Make life easier for Mozilla Application Development by creating logical, easy to use API's for general purpose routines that lend themselves to living in library code."

The JSLib javascript library wraps Mozilla's scriptable xpcom interfaces with easy to use methods. The sole purpose of the library is for applications based on the Mozilla application framework. So as a Mozilla author, you install jslib with your application as a dependency and then use the libraries in your application logic just as you would libraries in other languages.

The most complete module in this library is the I/O module. But development is continuous and there are many other valuable modules currently available for MAD authors to use. These are modules that implement date, prefs settings, windows, and dialogs, sound, etc. Each modules function list is documented independently.

The current module groups are:

  debug
  install
  io
  network 
  rdf 
  samples
  sound
  utils 
  xbl 
  xul
  zip

JSLib is reasonably small in file size about 100K and new builds are posted often. So as you develop your Mozilla application, it is a good idea to always install the latest version of jslib.

Where JSLib is installed on your system

JSLib is usually installed into your Mozilla global chrome dir if it has permission to do so, otherwise it will fall back and install in your user profile folder. This is to avoid any permission problems that may come from a shared system wide installation of mozilla. The Mozilla profile directories reside in different locations on defferent systems. For example:

Linux/Unix Systems

  ~/.mozilla/profile_name/generated.slt/chrome

On my system it is:

  /home/petejc/.mozilla/default/m84bwsx3.slt/chrome/

Windows Systems

  c:\WINDOWS\Application Data\Mozilla\Profiles\default\generated.slt\chrome\

Mac Classic Systems

  I forget need to double check

Mac OSX systems

  /Users/uname/Library/Application Support/Firefox/Profiles/default.dcc/extensions/ 

JSLib installs one of two ways depending on the package you choose to install. The two current distribtions are:

  jar file - Best for production installs

  eg:
    ~/.mozilla/profile_name/generated.slt/chrome/jslib.jar

  normal directory/file archive - Best for a development environment  

  eg:
    ~/.mozilla/profile_name/generated.slt/chrome/jslib/

Using JSLIb in your application

To use from a xul page, just paste in the code below:

<script type="application/x-javascript" src="chrome://jslib/content/jslib.js" />

This loads the required jslib.js root library file. This is only a minimal amount of code. This must be placed on the top of any other scripts used in your application document.

A sample xul page:

<?xml version="1.0"?> <!DOCTYPE window> <window id="jslib-test" style="background-color: #cccccc; width: 100px; height: 100px;" xmlns:html="http://www.w3.org/1999/xhtml" xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

<script type="application/x-javascript" src="chrome://jslib/content/jslib.js" />

<vbox flex="1" pack="center"> <spacer flex="1" /> <button label="test" oncommand="alert(JS_LIB_VERSION);" /> <spacer flex="1" /> </vbox> </window>

After you reference the root script above, you can now include a library module using the include method:

// to include the i/o file module include ('chrome://jslib/content/io/file.js'); Or a shortcut using the module identifier: // file module identifier include (jslib_file); Or to use the entire io suite, do this: // to include all the i/o modules include ('chrome://jslib/content/io/io.js'); Or a shortcut using the i/o module identifier: // i/o module identifier include (jslib_io); A sample xul page using the file module: <?xml version="1.0"?> <!DOCTYPE window> <window id="jslib-file-test" style="background-color: #cccccc; width: 100px; height: 100px;" xmlns:html="http://www.w3.org/1999/xhtml" xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

<script type="application/x-javascript" src="chrome://jslib/content/jslib.js" />;

<script type="application/x-javascript"> include (jslib_file); // a local file path var localFile = "/tmp/fubar.dat"; var f = new File(localFile); </script> <vbox flex="1" pack="center"> <spacer flex="1" /> <button label="Function List" oncommand="alert(f.help);" /> <button label="exists" oncommand="alert(f.exists());" /> <button label="create file" oncommand="if (!f.exists()) f.create();" /> <spacer flex="1" /> </vbox> </window>

Using JSLib in xpcshell

To use jslib from xpcshell for testing, you will need to get the local path of your current profile. For example mine on unix is: /home/petejc/.mozilla/Default\ User/cmxiog2c.slt/chrome/jslib/jslib.js So then i run xpcshell like this: ./run-mozilla.sh xpcshell My profile on windows is: C:\WINDOWS\Application Data\Mozilla\Profiles\default\0tjdfpk2.slt\chrome\jslib // remember to use double '\\' on windows paths var myProfileWindows="C:\\WINDOWS\\Application Data\\Mozilla\\Profiles\\default\\0tjdfpk2.slt\\chrome\\jslib"; I load xpcshell like this from the mozilla bin dir: xpcshell.exe js> // an xpcshell session on unix js> var myProfile="/home/petejc/.mozilla/Default\ User/cmxiog2c.slt/chrome/jslib/jslib.js"; js> load (myProfile); *** Chrome Registration of package: Checking for contents.rdf at resource:/chrome/jslib/ ********************* JSLIB DEBUG IS ON ********************* js> include (jslib_file); js> var f=new File ('/tmp/foo'); js> f.exists(); true js> f.open(); true js> f.read(); this is line #1 this is line #2 js> f.close(); true js> f.open("a"); true js> f.write('this is line #3\n'); true js> f.close(); true js> f.open(); true js> f.read(); this is line #1 this is line #2 this is line #3 js> f.close(); true js>

Module Identifiers

The curent jslib module identifiers to use when including library modules are:

// io library modules
jslib_io        
jslib_filesystem 
jslib_file    
jslib_fileutils 
jslib_dir    
jslib_dirutils
                                                                                                               
// xul dom library modules
jslib_dialog
jslib_window
jslib_routines
                                                                                                               
// sound library modules
jslib_sound
                                                                                                               
// utils library modules
jslib_date
jslib_prefs

Example xpcshell session using the date module identifier: js> include (jslib_date); *** load: date.js OK js> date(); 28.04.2003 - 10:28:48 js> date("l"); Monday js> date ("l dS of F Y h:i:s A"); Monday 28th of April 2003 10:30:00 AM js> quit();

Installing jslib w/ your application

The sample code below is for a mozdev project where your xpi file is located in /downloads/xpi/. Your xpi file name is called myproject.xpi. You will need to modify this sample to suite your specific needs.

Here is some sample code you can paste in your application html install page:

<script language="javascript"> <!-- // my project xpi const JAR_XPI="http://downloads.mozdev.org/myproject/myproject.xpi"; // jslib dependency const JAR_JSLIB="http://www.mozdevgroup.com/dropbox/jslib/signed/jslib_current_global_lite_signed.xpi"; // create xpi target object - this example uses 2 xpi packages var target = {'jslib production build' : JAR_JSLIB, 'MyXPI production build' : JAR_XPI}; function install () { if (typeof(InstallTrigger) != "object") return upgradeMessage(); InstallTrigger.install(target); } function upgradeMessage (aMsg) { alert("installation requires a Mozilla based browser"); } //--> </script> <a href="#" onclick="install();">myproject jar</a>

JSLib Samples

The sample code above can be found in /jslib/content/libraries/samples

To see the samples in action just launch jslib as shown below.

Launching jslib from a shell or command prompt.

Linux/Unix/OSX

  # from mozilla bin dir
  ./mozilla -chrome chrome://jslib/content/samples/test.xul

Windows

  # from mozilla bin dir
  mozilla.exe -chrome chrome://jslib/content/samples/test.xul

Turning Dump On and Off

If you are using a non-debug version of Mozilla and want to see debug output from methods such as jslibDebug(), jslibPrint, or dump(), you can use jslib_turnDumpOn() and jslib_turnDumpOff. These methods will on the fly turn dump on or off.

eg:

  // to turn dump on
  jslib_turnDumpOn();
  jslibDebug("Hello, this is my debug message") 
  jslibPrint("Hello, this is my print message") 

  // to now turn dump off
  jslib_turnDumpOff();

XPCOM Methods

JSLib provides some useful methods to easily instantiate xpconnect wrapped xpcom classes. The methods are jslibCreateInstance(), jslibGetService, and jslibQI().

eg:

  // create an nsIFile instance
  var obj = jslibCreateInstance("@mozilla.org/file/local;1", "nsIFile");
  jslibPrint(obj);

  // QI class for nsILocalFile
  obj = jslibQI(obj, "nsILocalFile");
  jslibPrint(obj);

  // get nsIWindowMediator service
  var wm = jslibGetService("@mozilla.org/appshell/window-mediator;1",
                           "nsIWindowMediator");
  jslibPrint(wm);

Using jsLib from a local "file://"

To use jsLib from a local file. you need to set two user_prefs in your "prefs.js" file.

 pref("capability.principal.codebase.p0.granted", "UniversalXPConnect");
 pref("capability.principal.codebase.p0.id", "file:///"); 

then you should be able to run jslib out of the box from a local ".xul" file.

  eg:  ./mozilla file:///tmp/file.xul