Namespace: baja

baja

The core BajaScript namespace.

Classes

AbsTime
Action
ActionProperty
AsyncCursor
BaseBajaObj
BatchResolve
Complex
Component
ComponentSpace
Cursor
Date
DaysOfWeeksBits
DefaultSimple
Dimension
Double
DynamicEnum
Enum
EnumRange
EnumSet
Facets
FilterCursor
Flags
Float
Format
FrozenEnum
Host
Icon
Integer
LocalHost
Long
NameList
NameMap
NavContainer
NavNode
NavNodeContainer
Object
Ord
OrdList
OrdQueryList
OrdScheme
Permissions
PermissionsMap
Property
RelTime
Simple
Singleton
Slot
SlotPath
SlotScheme
Status
Struct
Subscriber
SyncCursor
Time
TimeZone
TimeZoneDatabase
Topic
Unit
UnitDatabase
Value
ViewQuery
VirtualComponent
VirtualComponentSpace
VirtualGateway
VirtualPath
VirtualScheme

Namespaces

browser
browser
bson
clock
coll
comm
event
file
nav
registry
transfer

Members


<static> stackTraceLimit :Number

Limits the length of stack traces printed by baja.error.

Type:
  • Number
Default Value:
  • 20

<static, readonly> TimeFormat :Number

Date and Time formatting.

Type:
  • Number
Properties:
Name Type Default Description
SHOW_DATE Number 1

Show the date field.

SHOW_TIME Number 2

Show the time field.

SHOW_SECONDS Number 4

Show the seconds field.

SHOW_MILLIS Number 8

Show the milliseconds field.

SHOW_ZONE Number 16

Show the time zone field.

See:

<static, constant> version :String

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

Type:
Default Value:
  • 2.0.0.0

Methods


<static> $(typeSpec)

Return an instance from the Type.

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

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:
Name Type Description
typeSpec String

the Type Specification.

See:
Throws:

if the given type spec could not be found

Type
Error
Returns:

an instance from the Type

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

Please note, if the Type information is invalid or hasn't been imported into BajaScript, this will throw an Error. Please use baja.importTypes to import Type information into BajaScript.

baja.importTypes({
    typeSpecs: ["control:NumericWritable"]
  })
    .then(function () {
      var v = baja.$("control:NumericWritable");
    });

  //or use the RequireJS plugin:

  require(['baja!control:NumericWritable'], function () {
    var v = baja.$("control:NumericWritable");
  });

<static> callbackify( [callbacks] [, defaultOk] [, defaultFail])

Ensure that a callback object literal exists and has ok and fail callbacks

  • default them to baja.ok and baja.fail,
    respectively, if they do not exist.
Parameters:
Name Type Argument Default Description
callbacks Object <optional>

an object containing ok/fail callbacks
(the object may be missing one or both callbacks or may itself be
undefined)

defaultOk function <optional>
baja.ok

the ok handler to use if none
provided

defaultFail function <optional>
baja.fail

the fail handler to use if
none provided


<static> callSuper( [methodName], instance [, args])

Call the instance's super method.

Parameters:
Name Type Argument Description
methodName String <optional>

the name of the method to invoke on the Super JavaScript Constructor. If not specified
then it's assumed the super JavaScript Constructor is being called.

instance

the instance to the Super JavaScript Constructor will be looked up from.

args Array <optional>

the arguments to invoke on the super method.

Returns:

value returned from super method.


<static> clearOut()

Attempt to clear BajaScript's debug output.

Returns:

baja


<static> 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:
Name Type Description
e

the error to output.

Returns:

baja


<static> 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 specified by the
developer, it will default back to this function.

Parameters:
Name Type Argument Default Description
err Error <optional>
new Error()

an error to print

See:

<static> findCtor(typeSpec)

Find a Type's Constructor and return it. If the Type hasn't been
Properly loaded then return null.

Parameters:
Name Type Description
typeSpec String

the type spec of the type we're interested
in (moduleName:typeName).

Returns:

the Constructor for the Type or null if nothing
is found.

Type
function

<static> getLanguage()

Returns language code for the user.

Returns:

the language character code.

Type
String

<static> getTimeFormatPattern()

Return the user's default time format pattern.

Returns:
Type
String

<static> getUnitConversion()

Return the user's configured unit conversion.

Returns:

an ordinal corresponding to a BUnitConversion enum

Type
number

<static> getUserHome()

Return the user home.

