bajaScript Module: baja/comp/ControlPoint

Defines a BajaScript implementation of control:ControlPoint (not exposed
on baja namespace).

Methods

add(obj)

Add a dynamic Property to a Component.

If the value extends baja:Action, the new slot is also an Action.
If the value extends baja:Topic, the new slot is also a Topic.

If the Complex is mounted, this will asynchronously add
the Property to the Component on the server.

For callbacks, the 'this' keyword is set to the Component instance.

Parameters:

Name Type Description

obj

Object

the object literal for the method's arguments.

Properties

Name	Type	Argument	Description
`slot`	String		the Slot name the unique name to use as the String key for the slot. If null is passed, then a unique name will automatically be generated. If the name ends with the '?' character a unique name will automatically be generated by appending numbers to the specified name. The name must meet the "name" production in the SlotPath BNF grammar. Informally this means that the name must start with an ASCII letter and contain only ASCII letters, ASCII digits, or '_'. Escape sequences can be specified using the '$' char. Use `baja.SlotPath.escape()` to escape illegal characters.
`value`	baja.Value		the value to be added
`flags`	Number	<optional>	optional Slot flags.
`facets`	baja.Facets	<optional>	optional Slot Facets.
`ok`	function	<optional>	(Deprecated: use Promise) the ok callback. This function is called once the Property has been added to the Server. The function is passed the new `Property` that has just been added.
`fail`	function	<optional>	(Deprecated: use Promise) the fail callback. This function is called if the Property fails to add. Any error information is passed into this function.
`batch`	baja.comm.Batch	<optional>	if defined, any network calls will be batched into this object.
`cx`		<optional>	the Context (used internally by BajaScript).

Inherited From:

baja.Component#add

See:

Returns:

a promise that will be resolved with the
newly added Property.

Type: Promise.<baja.Property>

Example

An object literal is used to specify the method's arguments.

