Class: Subscriber

baja. Subscriber


new Subscriber()

Component Subscriber used to subscribe to multiple Components for events.

Extends

Methods


attach(event, func)

Attach an Event Handler to this Subscriber.

A Subscriber can be used to subscribe to multiple Components
in the Station and 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.

Parameters:
Name Type Description
event String

handler name.

func function

the event handler function.

See:
Examples

A common use case would be a Property changed event.

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

An object literal can be used to specify multiple handlers.

var sub = new baja.Subscriber();
  sub.attach({
    changed: function (prop, cx) {
    },
    subscribed: function (cx) {
    }
  });

Spaces can be used in a name to specify a function for multiple events.

var sub = new baja.Subscriber();
  sub.attach("subscribed changed", function () {
    updateGui(this);
  });
  

Here are some examples of the different event handlers that can be attached to a Component.

// Property Changed
  sub.attach("changed", function (prop, cx) {
    // prop: the Property that has changed
    // cx: the Context (used internally)
  });
  
  // Property Added
  sub.attach("added", function (prop, cx) {
    // prop: the Property that has been added
    // cx: the Context (used internally)
  });
  
  // Property Removed
  sub.attach("removed", function (prop, val, cx) {
    // prop: the Property that has been removed
    // val: the old value of the Property
    // cx: the Context (used internally)
  });
  
  // Property Renamed
  sub.attach("renamed", function (prop, oldName, cx) {
    // prop: the Property that has been renamed
    // oldName: the old slot name
    // cx: the Context (used internally)
  });
  
  // Dynamic Slots Reordered
  sub.attach("reordered", function (cx) {
    // cx: the Context (used internally)
  });
  
  // Topic Fired
  sub.attach("topicFired", function (topic, event, cx) {
    // topic: the Topic that has been fired
    // event: the Topic event data (can be null)
    // cx: the Context (used internally)
  });
  
  // Slot Flags Changed
  sub.attach("flagsChanged", function (slot, cx) {
    // slot: the slot whose flags have changed
    // cx: the Context (used internally)
  });
  
  // Slot Facets Changed
  sub.attach("facetsChanged", function (slot, cx) {
    // slot: the slot whose facets have changed
    // cx: the Context (used internally)
  });

  // Component subscribed
  sub.attach("subscribed", function (cx) {
    // cx: the Context (used internally)
  });

  // Component unsubscribed
  sub.attach("unsubscribed", function (cx) {
    // cx: the Context (used internally)
  });

  // Component unmounted (called just before Component is removed from parent)
  sub.attach("unmount", function (cx) {
    // cx: the Context (used internally)
  });

  // Component renamed in parent
  sub.attach("componentRenamed", function (oldName, cx) {
    // cx: the Context (used internally)
  });

  // Component's flags changed in parent
  sub.attach("componentFlagsChanged", function (cx) {
    // cx: the Context (used internally)
  });

  // Component's facets changed in parent
  sub.attach("componentFacetsChanged", function (cx) {
    // cx: the Context (used internally)
  });

  // Component reordered in parent
  sub.attach("componentReordered", function (cx) {
    // cx: the Context (used internally)
  });

detach( [hName] [, func])

Detach an Event Handler from the Subscriber.

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

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

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.

See:
Example
sub.detach("renamed"); // Remove a single handler
  sub.detach("subscribed changed"); // Remove multiple handlers at once

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

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

Type
Boolean

getComponents()

Return an array of the Components currently being
subscribed to by this Subscriber.

Returns:

a copy of the array of components
subscribed to by this Subscriber.

Type
Array.<baja.Component>

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

See:
Returns:
Type
Array.<function()>

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.

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

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

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.

See:
Returns:
Type
Boolean

isEmpty()

Return true if the Subscriber is empty of subscriptions.

Returns:

true if the Subscriber is empty.

Type
Boolean

isSubscribed(comp)

Return true if the Component is subscribed in this Subscriber.

Parameters:
Name Type Description
comp baja.Component

the Component to be tested for subscription.

Returns:
Type
Boolean

subscribe( [obj])

Subscribe a Component or a number of Components.

This will put the Components into subscription if they are not already
subscribed and are mounted. The Subscription will last until the page is
refreshed or unsubscribe() is called.

If the Components are mounted and able to be subscribed, this will result in
an asynchronous network call.

