Docs/trephine.js

From Trephine

When loaded, the trephine.js script creates a singleton Object called trephine which is used to communicate with the applet. Of course, one could load the applet directly into the HTML page, but using this script makes it easier, more dynamic and more robust.

Tip: See Getting started for instructions on how to load the script.

properties

loaded

The loaded property tells you whether the applet has been successfully loaded.

Prior to the first call to trephine.load(), this will always be false. If the load call fails for some reason, then loaded will remain false.

Example

if (trephine.loaded) { /* ... */ } else { /* ... */ }

methods

load

Calling this method triggers trephine to attempt to load the applet.

Syntax

trephine.load([options]);

Arguments

1. options - (object, optional)

Options

• force - (boolean, default: false) Whether to force loading, disregarding the value of this.loaded.
• jars - (array, default: []) List of URLs of additional jars to load. Relative URLs will have the root value prepended.
• root - (string, default: "http://trephine.s3.amazonaws.com/") Base url for resolving relative jar URLs.
• debug - (boolean, default: false) Whether to display debugging information to the Java console (invaluable during testing).
• engines - (array, default: []) List of script engines to pre-load as soon as the user has granted permissions. Example: ['js', 'jruby'] (pre-loads the JavaScript and JRuby engines)
• onload - (function, default: null) Function to call after the applet has successfully loaded.
• onerror - (function, default: null) Function to call if the applet failed to load (usually means the client does not have Java).

Example

trephine.load({
  debug: true,
  force: true,
  jars: [ "jruby-engine.jar", "jruby-complete-1.1.4.jar" ],
  engines: [ "jruby" ],
  onload: function() {
    /* code here */
  },
  onerror: function() {
    /* code here */
  }
});

exec

Executes a given piece of code using the specified engine (language).

Syntax

trephine.exec(engine, code);

Arguments

1. engine - (string) The script engine to use when executing the code (the language)
2. code - (string) The code to execute

Examples

trephine.exec('js', 'var print = java.lang.System.println; print("howdy");');
trephine.exec('jruby', 'puts "howdy"');

askPermission

Once the applet has been loaded, use askPermission to prompt the user to grant additional privileges to scripts on this page.

Syntax

trephine.askPermission([callback]);

Arguments

1. callback - (function, optional) A function to execute after a user response has been received. (The user's boolean response is passed as the only argument to this function).

Examples

trephine.askPermission( function(result) {
  if (result) alert("Thanks for enabling trephine's features");
  else alert("Sorry, without elevated privileges, this webapp is basically useless. :/");
});

hasPermission

Simply checks whether the user has granted additional permissions or not.

Syntax

trephine.hasPermission();

Example

if (!trephine.hasPermission()) trephine.askPermission(); // When at first you don't succeed...

isPrivileged

Checks whether the applet is running in privileged mode itself. If this method returns false, no other method calls (such as trephine.exec) can be expected to succeed.

A false return value from isPrivileged means either that the trephine.jar file was not properly signed, or the user disallowed privileged execution when initially prompted.

Syntax

trephine.isPrivileged();

isDebugEnabled

Used to determine whether the applet has debug logging enabled.

Syntax

trephine.isDebugEnabled();

enableDebug

Used to enable debug logging in the applet.

Syntax

trephine.enableDebug();

version

Returns a version string.

Syntax

trephine.version();

toJSON

Encodes a given value as a JSON string.

Syntax

trephine.toJSON(value);

Arguments

1. value - (mixed) The value to encode

Examples

trephine.toJSON( new Date() ); // returns "2009-02-11T04:11:30Z"
trephine.toJSON( { a : 'b' } ); // returns {"a":"b"}
trephine.toJSON( [ 1, 2, 3, 4 ] ); // returns [1,2,3,4]