myObj.add({
    slot: 'foo',
    value: 'slot value',
    facets: baja.Facets.make({ doo: 'boo'), // Optional
    flags: baja.Flags.SUMMARY, // Optional  
    batch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function (prop) {
      baja.outln('added a new Property named "' + prop + '"');
    })
    .catch(function (err) {
      baja.error('error adding Property: ' + err);
    });

attach(event, func)

Attach an Event Handler to this Component instance.

When an instance of Component is subscribed to a Component running
in the Station, BajaScript can be used to listen for Component Events.

An event handler consists of a name and a function. When the
function is called, this will map to the target Component the handler
is attached to.

For a list of all the event handlers and some of this method's more advanced
features, please see baja.Subscriber#attach.

Parameters:

Name	Type	Description
`event`	String	handler name
`func`	function	the event handler function

Inherited From:

baja.Component#attach

See:

Example

A common event to attach to would be a Property changed event.

// myPoint is a mounted and subscribed Component...
  myPoint.attach("changed", function (prop, cx) {
    if (prop.getName() === "out") {
      baja.outln("The output of the point is: " + this.getOutDisplay());
    }
  });

canWrite(ordTarget)

If the target is to a slot within this component
then use the write permission based on the slot's
readonly and operator flags. If the target is the
component itself return if operator write is enabled.

Parameters:

Name	Type	Description
`ordTarget`	module:baja/ord/OrdTarget

Since:

Niagara 4.10

Inherited From:

baja.Component#canWrite

Returns:

true if the component has required permissions to be written into

Type: boolean

checkLink(obj)

Check the validity of a link to the specified source Component.

The target and source components must be mounted, leased / subscribed,
otherwise this function will fail.

For callbacks, the this keyword is set to the Component instance.

Parameters:

Name Type Description

obj

Object

the object literal for the method's arguments.

Properties

Name	Type	Argument	Description
`source`	baja.Component		the source Component for the link.
`sourceSlot`	baja.Slot \| String		the source Slot or Slot name.
`targetSlot`	baja.Slot \| String		the target Slot or Slot name.
`ok`	function	<optional>	(Deprecated: use Promise) the ok callback. A Link will be passed as an argument to this function.
`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.

Inherited From:

baja.Component#checkLink

Returns:

a promise that will be resolved with the
LinkCheck object.

Type: Promise.<baja.Struct>

Example

component.checkLink({
  source: sourceComponent,
  sourceSlot: 'sourceSlot',
  targetSlot: 'myTargetSlot',
  batch // if defined, any network calls will be batched into this object (optional)
})
  .then(function (linkCheck) {
    baja.outln('link checked: ' + linkCheck.isValid());
  })
  .catch(function (err) {
    baja.error('failed to check link: ' + err);
  });

detach( [hName] [, func])

Detach an Event Handler from the Component.

If no arguments are used with this method then all events are removed.

For some of this method's more advanced features, please see
baja.Subscriber#detach.

For a list of all the event handlers, please see baja.Subscriber#attach.

Parameters:

Name	Type	Argument	Description
`hName`	String	<optional>	the name of the handler to detach from the Component.
`func`	function	<optional>	the function to remove from the Subscriber. It's recommended to supply this just in case other scripts have added event handlers.

Inherited From:

baja.Component#detach

See:

doCheckLink(obj)

This is an override point to specify additional link checking
between the specified source and the target slot. The default
implementation is to return undefined, delegating the link checking to the
station. If you know the link is valid without checking the station,
return or resolve LinkCheck.makeValid(). If you know the link would result
in an error condition then return or resolve to an invalid LinkCheck
with the appropriate reason.

Parameters:

Name Type Description

obj

Object

the object literal for the method's arguments.

Properties

Name	Type	Argument	Description
`source`	baja.Component		the source Component for the LinkCheck.
`sourceSlot`	baja.Slot \| String		the source Slot or Slot name.
`targetSlot`	baja.Slot \| String		the target Slot or Slot name.
`ok`	function	<optional>	(Deprecated: use Promise) the ok callback. A LinkCheck will be passed as an argument to this function.
`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.

Inherited From:

baja.Component#doCheckLink

Returns:

a falsy value to delegate
the decision to the server. Otherwise, return a LinkCheck object, or a
promise resolving to one.

Type: null | LinkCheck | Promise.<LinkCheck>

equals(obj)

Indicates whether some other object is equal to this one.

Parameters:

Name	Type	Description
`obj`	Object	the reference object with which to compare.

Inherited From:

baja.BaseBajaObj#equals

Returns:

true if this object is the same as the obj argument; false otherwise.

Type: Boolean

equivalent(obj)

Compare if all of this object's properties are equal to the specified object.

Parameters:

Name	Type	Description
`obj`	baja.Complex

Inherited From:

baja.Complex#equivalent

Returns:

true if this object is equivalent to the specified object.

Type: Boolean

fire(obj)

Fire a Topic.

If the Component is mounted, this will asynchronously fire
the Topic on the Component in the Server.

For callbacks, the this keyword is set to the Component instance.

Parameters:

Name Type Description

obj

baja.Action | String | Object

the Topic, Topic name or object
literal for the method's arguments.

Properties

Name	Type	Argument	Description
`slot`	baja.Action \| String		the Topic or Topic name.
`value`		<optional>	the Topic's event.
`ok`	function	<optional>	(Deprecated: use Promise) the ok callback. This function is called once the Topic has been fired.
`fail`	function	<optional>	(Deprecated: use Promise) the fail callback. This function is called if the Topic fails to fire. Any error information is passed into this function.
`batch`	baja.comm.Batch	<optional>	if defined, any network calls will be batched into this object.
`cx`		<optional>	the Context (used internally by BajaScript).

Inherited From:

baja.Component#fire

Returns:

a promise that will be resolved once the Topic has been
fired.

Type: Promise

Examples

A Slot, Slot name or an object literal can used for the method's arguments.

// Fire the Topic via its Topic Slot...
  myObj.fire(fooTopic);

  // ...or via the Topic's Slot name...
  myObj.fire("foo");

  // ...or for more arguments, use an object literal...
  myObj.fire({
    slot: topicSlot, // Can also be a Topic Slot name
    value: "the Topic event argument",
    batch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function () {
      baja.outln('topic has been fired');
    })
    .catch(function (err) {
      baja.error('error firing topic: ' + err);
    });

Please note that auto-generated convenience methods are created and added to a Component for firing frozen Topics. If the name of the auto-generated Topic method is already used, BajaScript will attach a number to the end of the method name so it becomes unique.

// Fire a Topic called 'foo'
  myObj.fireFoo();

  // Fire a Topic called foo with an event argument...
  myObj.fireFoo("the Topic event argument");

  // ...or via an object literal for more arguments...
  myObj.fireFoo({
    value: "the Topic event argument",
    batch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function () {
      baja.outln('topic has been fired');
    })
    .catch(function (err) {
      baja.error('error firing topic: ' + err);
    });

get(prop)

Return a Property's value.

Note that when an instance of a Complex is created, auto-generated
accessors are created to make accessing a frozen Property's value
convenient (see example).

Parameters:

Name	Type	Description
`prop`	baja.Property \| String	the Property or Property name.

Inherited From:

baja.Complex#get

Returns:

the value for the Property (null if the Property doesn't exist).

Type: baja.Value

Example

Note that when an instance of a Complex is created, auto-generated setters are created to make setting a frozen Property's value convenient. The auto-generated setter is in the format of set(first letter is capitalized)SlotName(...).

// myPoint has a frozen Property named out...
  var val = myPoint.getOut();
  val = myPoint.get('out'); //equivalent

getActionParameterDefault(obj)

Returns the default parameter for an Action.

For unmounted Components, by default it calls
baja.ActionProperty#getParamDefault. If mounted in a Proxy
Component Space, this will result in an asynchronous network call.

For callbacks, the this keyword is set to the Component instance.

Parameters:

Name Type Description

obj

Object

the object literal for the method's arguments.

Properties

Name	Type	Argument	Description
`slot`	baja.Action \| String		the Action or Action name.
`ok`	function	<optional>	(Deprecated: use Promise) the ok callback. Called once the Action Parameter Default has been received. Any return value is passed to this function (could be null if no Action parameter is defined).
`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.

Inherited From:

baja.Component#getActionParameterDefault

Returns:

a promise that will be resolved once
the callbacks have been invoked.

Type: Promise.<(baja.Value|null)>

Example

// A resolved and mounted Component...
  myComp.getActionParameterDefault({
    slot: 'myAction',
    batch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function (param) {
      if (param === null) {
        baja.outln('action takes no parameters');
      } else {
        baja.outln('action parameter is: ' + param);
      }
    })
    .catch(function (err) {
      baja.error('could not retrieve action parameter: ' + err);
    });

getAgents( [is], batch)

Returns a promise that resolves to the agent list for this component.

Parameters:

Name	Type	Argument	Description
`is`	Array.<String>	<optional>	An optional array of filters to add to the agent query.
`batch`	baja.comm.Batch		An optional object used to batch network calls together.

Inherited From:

baja.Component#getAgents

See:

baja.registry.getAgents

Returns:

A promise that will resolve with the
Agent Info.

Type: Promise.<Array.<Object>>

getComponentSpace()

Return the Component Space.

Inherited From:

baja.Component#getComponentSpace

Returns:

the Component Space for this Component (if mounted) otherwise return null.

getDisplay( [slot] [, cx])

Return a display string.

If a Slot argument is defined, the display value for the Slot will be
returned. If a Slot argument is not defined, the display value for the
Complex will be returned.

Parameters:

Name	Type	Argument	Description
`slot`	baja.Property \| String	<optional>	the Slot or Slot name.
`cx`	object	<optional>	as of Niagara 4.10, you can pass a context as the second argument to use for string formatting. When a context is passed, a Promise will be returned to be resolved with the formatted string.

Inherited From:

baja.Complex#getDisplay

Returns:

display (or null if none available).

Type: String | null | Promise.<(String|null)>

Example

Printing display values of slots

// myPoint has a Property named out...
  baja.outln('The display string of the out Property: ' + myPoint.getDisplay('out'));

  // or use string formatting:
  return myPoint.getDisplay('out', { precision: 5 })
    .then(function (str) { baja.outln('formatted display string: ' + str); });

getDisplayName( [slot])

Return a display name.

If a Slot is defined as an argument, the display name for the slot will
be returned. If no Slot is defined, the display name of the Complex
will be returned.

Parameters:

Name	Type	Argument	Description
`slot`	baja.Slot \| String	<optional>	the Slot or Slot name.

Inherited From:

baja.Complex#getDisplayName

Returns:

the display name (or null if none available).

Type: String

getFacets( [slot])

Return the Facets for a Slot.

If no arguments are provided and the Complex has a parent, the
facets for the parent's Property will be returned.

Parameters:

Name	Type	Argument	Description
`slot`	baja.Slot \| String	<optional>	the `Slot` or Slot name.

Inherited From:

baja.Complex#getFacets

Returns:

the Facets for the Slot (or null if Slot not
found) or the parent's Property facets.

Type: baja.Facets

getFlags( [slot])

Return Flags for a slot or for the Complex's parent Property.

If no arguments are provided and the Complex has a parent, the
flags for the parent's Property will be returned.

Parameters:

Name	Type	Argument	Description
`slot`	baja.Slot \| String	<optional>	`Slot` or Slot name.

Inherited From:

baja.Complex#getFlags

See:

baja.Flags

Returns:

the flags for the Slot or the parent's Property flags.

Type: Number

getHandle()

Return the Component's handle.

Inherited From:

baja.Component#getHandle

Returns:

handle for this Component (if mounted), otherwise
null.

Type: String | null

getHandlers(hName)

Return an array of event handlers.

For a list of all the event handlers, please see
baja.Subscriber#attach.

To access multiple handlers, insert a space between the handler names.

Parameters:

Name	Type	Description
`hName`	String	the name of the handler

Inherited From:

baja.Component#getHandlers

See:

Returns:

Type: Array.<function()>

getIcon()

Return the Icon for the Component

Inherited From:

baja.Component#getIcon

Returns:

Type: baja.Icon

getKnobCount()

Return the knob count for the Component.

Inherited From:

baja.Component#getKnobCount

Returns:

the number of knobs installed on the Component

Type: Number

getKnobs( [slot])

Return the Knobs for a particular Slot or the whole Component.

If no slot is passed in all the knobs for the Component will be returned.

Parameters:

Name	Type	Argument	Description
`slot`	baja.Slot \| String	<optional>	the Slot or Slot name.

Inherited From:

baja.Component#getKnobs

Returns:

array of knobs

Type: Array.<Object>

getLinks( [slot])

Return the Links for a particular Slot or the whole Component.

If no slot is passed in all the links for the Component will be returned.

Parameters:

Name	Type	Argument	Description
`slot`	baja.Slot \| String	<optional>	the `Slot` or Slot name.

Inherited From:

baja.Component#getLinks

Returns:

array of links.

Type: Array.<baja.Struct>

getName()

Return the name of the Component.

The name is taken from the parent Component's Property for this
Component instance.

Inherited From:

baja.Complex#getName

Returns:

name (null if not mounted).

Type: String

getNavChildren()

Access the Nav Children for the Component.

Inherited From:

baja.Component#getNavChildren

See:

baja.NavContainer#getNavChildren

getNavDescription()

Return the Nav Description for the Component.

Inherited From:

baja.Component#getNavDescription

Returns:

Type: String

getNavDisplayName()

Return the Nav Display Name for the Component.

Inherited From:

baja.Component#getNavDisplayName

Returns:

Type: String

getNavIcon()

Return the Nav Icon for the Component

Inherited From:

baja.Component#getNavIcon

Returns:

Type: baja.Icon

getNavName()

Return the Nav Name for the Component.

Inherited From:

baja.Component#getNavName

Returns:

Type: String

getNavOrd( [params])

Return the Nav ORD for the Component.

Parameters:

Name Type Argument Description

params

object

Properties

Name	Type	Argument	Description
`sessionAware`	boolean	<optional>

Inherited From:

baja.Component#getNavOrd

See:

baja.NavContainer#getNavOrd

Returns:

the Nav ORD or null if it's not mounted.

Type: baja.Ord

getNavParent()

Return the Nav Parent for the Component.

Inherited From:

baja.Component#getNavParent

Returns:

parent Nav Node

getNavTypeSpec()

Return the type if the object the nav node navigates too.

For a Component, this is just a string version of its own type spec.

Inherited From:

baja.Component#getNavTypeSpec

Returns:

The nav node type spec.

Type: String

getOrdInSession()

Return the ORD in session for this Component.

Inherited From:

baja.Component#getOrdInSession

Returns:

ORD in Session for this Component (or null if not mounted).

Type: baja.Ord

getParent()

Return the parent.

Inherited From:

baja.Complex#getParent

Returns:

parent

Type: baja.Complex

getParentComponent()

Get the nearest ancestor of this object which is
an instance of Component. If this object is itself
a Component, then return this. Return
null if this object doesn't exist under a Component.

Since:

Niagara 4.10

Inherited From:

baja.Complex#getParentComponent

Returns:

Type: baja.Component | null

getPermissions()

Return the permissions for this Component.

Inherited From:

baja.Component#getPermissions

Returns:

Type: baja.Permissions

getPropertyInParent()

Return the Property in the parent.

Inherited From:

baja.Complex#getPropertyInParent

Returns:

the Property in the parent (null if not mounted).

Type: baja.Property

getRelationKnob(id)

Return the relation knob for the specified id.

Parameters:

Name	Type	Description
`id`	String	The id.

Inherited From:

baja.Component#getRelationKnob

Returns:

The relation knob or null if nothing can be found.

Type: Object | null

getRelationKnobCount()

Return the relation knob count for the component.

Inherited From:

baja.Component#getRelationKnobCount

Returns:

The number of relation knobs installed on the component.

Type: Number

getRelationKnobs()

Return all of the relation knobs for the component.

Inherited From:

baja.Component#getRelationKnobs

Returns:

An array of relation knobs.

Type: Array.<Object>

getSlot(slot)

Return the Slot.

This is useful method to ensure you have the Slot instance instead of the
Slot name String. If a Slot is passed in, it will simply be checked and
returned.

Parameters:

Name	Type	Description
`slot`	baja.Slot \| String	the `Slot` or Slot name.

Inherited From:

baja.Complex#getSlot

Returns:

the Slot for the Component (or null if the
Slot doesn't exist).

Type: baja.Slot

getSlotPath()

Return the Slot Path of the Component.

Inherited From:

baja.Component#getSlotPath

Returns:

the Slot Path or null if not mounted.

Type: baja.SlotPath

getSlots( [filter])

Return a Cursor for accessing a Complex's Slots.

Please see module:baja/comp/SlotCursor for useful builder methods.

Parameters:

Name	Type	Argument	Description
`filter`	function	<optional>	function to filter out the Slots we're not interested in. The filter function will be passed each `Slot` to see if it should be be included. The function must return false to filter out a value and true to keep it.

Inherited From:

baja.Complex#getSlots

Returns:

a Cursor for iterating through the Complex's Slots.

Type: module:baja/comp/SlotCursor

Example

// A Cursor for Dynamic Properties
  var frozenPropCursor = myComp.getSlots().dynamic().properties();

  // A Cursor for Frozen Actions
  var frozenPropCursor = myComp.getSlots().frozen().actions();

  // An Array of Control Points
  var valArray = myComp.getSlots().properties().is("control:ControlPoint").toValueArray();

  // An Array of Action Slots
  var actionArray = myComp.getSlots().actions().toArray();

  // An Object Map of slot name/value pairs
  var map = myComp.getSlots().properties().toMap();

  // The very first dynamic Property
  var firstProp = myComp.getSlots().dynamic().properties().first();

  // The very last dynamic Property
  var lastProp = myComp.getSlots().dynamic().properties().last();

  // The very first dynamic Property value
  var firstVal = myComp.getSlots().dynamic().properties().firstValue();

  // The very first dynamic Property value
  var lastVal = myComp.getSlots().dynamic().properties().lastValue();

  // All the Slots that start with the name 'foo'
  var slotNameCursor = myComp.getSlots().slotName(/^foo/);

  // Use a custom Cursor to find all of the Slots that have a particular facets key/value
  var custom = myComp.getSlots(function (slot) {
     return slot.isProperty() && (this.getFacets(slot).get("myKey", "def") === "foo");
  });

  // Same as above
  var custom2 = myComp.getSlots().filter(function (slot) {
     return slot.isProperty() && (this.getFacets(slot).get("myKey", "def") === "foo");
  });
  
  // All Slots marked summary on the Component
  var summarySlotCursor = myComp.getSlots().flags(baja.Flags.SUMMARY);

  // Call function for each Property that's a ControlPoint
  myComp.getSlots().is("control:ControlPoint").each(function (slot) {
    baja.outln("The Nav ORD for the ControlPoint: " + this.get(slot).getNavOrd();
  });

getType()

Get the type of this instance.

Inherited From:

baja.Object#getType

Returns:

Type: Type

getTypeDisplayName( [cx])

Gets the friendly type display name for this object.

Parameters:

Name	Type	Argument	Description
`cx`	Object	<optional>	a context to be passed down to Type

Since:

Niagara 4.10

Inherited From:

baja.Object#getTypeDisplayName

See:

baja.Type#getDisplayName

Returns:

If no context is provided, the type
display name is returned synchronously as a string. If context provided,
the type display name is resolved via a promise as a string.

Type: Promise.<string> | string

getUniqueName(slotName)

Return a unique name for a potential new Slot in this Component.

Please note, this method inspects the current Slots this Component has loaded
to find a unique name. Therefore, if this Component is a Proxy, it must be
fully loaded and subscribed. Also please refrain from using this method in a
batch operation since it's likely the other operations in the batch will influence
a Slot name's uniqueness.

Parameters:

Name	Type	Description
`slotName`	String	the initial Slot name used to ensure uniqueness. This must be a valid Slot name.

Inherited From:

baja.Component#getUniqueName

Returns:

a unique name.

Type: String

getValueOf(prop)

Return the result of valueOf on the specified Property's value.
If valueOf is not available then the Property's value is returned.

Parameters:

Name	Type	Description
`prop`	baja.Property \| String	the `Property` or Property name.

Inherited From:

baja.Complex#getValueOf

See:

baja.Complex#get

Returns:

the valueOf for the Property's value or the Property's
value (null if the Property doesn't exist).

has(prop)

Return true if the Slot exists.

Parameters:

Name	Type	Description
`prop`	baja.Property \| String	the Property or Property name

Inherited From:

baja.Complex#has

Returns:

Type: Boolean

hasHandlers( [hName])

Return true if there any handlers registered for the given handler name.

If no handler name is specified then test to see if there are any
handlers registered at all.

Multiple handlers can be tested for by using a space character between the names.

For a list of all the event handlers, please see
baja.Subscriber#attach.

Parameters:

Name	Type	Argument	Description
`hName`	String	<optional>	the name of the handler. If undefined, then see if there are any handlers registered at all.

Inherited From:

baja.Component#hasHandlers

See:

Returns:

Type: Boolean

invoke(obj)

Invoke an Action.

If the Component is mounted, this will asynchronously invoke
the Action on the Component in the Server.

For callbacks, the this keyword is set to the Component instance.

Parameters:

Name Type Description

obj

baja.Action | String | Object

the Action, Action name or object
literal for the method's arguments.

Properties

Name	Type	Argument	Description
`slot`	baja.Action \| String		the Action or Action name.
`value`		<optional>	the Action's argument.
`ok`	function	<optional>	(Deprecated: use Promise) the ok callback. This function is called once Action has been invoked. If the Action has a returned argument, this will be passed to this function.
`fail`	function	<optional>	(Deprecated: use Promise) the fail callback. This function is called if the Action fails to invoke. Any error information is passed into this function.
`batch`	baja.comm.Batch	<optional>	if defined, any network calls will be batched into this object.
`cx`		<optional>	the Context (used internally by BajaScript).

Inherited From:

baja.Component#invoke

Returns:

a promise that will be resolved once
the Action has been invoked.

Type: Promise.<(baja.Value|null)>

Examples

A Slot, Slot name or an object literal can used for the method's arguments.

// Invoke the Action via its Action Slot...
  myObj.invoke(fooAction);

  // ...or via the Action's Slot name...
  myObj.invoke("foo");

  // ...or for more arguments, use an object literal...
  myObj.invoke({
    slot: actionSlot, // Can also be an Action Slot name
    value: 'the Action argument',
    batch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function (returnValue) {
      baja.outln('action successfully invoked and returned: ' + returnValue);
    })
    .catch(function (err) {
      baja.error('error invoking action: ' + err);
    });

Please note that auto-generated convenience methods are created and added to a Component for invoking frozen Actions. If the name of the auto-generated Action method is already used, BajaScript will attach a number to the end of the method name so it becomes unique. For example, the 'set' Action on a NumericWritable would be called 'set1' because Component already has a 'set' method.

// Invoke an Action called 'override'. Pass in an argument
  myPoint.override(overrideVal);

  // ...or via an object literal for more arguments...
  myPoint.override({
    value: overrideVal
    batch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function (returnValue) {
      baja.outln('action successfully invoked and returned: ' + returnValue);
    })
    .catch(function (err) {
      baja.error('error invoking action: ' + err);
    });

isMounted()

Return true if the Component is mounted inside a Space.

Inherited From:

baja.Component#isMounted

Returns:

Type: Boolean

isNavChild()

Return true if this Component is a Nav Child.

Inherited From:

baja.Component#isNavChild

Returns:

true if this Component is a Nav Child.

Type: Boolean

isSubscribed()

Is the component subscribed?

Inherited From:

baja.Component#isSubscribed

Returns:

Type: Boolean

lease( [obj])

Subscribe a Component for a period of time.

The default lease time is 10 seconds.

Please note that a baja.Subscriber can also be used to put a
Component into and out of subscription.

If the Component is mounted and it can be subscribed, this will result in
an asynchronous network call.

If lease is called while the Component is already leased, the timer
will just be renewed.

For callbacks, the this keyword is set to the Component instance.

Parameters:

Name Type Argument Description

obj

Number | baja.RelTime | Object

the number of milliseconds,
RelTime or an object literal for the method's arguments.

Properties

Name	Type	Argument	Description
`ok`	function	<optional>	(Deprecated: use Promise) the ok callback. Called once the Component has been subscribed.
`fail`	function	<optional>	(Deprecated: use Promise) the fail callback. Called if the Component fails to subscribe. Any errors will be passed to this function.
`time`	Number \| baja.RelTime	<optional>	the number of milliseconds or RelTime for the lease.
`batch`	baja.comm.Batch	<optional>	if defined, any network calls will be batched into this object. The timer will only be started once the batch has fully committed.

Inherited From:

baja.Component#lease

See:

Returns:

a promise that will be resolved once the component has
been subscribed.

Type: Promise

Example

A time (Number or baja.RelTime) or an object literal can be used to specify the method's arguments.

// Lease for 15 seconds
  myComp.lease(15000);

  // ...or lease for 2 and half minutes...
  myComp.lease(baja.RelTime.make({minutes: 2, seconds: 30}));

  // ...or lease using an object literal for more arguments...
  myComp.lease({
    time: 1000, // in milliseconds. Can also be a RelTime.
    batch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function () {
      baja.outln('component has been leased');
    })
    .catch(function (err) {
      baja.error('failed to lease component: ' + err);
    });

loadSlots()

Load all of the Slots on the Component.

If the Component is mounted and it can be loaded, this will result in
an asynchronous network call.

For callbacks, the this keyword is set to the Component instance.

Parameters:

Name	Type	Argument	Description
`obj.ok`	function	<optional>	(Deprecated: use Promise) the ok callback. Called once the Component has been loaded.
`obj.fail`	function	<optional>	(Deprecated: use Promise) the fail callback. Called if the Component fails to load. Any errors will be passed to this function.
`obj.batch`	baja.comm.Batch	<optional>	if defined, any network calls will be batched into this object.

Inherited From:

baja.Component#loadSlots

Returns:

a promise that will be resolved once the slots have
been loaded.

Type: Promise

Example

An optional object literal can be used to specify the method's arguments.

myComp.loadSlots({
    batch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function () {
      baja.outln('slots have been loaded');
    })
    .catch(function (err) {
      baja.error('failed to load slots: ' + err);
    });

makeLink(obj)

Create an instance of a Link to use for a link to the specified source
Component.

For unmounted Components, by default this method resolves a plain
baja:Link instance. If mounted in a Proxy Component Space, this will
result in an asynchronous network call.

For callbacks, the this keyword is set to the Component instance.

Parameters:

Name Type Description

obj

Object

the object literal for the method's arguments.

Properties

Name	Type	Argument	Description
`source`	baja.Component		the source Component for the link.
`sourceSlot`	baja.Slot \| String		the source Slot or Slot name.
`targetSlot`	baja.Slot \| String		the target Slot or Slot name.
`ok`	function	<optional>	(Deprecated: use Promise) the ok callback. A Link will be passed as an argument to this function.
`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.

Inherited From:

baja.Component#makeLink

Returns:

a promise that will be resolved with the
newly added Link.

Type: Promise.<baja.Struct>

Example

component.makeLink({
  source: sourceComponent,
  sourceSlot: 'sourceSlot',
  targetSlot: 'myTargetSlot',
  batch // if defined, any network calls will be batched into this object (optional)
})
  .then(function (link) {
    baja.outln('link created: ' + link);
  })
  .catch(function (err) {
    baja.error('failed to create link: ' + err);
  });

newCopy( [exact])

Create a clone of this Complex.

If the exact argument is true and this Complex is a Component then
the defaultOnClone and removeOnClone flags will be ignored.

Parameters:

Name	Type	Argument	Default	Description
`exact`	Boolean	<optional>	false	flag to indicate whether to create an exact copy

Inherited From:

baja.Complex#newCopy

Returns:

cloned Complex.

Type: baja.Complex

relations( [obj])

Returns a promise that resolves to the Component's relations. If the
Component is mounted under a Proxy Component Space, a network call will be
made for the Component's implied relations to include into the result.

Parameters:

Name Type Argument Description

obj

Object

the object literal for the method's arguments.

Properties

Name	Type	Argument	Description
`ok`	function	<optional>	(Deprecated: use Promise) the ok callback. A link will be passed as an argument to this function.
`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.

Inherited From:

baja.Component#relations

Returns:

a promise that resolves
to the Component's relations.

Type: Promise.<baja/tag/ComponentRelations>

Example

component.relations({
  batch // if defined, any network calls will be batched into this object (optional)
})
  .then(function (relations) {
    baja.outln(relations.getAll().map(function (relation) {
      return relation.getId() + ' = ' + relation.getEndpointOrd();
    }).join());
  })
  .catch(function (err) {
    baja.error('failed to retrieve relations: ' + err);
  });

remove(obj)

Remove the dynamic Slot by the specified name.

If the Complex is mounted, this will asynchronously remove
the Property from the Component on the server.

For callbacks, the 'this' keyword is set to the Component instance.

Parameters:

Name Type Description

obj

baja.Slot | String | Object

the Slot, Slot name, Complex
instance or an object literal.

Properties

Name	Type	Argument	Description
`slot`	String		the Slot, Slot name or `Complex` instance to remove.
`ok`	function	<optional>	(Deprecated: use Promise) the ok callback. This function is called once the Property has been removed from the Server.
`fail`	function	<optional>	(Deprecated: use Promise) the fail callback. This function is called if the Property fails to remove. Any error information is passed into this function.
`batch`	baja.comm.Batch	<optional>	if defined, any network calls will be batched into this object.
`cx`		<optional>	the Context (used internally by BajaScript).

Inherited From:

baja.Component#remove

Returns:

a promise that will be resolved once the Property has
been removed.

Type: Promise

Example

The Slot, Slot name, a Complex or an object literal can be used for the method's arguments.

myObj.remove("foo");

  //...or via the Slot itself...

  myObj.remove(theFooSlot);

  //...or remove the Complex instance from the parent...

  myObj.remove(aComplexInstance);

  //... of if more arguments are needed then via object literal notation...

  myObj.remove({
    slot: 'foo',
    batch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function () {
      baja.outln('Property has been removed');
    })
    .catch(function (err) {
      baja.error('error removing Property: ' + err);
    });

rename(obj)

Rename the specified dynamic Slot.

If the Component is mounted, this will asynchronously rename
the Slot in the Component on the server.

For callbacks, the this keyword is set to the Component instance.

Parameters:

Name Type Description

obj

Object

the object literal used for the method's arguments.

Properties

Name	Type	Argument	Description
`slot`	baja.Slot \| String		the dynamic Slot or dynamic Slot name that will be renamed
`newName`	String		the new name of the Slot. The name must meet the "name" production in the `SlotPath` BNF grammar. Informally this means that the name must start with an ASCII letter, and contain only ASCII letters, ASCII digits, or '_'. Escape sequences can be specified using the '$' char. Use `baja.SlotPath.escape()` to escape illegal characters.
`ok`	function	<optional>	(Deprecated: use Promise) the ok callback. This function is called once the Slot has been renamed.
`fail`	function	<optional>	(Deprecated: use Promise) the fail callback. This function is called if the Slot fails to rename. Any error information is passed into this function.
`batch`	baja.comm.Batch	<optional>	if defined, any network calls will be batched into this object.
`cx`		<optional>	the Context (used internally by BajaScript).

Inherited From:

baja.Component#rename

Returns:

a promise that will be resolved once the slot has been
renamed.

Type: Promise

Example

An object literal is used for the method's arguments.

myObj.rename({
    slot: 'foo',
    newName: 'boo',
    batch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function () {
      baja.outln('slot has been renamed');
    })
    .catch(function (err) {
      baja.error('error renaming slot: ' + err);
    });

reorder(obj)

Reorder the Component's dynamic Properties.

If the Component is mounted, this will asynchronously reorder
the dynamic Properties in the Component on the Server.

For callbacks, the this keyword is set to the Component instance.

Parameters:

Name Type Description

obj

Array.<(baja.Property|String)> | Object

the array of Properties
or Property names, or an object literal used for the method's arguments.

Properties

Name	Type	Argument	Description
`dynamicProperties`	Array.<(baja.Property\|String)>		an array of Properties or Property names for the slot order.
`ok`	function	<optional>	(Deprecated: use Promise) the ok callback. This function is called once the dynamic Properties have been reordered.
`fail`	function	<optional>	(Deprecated: use Promise) the fail callback. This function is called if the dynamic Properties fail to reorder. Any error information is passed into this function.
`batch`	baja.comm.Batch	<optional>	if defined, any network calls will be batched into this object.
`cx`		<optional>	the Context (used internally by BajaScript).

Inherited From:

baja.Component#reorder

Returns:

a promise that will be resolved once the dynamic
properties have been reordered.

Type: Promise

Example

A Property array or an object literal can used for the method's arguments.

// Order via an array of Properties...
  myObj.reorder([booProp, fooProp, dooProp]);

  // ...or order via an array of Property names...
  myObj.reorder(["boo", "foo", "doo"]);

  // ...or for more arguments, use an object literal...
  myObj.reorder({
    dynamicProperties: [booProp, fooProp, dooProp], // Can also be a Property name array!
    batch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function () {
      baja.outln('slots have been reordered');
    })
    .catch(function (err) {
      baja.outln('error reordering slots: ' + err);
    });

rpc(methodName)

Invokes a Niagara RPC call on the Component running in the Station.
The method must implement the '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	Description
`methodName`	String	The method name of the RPC call to invoke on the Server.

Inherited From:

baja.Component#rpc

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.<(baja.Value|null)>

serverSideCall(obj)

Make a Server Side Call.

Sometimes it's useful to invoke a method on the server from BajaScript.
A Server Side Call is how this is achieved.

This will result in an asynchronous network call.

In order to make a Server Side Call, the developer needs to first create a
Niagara (Server Side) class that implements the
box:javax.baja.box.BIServerSideCallHandler interface.
The implementation should also declare itself as an Agent on the target
Component Type (more information in Java interface docs).
For callbacks, the 'this' keyword is set to the Component instance.

Parameters:

Name Type Description

obj

Object

the object literal for the method's arguments.

Properties

Name	Type	Argument	Description
`typeSpec`	String		the type specification of the Server Side Call Handler (`moduleName:typeName`).
`methodName`	String		the name of the method to invoke in the Server Side Call Handler
`value`			the value for the server side method argument (must be a BajaScript Type)
`ok`	function	<optional>	(Deprecated: use Promise) the ok callback. Called once the Server Side Call has been invoked. Any return value is passed to this function.
`fail`	function	<optional>	(Deprecated: use Promise) the fail callback. Called if the Component fails to load. Any errors will be passed to this function.
`batch`	baja.comm.Batch	<optional>	if defined, any network calls will be batched into this object.

Inherited From:

baja.Component#serverSideCall

Returns:

a promise that will be resolved once
the server side call has completed.

Type: Promise.<(baja.Value|null)>

Example

Here's an example of how a method implemented by this handler can be invoked.

// A resolved and mounted Component...
  myComp.serverSideCall({
    typeSpec: "foo:MyServerSideCallHandler", // The TypeSpec (moduleName:typeName) of the Server Side Call Handler
    methodName: "bar", // The name of the public method we wish to invoke in the handler
    value: "the argument for the method", // The argument to pass into the method (this can be any Baja Object/Component structure).
                                             It will be deserialized automatically by Niagara.
    batch // if defined, any network calls will be batched into this object (optional)
  })
   .then(function (returnValue) {
     baja.outln('server side call has completed with: ' + returnValue);
   })
   .catch(function (err) {
     baja.error('server side call failed: ' + err);
   });

set(obj)

Set a Property's value.

If the Complex is mounted, this will asynchronously set the Property's
value on the Server.

Parameters:

Name Type Description

obj

Object

the object literal for the method's arguments.

Properties

Name	Type	Argument	Description
`slot`	baja.Property \| String		the `Property` or Property name the value will be set on.
`value`			the value being set (Type must extend `baja:Value`).
`ok`	function	<optional>	(Deprecated: use Promise) the ok function callback. Called once the network call has succeeded on the Server.
`fail`	function	<optional>	(Deprecated: use Promise) the fail function callback. Called if this method has an error.
`batch`	baja.comm.Batch	<optional>	if defined, any network calls will be batched into this object.
`cx`		<optional>	the Context (used internally by BajaScript).

Inherited From:

baja.Complex#set

Returns:

a promise that will be resolved once the value has been
set on the Complex. If the complex is mounted, will be resolved once the
value has been saved to the server.

Type: Promise

Examples

An object literal is used to specify the method's arguments.

myObj.set({
    slot: "outsideAirTemp",
    value: 23.5,
    batch: myBatch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function () {
      baja.outln('value has been set on the server');
    })
    .catch(function (err) {
      baja.error('value failed to set on the server: ' + err);
    });

// myPoint has a Property named outsideAirTemp...
  myObj.setOutsideAirTemp(23.5);
  
  // ... or via an Object Literal if more arguments are needed...
  
  myObj.setOutsideAirTemp({ value: 23.5, batch: myBatch })
    .then(function () {
      baja.outln('value has been set on the server');
    });

setFacets(obj)

Set a dynamic Slot's facets.

If the Complex is mounted, this will *asynchronously change the
facets on the server.

For callbacks, the this keyword is set to the Component instance.

Parameters:

Name Type Description

obj

Object

the object literal for the method's arguments.

Properties

Name	Type	Argument	Description
`slot`	baja.Slot \| String		the Slot of Slot name.
`facets`	baja.Facets		the new facets for the dynamic Slot.
`ok`	function	<optional>	(Deprecated: use Promise) the ok function callback. Called once the method has succeeded.
`fail`	function	<optional>	(Deprecated: use Promise) the fail function callback. Called if this method has an error.
`batch`	baja.comm.Batch	<optional>	if defined, any network calls will be batched into this object.
`cx`		<optional>	the Context (used internally by BajaScript).

Inherited From:

baja.Component#setFacets

Returns:

a promise that will be resolved once the Facets have
been set.

Type: Promise

Example

An object literal is used to specify the method's arguments.

myObj.setFacets({
    slot: 'outsideAirTemp',
    facets: baja.Facets.make({ foo: 'boo' }),
    batch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function () {
      baja.outln('facets have been set');
    })
    .catch(function (err) {
      baja.error('error setting facets: ' + err);
    });

setFlags(obj)

Set a Slot's flags.

If the Complex is mounted, this will asynchronously set the Slot
Flags on the server.

For callbacks, the this keyword is set to the Component instance.

Parameters:

Name Type Description

obj

Object

the object literal for the method's arguments.

Properties

Name	Type	Argument	Description
`slot`	baja.Slot \| String		the Slot or Slot name.
`flags`	Number		the new flags for the Slot.
`ok`	function	<optional>	(Deprecated: use Promise) the ok function callback. Called once the method has succeeded.
`fail`	function	<optional>	the fail function callback. Called if this method has an error.
`batch`	baja.comm.Batch	<optional>	if defined, any network calls will be batched into this object.
`cx`		<optional>	the Context (used internally by BajaScript).

Inherited From:

baja.Component#setFlags

Returns:

a promise that will be resolved once the flags have been
set.

Type: Promise

Example

An object literal is used to specify the method's arguments.

myObj.setFlags({
    slot: 'outsideAirTemp',
    flags: baja.Flags.SUMMARY,
    batch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function () {
      baja.outln('flags were set');
    })
    .catch(function (err) {
      baja.error('error setting flags: ' + err);
    });

tags(obj)

Returns a promise that resolves to the Component's tags. If the Component
is mounted under a Proxy Component Space, a network call will be made
for the Component's implied tags to include into the result.

Parameters:

Name Type Description

obj

Object

the object literal for the method's arguments.

Properties

Name	Type	Argument	Description
`ok`	function	<optional>	(Deprecated: use Promise) the ok callback. A collection of tags will be passed as an argument to this function.
`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.

Inherited From:

baja.Component#tags

Returns:

a promise that resolves
to the Component's tags.

Type: Promise.<module:baja/tag/ComponentTags>

Example

component.tags({
  batch // if defined, any network calls will be batched into this object (optional)
})
  .then(function (tags) {
    baja.outln(tags.getAll().map(function (tag) {
      return tag.getId() + ' = ' + tag.getValue();
    }).join());
  })
  .catch(function (err) {
    baja.error('failed to retrieve tags: ' + err);
  });

toPathString()