If the Components are mounted in multiple component spaces, there is a slight
chance for the promise to fail because a single component space subscription
failed, but Components from other successful component spaces
could still be subscribed. Therefore, in a failure condition, it is not safe to
assume that none of the Components were successfully subscribed. You can call
baja.Subscriber#isSubscribed in such a scenario to determine which
Components were successfully subscribed and which were not. Furthermore, even
when a failure condition occurs, you may still need to remember to call
baja.Subscriber#unsubscribe due to the scenario just described.

For callbacks, the this keyword is set to the comps property.

Parameters:
Name Type Argument Description
obj Object <optional>

the object literal used for the method's arguments.

Properties
Name Type Argument Description
comps baja.Component | Array

The Component or array of
Components to be subscribed.

ok function <optional>

(Deprecated: use Promise) the ok callback.
Called once the Components have been subscribed.

fail function <optional>

(Deprecated: use Promise) the fail callback.
Called if the Components fail to subscribe. Any errors will be passed to
this function.

batch baja.comm.Batch <optional>

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

Returns:

a promise that will be resolved once component(s) have
been subscribed.

Type
Promise
Example

A Component instance, array of Components or an optional object literal can be used.

// Subscribe a single Component
  sub.subscribe(aComp);

  // ...or subscribe an array of Components...
  sub.subscribe([aComp1, aComp2]);

  // ...or use an object literal for more arguments...
  sub.subscribe({
    comps: [aComp1, aComp2], // Can also just be an singular Component instance
    batch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function () {
      baja.outln('components have been subscribed');
    })
    .catch(function (err) {
      baja.error('some components failed to subscribe: ' + err);

      // If the components were mounted in different component spaces,
      // remember to check sub.isSubscribed(comp) to determine which
      // components successfully subscribed and which failed
    });

unsubscribe( [obj])

Unsubscribe a Component or a number of Components.

This will unsubscribe the mounted Components if they are not already
unsubscribed.

If the Components are able to be unsubscribed, this will result in
an asynchronous network call.

If the Components are mounted in multiple component spaces, there is a slight
chance for the promise to fail because a single component space
unsubscription failed, but Components from other component spaces could
have been successfully unsubscribed.

For callbacks, the 'this' keyword is set to the comps property.

Parameters:
Name Type Argument Description
obj Object <optional>

the object literal used for the method's arguments.

Properties
Name Type Argument Description
ok function <optional>

(Deprecated: use Promise) the ok callback.
Called once the Components have been unsubscribed.

fail function <optional>

(Deprecated: use Promise) the fail callback.
Called if the Components fail to subscribe. Any errors will be passed to
this function.

batch baja.comm.Batch <optional>

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

Returns:

a promise that will be resolved once the components have
been unsubscribed.

Type
Promise
Example

A `Component` instance, array of `Component`s or an optional object literal can be used to specify the method's arguments.

// Unsubscribe a single Component
  sub.unsubscribe(aComp);

  // ...or unsubscribe an array of Components...
  sub.unsubscribe([aComp1, aComp2]);

  // ...or use an object literal for more arguments...
  sub.unsubscribe({
    comps: [aComp1, aComp2], // Can also just be an singular Component instance
    batch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function () {
      baja.outln('components have been unsubscribed');
    })
    .catch(function (err) {
      baja.error('components failed to unsubscribe: ' + err);
    });

unsubscribeAll( [obj])

Unsubscribe and unregister all Components from a Subscriber.

If the Components are able to be unsubscribed, this will result in
an asynchronous network call.

For callbacks, the this keyword is set to the internal component array.

Parameters:
Name Type Argument Description
obj Object <optional>

the Object Literal used for the method's arguments.

Properties
Name Type Argument Description
ok function <optional>

(Deprecated: use Promise) the ok callback.
Called once the Components have been unsubscribed.

fail function <optional>

(Deprecated: use Promise) the fail callback.
Called if the Components fail to unsubscribe. Any errors will be passed to
this function.

batch baja.comm.Batch <optional>

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

Returns:

a promise that will be resolved once all components are
unsubscribed.

Type
Promise
Example
sub.unsubscribeAll({
    batch // if defined, any network calls will be batched into this object (optional)
  })
    .then(function () {
      baja.outln('all components unsubscribed');
    })
    .catch(function (err) {
      baja.error('failed to unsubscribe components: ' + err);
    });

valueOf()

Return the inner value of the object.

By default the object's instance is returned.

Inherited From:
Returns:

the inner value of the object or just the object's instance.

Type
*