Namespace baja

the core BajaScript namespace.
Defined in: sys.js.

Namespace Summary
Constructor Attributes	Constructor Name and Description
	baja

Field Summary
Field Attributes	Field Name and Description
<static>	baja.Double
<private> <static>	baja.printError Print out the error to the specified line printer function.
<static>	baja.station Shortcut to local Station Component Space
<static>	baja.version BajaScript's version number (maj.min.build.patch).

Method Summary
Method Attributes	Method Name and Description
<static>	baja.$(typeSpec) Return an instance from the Type.
<static>	baja.clearOut() Attempt to clear BajaScript's debug output.
<private> <static>	baja.def(val, defVal) Define a default value for possibly undefined variables.
<static>	baja.error(e) Print an error message in BajaScript's debug output.
<static>	baja.fail(err) The global default fail callback function.
<static>	baja.getLanguage() Returns language code for the user.
<static>	baja.getTimeFormatPattern() Return the user's default time format pattern.
<static>	baja.getUserHome() Return the user home.
<static>	baja.getUserName() Returns the user name the user is currently logged in with.
<static>	baja.hasType(obj, type) Test an Object to see if it's a Baja Object and has the 'getType' function.
<static>	baja.importTypes(obj) Load the Type and Contract information for the given TypeSpecs.
<private> <static>	baja.initFromSysProps(props) Initialize BajaScript from System Properties.
<static>	baja.isLogClientErrorsInServer() Return true if any client Errors are also being logged in the Server.
<static>	baja.isStarted() Return true if BajaScript has started.
<static>	baja.isStopped() Return true if BajaScript has stopped.
<static>	baja.isStopping() Return true if BajaScript has stopped or is in the process of stopping.
<static>	baja.iterate() A iteration general utility method that performs the given function on every JavaScript property in the given cursor or Javascript array.
<static>	baja.lex(obj) Returns a Lexicon Object for a given module.
<static>	baja.lt(typeSpec, encodeContracts) Loads and returns a Type.
<static>	baja.noop() A function that does nothing (noop = no-operation).
<private> <static>	baja.objectify(obj, propName) This is a conveniance method used for working with functions that take an Object Literal as an argument.
<static>	baja.ok() The global default ok callback function.
<static>	baja.outln(msg) Print a message to BajaScript's debug output followed by a newline.
<static>	baja.preStop(func) Add a function to be invoked just before BajaScript is stopped.
<static>	baja.runAsync(fn) Run the specified Function asynchronously.
<static>	baja.save() Save BajaScript's Registry Storage.
<static>	baja.start(obj) Start BajaScript.
<static>	baja.started(func) Add a function to be invoked once BajaScript has started.
<static>	baja.stop(obj) Stop BajaScript.
<private> <static>	baja.strictAllArgs(args, ctors) Strict Arguments Check.
<private> <static>	baja.strictArg(arg, ctor, errMsg) Strict Argument Check.
<static>	baja.throttle(func, obj) A general utility method that tries to prevents a function from running more often than the specified interval.

Namespace Detail

baja

Field Detail

<static> baja.Double

Defined in: obj.js.

<private> <static> baja.printError

Print out the error to the specified line printer function. This gets called by the default error handler.

See:: baja.error

<static> baja.station

Shortcut to local Station Component Space
Defined in: ord.js.

See:: baja.nav.localhost.station

<static> baja.version

BajaScript's version number (maj.min.build.patch).

Method Detail

<static> baja.$(typeSpec)

Return an instance from the Type.

When creating an instance of a Type, this method should always be used by preference...

  // Create an instance of a NumericWritable Control Component...
  var v = baja.$("control:NumericWritable");

At first this 'dollar' function looks a bit strange. However, much like other popular JavaScript libraries, this function has been reserved for the most commonly used part of BajaScript; creating instances of BajaScript Objects.

Parameters:
{String} typeSpec: the Type Specification.

Returns:: an instance from the Type

See:: Type#getInstance

<static> baja.clearOut()

Attempt to clear BajaScript's debug output.

Returns:: baja

<private> <static> baja.def(val, defVal)

Define a default value for possibly undefined variables.

Parameters:
val: the value to be tested.
defVal: the default value to be returned if the value is undefined.

Returns:: the default value if the value is undefined.

<static> baja.error(e)

Print an error message in BajaScript's debug output. In IE/Safari the length of the stack trace will be limited to 20 records - you can change this by setting baja.stackTraceLimit.