Returns:
Type
baja.Ord

<static> getUserName()

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

Returns:

the user name.

Type
String

<static> 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:
Name Type Argument Description
obj Object

the Object to be tested.

type Type | String <optional>

the type or (String type specification -
module:typeName) to test object against. Please note,
Type#is is used and not equals.

Returns:

true if the given Object is a proper BajaScript Object

Type
Boolean

<static> 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 number of network calls is expected to be made then a
Batch object can be passed into this method
along with a callback. The network call will then be 'batched'
accordingly.

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

Parameters:
Name Type Description
obj Object | Array

the object literal for the method's
arguments (or the array of type specs directly)

Properties
Name Type Argument Description
typeSpecs Array <optional>

an array of TypeSpecs to import.

ok function <optional>

(Deprecated: use Promise) the ok callback.
An array of the newly added Types will be passed into this handler.

fail function <optional>

(Deprecated: use Promise) the fail
callback.

batch baja.comm.Batch <optional>

If defined, any network calls will
be batched into this object.

See:
Returns:

A promise that will be resolved once
the types have been imported.

Type
Promise.<Array.<Type>>
Example

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"],
    batch: batch // If specified, network calls are batched into this object
  })
    .then(function (types) {
      baja.outln('imported all types: ' + types.join());
    })
    .catch(function (errObj) {
      baja.error('some types failed to import');
      Object.keys(errObj).forEach(function (typeSpec) {
        baja.error(typeSpec + ' failed because: ' + errObj[typeSpec]);
      });
    });

<static> 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:
Type
Boolean

<static> isOffline()

Return true if BajaScript is running in offline mode.

Returns:

offline.

Type
Boolean

<static> isStarted()

Return true if BajaScript has started.

Returns:

started

Type
Boolean

<static> isStopped()

Return true if BajaScript has stopped.

Returns:

stopped

Type
Boolean

<static> isStopping()

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

Returns:

stopping

Type
Boolean

<static> 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.

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.

Example
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))

<static> lex(obj)

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

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

If the argument is just a String, no network call will be made.
Instead, an attempt will be made to see if the Lexicon is cached
locally. If available, it's returned. If not then an Error will be
thrown. If you are not certain whether the lexicon is already loaded,
it's recommended to use a callback.

Please note, this method is now deprecated. Please use the lex module
instead.

Parameters:
Name Type Description
obj String | Object

a String for the module name or an object
literal for the method's arguments. If a String is specified, NO
network call will be made: the Lexicon will be returned if locally
available, or an error will be thrown if not.

Properties
Name Type Argument Description
module String <optional>

the module name to asynchronously look
up.

ok function <optional>

(Deprecated: use Promise) the ok callback.
Invoked once the Lexicon has been acquired. The Lexicon will be passed
as an argument to this callback.

fail function <optional>

(Deprecated: use Promise) the fail
callback. Invoked if Lexicon fails to import.

batch baja.comm.Batch <optional>

If specified, any network calls
will be batched into this object.

Deprecated:
  • Please use Lexicon JS instead.
See:
  • {module:nmodule/js/rc/lex/lex}
  • baja.request
Throws:

if looking up a Lexicon by name, but the Lexicon has
not yet been loaded

Type
Error
Returns:

If a String argument was specified, the Lexicon will be returned
directly; otherwise if an object literal was given, a Promise to be
resolved with the specified Lexicon.

Type
module:nmodule/js/rc/lex/lex | Promise.<module:nmodule/js/rc/lex/lex>
Example
// Get a value from a Lexicon. An asynchronous network call will be
  // made if the Lexicon isn't available locally. Note that this form
  // is safe to use whether the lexicon is already loaded or not.
  baja.lex({
    module: "bajaui"
  })
    .then(function (lex) {
      lex.get("dialog.ok");

      //now that the lexicon is loaded, baja.lex("bajaui") will
      //succeed from here on out.
    });

  // Get a value from a Lexicon. This will throw an error if the lexicon
  // was not already loaded via a network call as above.
  baja.lex("bajaui").get("dialog.ok");

<static> lt(typeSpec)

Loads and returns a Type.

This queries the BajaScript registry for a Type. If it doesn't exist
locally then null will be returned.

