Spark: px Framework

px Framework

Overview

Spark uses the px Framework to import the versioned UI API to use for an application. The px Framework disables the nodejs require keyword and instead provides px.import as an asynchronous loading mechanism for including modules in applications.

In addition, the px Framework provides built-in variables and functions for commonly used functionality. Please see this page for details of these built-ins.

px.import

px.import is used to include modules, jars, and individual JavaScript files into a JavaScript page. It is similar to the Nodejs "require" function, with some available enhancements. Unlike require, px.import is asynchronous.

px.import can include one to many modules in a single call and returns a promise when all imported source is ready for use.

Limitations

Only the following Nodejs modules are allowed for import:

crypto (as of Release 0.41)
htmlparser
http - restricted to client functionality
https - restricted to client functionality
http2 (as of Release 0.41) - restricted to client functionality
url
~~net - restricted to client functionality~~ deprecated as of Release 0.40
oauth (as of Release 0.41)
querystring
ws - restricted to client functionality

px Prefix

When used in px.import, the px: prefix has special meaning and references javascript built into Spark.

px:scene: import version of Spark scene graph objects
px:tools: import file from builtin tools here: tools in github

Usage

Import a single javascript file


// import the scene object, version 1
px.import("px:scene.1.js").then( function ready(scene) {
  var root = scene.root;
  .
  .
  .
  }).catch( function importFailed(err){
  console.error("Imports failed for myexample.js: " + err)
});

Import multiple items


// import the scene object, version 1,
// import the built-in keycode constants [need reference],
// import the Nodejs url module
px.import({ scene: 'px:scene.1.js',
              keys: 'px:tools.keys.js',
              url: 'url' }).then( function importsAreReady(imports) {
  var scene = imports.scene;
  var keys = imports.keys;
  var url = imports.url;
  var root = imports.scene.root;
  .
  .
  .
  }).catch( function importFailed(err){
  console.error("Imports failed for myexample.js: " + err)
});

px.configImport

px.configImport can be used to name a common frameworks location, then that name can be used within px.import.

Usage


px.configImport({"pxFramework:":"http://www.pxscene.org/someFrameworks/widgets/"});

px.import({ scene: 'px:scene.1.js',
           image: 'pxFramework:ImageAnimator.js'
}).then( function importsAreReady(imports)

var root = scene.root;
var image = image.ImageAnimator;
.
.
.
}).catch( function importFailed(err){
console.error("Imports failed for myexample.js: " + err)
});

px.appQueryParams

px.appQueryParams: can be used to retrieve query parameter values passed on the launch url

                    
  px.appQueryParams.<parameterName>;

... where <parameterName> is the name of a parameter that was passed in. This will return an undefined javascript object if a parameter with that name was not specified.

px.getPackageBaseFilePath

px.getPackageBaseFilePath(): function which returns the root URL path of entry JavaScript file or archive

  var basePackageUri = px.getPackageBaseFilePath();
 
  var fontMed = scene.create({t: "fontResource", url: basePackageUri + "/myFont.ttf");

px.getBaseFilePath

px.getBaseFilePath(): function which returns the root URL path of the current JavaScript file, even if it is pulled in via px.import.

Availability: Spark 1.2.0.0 and later.

px.getModuleFile

px.getModuleFile(fileName): function that returns a promise for the contents of a file in current module's archive or path

  var fileLoadPromise = px.getModuleFile(imagesFileName);
  fileLoadPromise.then(function(data) {
    // do processing
    // where 'data' is the contents of the 'imagesFileName' file
  }

This function can be useful for loading JSON or other data for an application.

px.getFile

px.getFile(fileUrl): function that returns a promise for the contents of a file downloaded from fileUrl. Note that permissions will be enforced for the fileUrl, such that the application must have permission to access the protocol and origin of fileUrl.

  var fileLoadPromise = px.getFile(imagesUrl);
  fileLoadPromise.then(function(data) {
    // do processing
    // where 'data' is the contents of the 'imagesUrl' file
  }

This function can be useful for loading JSON or other data for an application.

px.log

px.log: original low level debugging

px Delegates

Delegates are customization points that permit a JavaScript program running in Spark to optionally change the default behavior of the Spark core framework.

Currently the following delegate patterns are supported...

Clearscreen: A given Spark JavaScript app can choose to "decline" the default clear screen (to BLACK) by implementing the delegate method below.

                      
      // Delegate for Clearscreen
      module.exports.wantsClearscreen = function()
      {
          return false;
      };