By default, this method calls baja.printError using baja.outln as the printer function.

Parameters:
e: the error to output.

Returns:: baja

<static> baja.fail(err)

The global default fail callback function.

Throughout BajaScript there are places where network calls may be made. In one of these cases, a developer has the option of specifying a 'fail' callback. If the fail callback isn't specifed by the developer, it will default back to this function.

Parameters:
err

See:: baja.ok

<static> {String} baja.getLanguage()

Returns language code for the user.

Returns:: {String} the language character code.

<static> {String} baja.getTimeFormatPattern()

Return the user's default time format pattern.

Returns:: {String}

<static> {baja.Ord} baja.getUserHome()

Return the user home.

Returns:: {baja.Ord}

<static> {String} baja.getUserName()

Returns the user name the user is currently logged in with.

Returns:: {String} the user name.

<static> {Boolean} baja.hasType(obj, type)

Test an Object to see if it's a Baja Object and has the 'getType' function.

Please note: this test excludes objects that may extend baja.Slot.

Parameters:
{Object} obj: the Object to be tested.
{String} type Optional: the type or (String type specification - module:typeName) to test object against. Please note, Type.is(...) is used and not equals.

Returns:: {Boolean} true if the given Object is a proper BajaScript Object

<static> {Array} baja.importTypes(obj)

Load the Type and Contract information for the given TypeSpecs.

A TypeSpec is a String in the format of 'moduleName:typeName' in Niagara.

This method may perform a network call if one of the TypeSpecs can't be found locally in the Registry or if a Contract needs to be retrieved.

If a network call is expected, it's recommended to pass in ok and fail callback functions that will load the Type information asynchronously.

If a number of network calls is expected to be made then a batch baja.comms.Batch object can be passed into this method along with a callback. The network call will then be 'batched' accordingly.

The method can be invoked with an array of TypeSpecs or an Object Literal...

  baja.importTypes(["control:NumericWritable", "control:BooleanWritable"]);

  // ...or via an Object Literal to specify further options...

  baja.importTypes({
    typeSpecs: [["control:NumericWritable", "control:BooleanWritable"]],
    ok: function (newlyAddedTypes) {
      // Called on success (if specified, network call will be asynchronous otherwise synchronous)
    },
    fail: function (err) {
      // Called on failure (optional)
    },
    batch: batch // If specified, network calls are batched into this object
  });

If the types for a given Web Application are known upfront then please specify them in baja#start instead.

Parameters:
{Object} obj: the Object Literal for the method's arguments.
{Function} obj.ok Optional: the ok callback. By defining this, the network call automatically becomes asynchronous. An array of the newly added Types will be passed into this handler.
{Function} obj.fail Optional: the fail callback.
{baja.comm.Batch} obj.batch Optional: the batch Buffer. If defined, any network calls will be batched into this object.

Returns:: {Array} an array of Types if this method is invoked synchronously otherwise null.

See:: baja.start

<private> <static> baja.initFromSysProps(props)

Initialize BajaScript from System Properties.

Parameters:
{Object} props: System Properties loaded from Server.

<static> {Boolean} baja.isLogClientErrorsInServer()

Return true if any client Errors are also being logged in the Server.

Please note, since BOX and HTTP Errors are technically from the Server, these do not constitute as client Errors.

Returns:: {Boolean}

<static> {Boolean} baja.isStarted()

Return true if BajaScript has started.

Returns:: {Boolean} started

<static> {Boolean} baja.isStopped()

Return true if BajaScript has stopped.

Returns:: {Boolean} stopped

<static> {Boolean} baja.isStopping()

Return true if BajaScript has stopped or is in the process of stopping.

Returns:: {Boolean} stopping

<static> baja.iterate()

A iteration general utility method that performs the given function on every JavaScript property in the given cursor or Javascript array. This function can be called with a variety of parameter configurations.

baja.iterate(array, function (arrayElement, arrayIndex))

baja.iterate(array, startIndex, function (arrayElement, arrayIndex))

baja.iterate(array, startIndex, endIndex, function (arrayElement, arrayIndex))

baja.iterate(numberOfTimesToIterate, function (index))

baja.iterate(iterationStartIndex, iterationEndIndex, function (index))

baja.iterate(object, function (objectJsProperty, objectJsPropertyName))

baja.iterate(object, function doIterate(object), function getNext(object))

iterate() is compatible with arrays, but not with arguments objects - pass in Array.prototype.slice.call(arguments) instead.