If a network call is expected to be made then please try
asynchronously importing the Type information first via
or specify it in {@link baja.start on startup.

Parameters:
Name Type Description
typeSpec String

the type spec of the type we're interested
in (moduleName:typeName).

See:
Returns:

the Type for the given type spec or null if the Type
can't be found locally.

Type
Type
Example
// Ensure the Type information is locally available.
  baja.importTypes({
    typeSpecs: ["foo:Boo"]
  })
    .then(function () {
      var type = baja.lt("foo:Boo");
    });

<static> Marker()

A marker value is used primarily with the tagging API in order to represent the
presence of a named tag that has no meaningful value. That is, the tag itself is
sufficient to convey meaning.


<static> mixin(Ctor, mixin)

Apply a Mix-In to the Constructor/Object.

The Constructor passed in is extended then the MixIn function is
invoked so that it can add to the newly extended object's prototype
chain.

This method can be invoked via a call to baja.subclass.

Parameters:
Name Type Description
Ctor function

the Constructor that we're mixing into.

mixin function

the Mix-In Function that when invoked will append
new method's to the newly subclassed Constructor.
When invoked, the new Constructor is passed in as the first
argument.

Returns:

the newly extended Constructor that has been extended with the Mix-In.

Type
function

<static> noop()

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


<static> 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:

<static> 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:
Name Type Description
msg String

the message to output.

Returns:

baja


<static> 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:
Name Type Description
func function

<static> rpc(ord [, methodName])

Make an RPC call to a method on the Server that implements the
Java 'NiagaraRpc' annotation.

Any extra arguments passed in will be encoded in raw JSON and passed up
to the Server. If one of those arguments is a 'baja.comm.Batch', the
call will be batched accordingly.

Parameters:
Name Type Argument Description
ord baja.Ord | String | Object

The ORD used to resolve the RPC call on the Server.
This can also be an Object Literal that has methodName (or method), args, ord
(or typeSpec), batch, ok and fail callback properties.

methodName String <optional>

The method name of the RPC call to invoke on
the Server.

Returns:

A promise that is resolved once the RPC call
has completed. If the Station RPC call returns a value then it will
be encoded and returned as a value in the promise.

Type
Promise

<static> runAsync(fn)

Run the specified Function asynchronously.

Parameters:
Name Type Description
fn function

the Function to run asynchronously.


<static> save()

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


<static> 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.

Parameters:
Name Type Argument Description
obj Object | function <optional>

the Object Literal for the method's arguments or the function invoke after the comms have started.

Properties
Name Type Argument Description
started function <optional>

function to invoke after the comms have started and (if running in a browser) the DOM is ready.

commFail function <optional>

function to invoke if the comms fail.

typeSpecs Array <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.

navFile Boolean <optional>

if true, this will load the nav file for the user on start up. By default, this is false.

See:
Example

This method takes a started function or an object literal.

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 communications engine completely fails
    },
    typeSpecs: ["control:BooleanWritable", "control:NumericWritable"] // Types and Contracts we want imported 
                                                                      // upfront before our Web App loads
  });

<static> started(func)

Add a function to be invoked once BajaScript has started.

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

Parameters:
Name Type Description
func function

invoked once BajaScript has started.


<static> 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.

Parameters:
Name Type Argument Description
obj Object | function <optional>

the Object Literal for the method's arguments or a function
to be called once BajaScript has stopped.

Properties
Name Type Argument Description
stopped function <optional>

called once BajaScript has stopped.

preStop function <optional>

called just before BajaScript has stopped.

See:
Example

This method takes a stopped function or an object literal.

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 
    }
  });

<static> subclass(Ctor, SuperCtor [, mixIn])

Extends an Object by setting up the prototype chain.

This method can have a Function or Object passed in as the SuperCtor argument.
If SuperCtor Function is passed in, 'new' will be called on it to create an Object.
The new Object will then be set on the target Function's prototype.

Parameters:
Name Type Argument Description
Ctor function

the subclass constructor

SuperCtor function | Object

the superclass constructor

mixIn function <optional>

a function that can apply a MixIn to the subclass.

See:
Returns:

Ctor.

Type
function

<static> 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 last function 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:
Name Type Description
func function

a function to be executed - must take no parameters
and may optionally return a value.

obj Object

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.

Properties
Name Type Argument Description
interval Number <optional>

the interval in milliseconds - the
function will be prevented from executing more often than this (if
omitted, 100ms).

ok function <optional>

an optional callback function that will
handle the return value from the throttled function.

fail function <optional>

an optional fail callback function that
will be called if the function throws any exceptions.

drop Boolean <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:

a throttled function that can be executed the same
way as the original function.

Type
function