jspkg API

THIS DOCUMENTATION IS A WORK-IN-PROGRESS AND MAY BE OUT-OF-DATE OR INCORRECT.

Calling Convention

All jspkg function calls are prefixed with org.jspkg.API1 to allow for future API expansion/changes.

Package Patterns

Package patterns are used by the various import functions and package loader definitions to specify a set of packages to import. The package patterns may contain the wildcards * or **, representing a segment of the package name or zero or more segments of the package name, respectively. Wildcards may only appear at the end of a package pattern.

The pattern org.jspkg.* would only match packages that started with org.jspkg and contained anything in the third segment, such as org.jspkg.package1 or org.jspkg.package2. The pattern org.jspkg.** would match any package starting with org.jspkg, including the packages org.jspkg, org.jspkg.package and org.jspkg.sub.package.

Import/Using Functions

These functions control when and how packages are loaded by the engine.

loadPackage

Triggers the load of a given package. The package will be loaded asynchronously.

// Loads the package com.example.mypackage
org.jspkg.API1.loadPackage( "com.example.mypackage" );

importPackages

Triggers the import of a packages matching a pattern into the given scope. Only packages that have been loaded and activated (by being required by another package or script) are imported.

// Imports all the loaded packages from com.example.test
org.jspkg.API1.importPackages( { 
	scope: window, 
	pattern: "com.example.test.**" } );

// Imports only the com.example.otherpackage package
org.jspkg.API1.importPackages( { 
	scope: window, 
	pattern: "com.example.otherpackage" } );

packageApply

Runs a function with the given package's exports as the current this context.

// Applies the given function on the com.example.mypackage package
org.jspkg.API1.packageApply( { 
	package: "com.example.mypackage", 
	func: function() {
		alert(this.MyPackageExport);
	}
} );

Initial Import Functions

These functions are used to set the global package requirements for the HTML page itself.

initializeInitialPackages

Triggers the load and import of the initial packages. If this method is called in the HEAD section of an HTML page, the scripts will be loaded before scripts in the body are processed. Symbols from any imported packages will be available in the global Javascript context (ie: the window context in HTML).


org.jspkg.API1.initializeInitialPackages( {
	using: [ "my.package.p1", "my.package.p2", 
		"com.example.otherpackage" ],
	imports: [ "my.package.*" ] } );

Script/Packing Loading Functions

These functions affect and control loading of scripts.

assignPackageLoader

Assigns a package loader with the given parameters to load packages that match the provided pattern.

// Assigns the loader com.example.myserversideloader to
// all com.example packages.
org.jspkg.API1.assignPackageLoader( { 
	type: "com.example.myserversideloader", 
	pattern: "com.example.**", 
	params: { url: "myscript.php?script=%replace%" } } );

setScriptLoader

loadScript

Definition Functions

These functions are used to define packages and scripts.

The script or package body is passed a package object as the first parameter to its init function that can be used to interrogate the packaging system.

definePackage

Defines a package with the given name.

// Defines the com.example.mypackage package
org.jspkg.API1.definePackage({ 
	name: "com.example.mypackage", 
	namespace: "com.example", 
	using: [ "com.example.myotherpackage" ],
	imports: [ "**" ],
	init: function(pkg) {
		eval(pkg.getInitializer());
		this.MyPackageExport 
			= "exported from com.example.mypackage!";
}});

defineScript

Defines a script that executes when all of its dependencies are available.

// Defines a script that uses com.example.myotherpackage
org.jspkg.API1.defineScript({ 
	name: "My test script", 
	using: [ "com.example.myotherpackage" ],
	imports: [ "**" ],
	init: function(pkg) {
		eval(pkg.getInitializer());
		alert("Running!");
}});