In the last case with the doIterate and getNext functions, doIterate performs the iterative action on the object, and getNext returns the next object to iterate (this will be passed directly back into doIterate). This is handy for walking up prototype chains, supertype chains, component hierarchies, etc.

In all cases, if the function being executed ever returns a value other than undefined, iteration will be stopped at that point and iterate() will return that value.

For invocations of iterate() that include start or end indexes, note that start indexes are inclusive and end indexes are exclusive (e.g. iterate(2, 5, function (i) { baja.outln(i); }) would print 2,3,4).

Returns:: any non-undefined value that's returned from any function or Cursor.

<static> {Object} baja.lex(obj)

Returns a Lexicon Object for a given module. The locale will be whatever the current user is set too.

Please note, if BajaScript has Web Storage enabled, the Lexicon will be permanently cached.

If the Lexicon for the given module isn't loaded then a network call will be made.

  // Get a value from a Lexicon. A synchronous network call will be made if the Lexicon
  // isn't available locally.
  baja.lex("bajaui").get("dialog.ok");

  // Get a value from a Lexicon. An asynchronous network call will be made if the Lexicon
  // isn't available locally.
  baja.lex({
    module: "bajaui",
    ok: function (lex) {
      lex.get("dialog.ok");
    }
  });

Parameters:
obj

Returns:: {Object}

See:: Lexicon

<static> {Type} baja.lt(typeSpec, encodeContracts)

Loads and returns a Type.

This queries the BajaScript registry for a Type. If it doesn't exist then as a last resort, a synchronous network call is made in an attempt to retrieve the Type information.

Please note, no Contract information is retreived if a network call is made, only the Type information.

If a network call is expected to be made then please try asynchronously importing the Type information first via baja#importTypes.

Parameters:
{String} typeSpec: the type spec of the type we're interested in (moduleName:typeName).
{Boolean} encodeContracts Optional: encode the Contract when the Type is loaded (false by default).

Throws:
: error if the Type can't be found.

Returns:: {Type} the Type for the given type spec.

See:: baja.importTypes

<static> baja.noop()

A function that does nothing (noop = no-operation).

<private> <static> {Object} baja.objectify(obj, propName)

This is a conveniance method used for working with functions that take an Object Literal as an argument.

This method always ensures an Object is returned so its properties can be further validated.

In some cases, the function may take an object literal or a single argument. If the function can take a single argument that isn't an Object literal, then the 'propName' can be specified. If this is specified, an Object is created and the value is assigned to the Object with the specified property name.

  // For example, this function can take an Object literal or a Number
  function foo(obj) {
    obj = baja.objectify(obj, "num");
    
    // 'obj' will always point to an Object. We can now test and work with 'num'...
    baja.strictArg(obj.num, Number);
  }

  // Both method invocations are valid...
  foo(23.4); 
  foo({num: 23.4});

Parameters:
obj: the Object literal or a value to be added onto an Object if propName is specified.
{String} propName Optional: if the object isn't an Object, an Object is created and the value is assigned to the object with this property name.

Returns:: {Object} an Object

<static> baja.ok()

The global default ok callback function.

Throughout BajaScript there are places where network calls may be made. In one of these cases, a developer has the option of specifying an 'ok' callback. If the ok callback isn't specifed by the developer, it will default back to this function.

See:: baja.fail

<static> baja.outln(msg)

Print a message to BajaScript's debug output followed by a newline. By default just looks for a bajaJsPrint global function and passes the message to that.

Parameters:
{String} msg: the message to output.

Returns:: baja

<static> baja.preStop(func)

Add a function to be invoked just before BajaScript is stopped.

If BajaScript has already stopped, the function will be invoked immediately.

Parameters:
{Function} func

<static> baja.runAsync(fn)

Run the specified Function asynchronously.

Parameters:
{Function} fn: the Function to run asynchronously.

<static> baja.save()

Save BajaScript's Registry Storage. This is automatically called when BajaScript stops.

<static> baja.start(obj)

Start BajaScript.

This must be called to start BajaScript. This will make a network call to create a Session that starts BajaScript. It's recommended to call this as soon as possible.

This method takes a started function or an Object Literal for the method's arguments...

  baja.start(function () {
    // Called once BajaScript has started.
  });

  //...or this can be invoked via an Object Literal...

  baja.start({
    started: function () {
      // Called when BajaScript has started. We're ready to rock and roll at this point!
    },
    commFail: function () {
      // Called when the BajaScript communcations engine completely fails
    },
    typeSpecs: ["control:BooleanWritable", "control:NumericWritable"] // Types and Contracts we want imported 
                                                                      // upfront before our Web App loads
  });

Parameters:
{Object|Function} obj Optional: the Object Literal for the method's arguments or the function invoke after the comms have started.
{Function} obj.started Optional: function to invoke after the comms have started and (if running in a browser) the DOM is ready.
{Function} obj.commFail Optional: function to invoke if the comms fail.
{Array} obj.typeSpecs Optional: an array of type specs (moduleName:typeName) to import from the Server. Please note, this may not be needed if the Type and Contract information has been cached by web storage.
{Boolean} obj.navFile Optional: if true, this will load the nav file for the user on start up. By default, this is false.

See:: baja.started; baja.save; baja.preStop; baja.stop

<static> baja.started(func)

Add a function to be invoked once BajaScript has started.

If BajaScript has already started, the function will be invoked immediately.

Parameters:
{Function} func: invoked once BajaScript has started.

<static> baja.stop(obj)

Stop BajaScript.

This method should be called when the page running BajaScript is unloaded. This will make a network call to stop BajaScript's session.

This method takes a stopped function or an Object Literal for the method's arguments...

  baja.stop(function () {
    // Called once stop has completed
  });
  
  //...or this can be invoked via an Object Literal...
  
  baja.stop({
    stopped: function () {
      // Called once stop has completed 
    }
  });

Parameters:
{Object|Function} obj Optional: the Object Literal for the method's arguments or a function to be called once BajaScript has stopped.
{Function} obj.stopped Optional: called once BajaScript has stopped.
{Function} obj.preStop Optional: called just before BajaScript has stopped.

See:: baja.start; baja.started; baja.preStop

<private> <static> baja.strictAllArgs(args, ctors)

Strict Arguments Check.

Checks all of the given arguments to ensure they're not undefined. An array of Constructors is passed in to ensure they match the argument's Constructors.

// Example...
baja.strictAllArgs([arg1, arg2], [String, Number]);

Please note, the Constructors array can also hold a Type used for comparison (in the form of either a String or Type).

Parameters:
{Array} args: an array of arguments being tested.
{Array} ctors: an array of Constructors being used to test against the arguments.

See:: baja.strictArg

<private> <static> baja.strictArg(arg, ctor, errMsg)

Strict Argument Check.

Checks a given argument to ensure it's not undefined. If a Constructor is specified then it matches the argument's Constructor against it.

// Example...
baja.strictArg(arg1, String);

The second argument can also be a String TypeSpec or a Type Object. This will ensure the argument has the correct TypeSpec.

// Example...
baja.strictArg(arg1, "control:NumericWritable");

...or...

baja.strictArg(arg1, baja.lt("control:NumericWritable"));

Parameters:
arg: the argument being tested.
{Function|String|Type} ctor Optional: optional Constructor function used to test the argument against. Can also be a String TypeSpec or a Type Object.
{String} errMsg Optional: optional message to specify if argument check fails.

Returns:: arg

<static> {Function} baja.throttle(func, obj)

A general utility method that tries to prevents a function from running more often than the specified interval. Due to the vagaries of Javascript time management you may see the occasional drop of a few milliseconds but on the whole execution of the given function should not be permitted more than once in the specified interval.

If the function is called before the interval is up, it will still be executed once the remainder of the interval elapses - it will not be cancelled.

However, if the function is called multiple times before the interval has elapsed, only the lastfunction call will execute - calls prior to that one will be cancelled.

The function passed in will be run asynchronously via setTimeout(), so if you wish to process the results of the function call, you must do so via callback.

Parameters:
{Function} func: a function to be executed - must take no parameters and may optionally return a value.
{Object} obj: an object literal with additional parameters - also, passing a Number in as the second parameter will use that as obj.interval and the other params will be ignored/false.
{Number} obj.interval Optional: the interval in milliseconds - the function will be prevented from executing more often than this (if omitted, 100ms).
{Function} obj.ok Optional: an optional callback function that will handle the return value from the throttled function.
{Function} obj.fail Optional: an optional fail callback function that will be called if the function throws any exceptions.
{Boolean} obj.drop Optional: if drop is set to true, then additional function invocations that occur before the interval is up will be simply ignored rather than queued to execute at the end of the interval period.

Returns:: {Function} a throttled function that can be executed the same way as the original function.

Classes

Namespace baja