new Subscriber()
Component Subscriber used to subscribe to multiple Component
s 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
Component
s currently being
subscribed to by thisSubscriber
.Returns:
a copy of the array of components
subscribed to by thisSubscriber
.- 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 thisSubscriber
.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 ofComponent
s.This will put the
Component
s into subscription if they are not already
subscribed and are mounted. The Subscription will last until the page is
refreshed orunsubscribe()
is called.If the
Component
s are mounted and able to be subscribed, this will result in
an asynchronous network call.If the
Component
s are mounted in multiple component spaces, there is a slight
chance for the promise to fail because a single component space subscription
failed, butComponent
s from other successful component spaces
could still be subscribed. Therefore, in a failure condition, it is not safe to
assume that none of theComponent
s were successfully subscribed. You can call
baja.Subscriber#isSubscribed in such a scenario to determine whichComponent
s 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 thecomps
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
Component
s to be subscribed.ok
function <optional>
(Deprecated: use Promise) the ok callback.
Called once theComponent
s have been subscribed.fail
function <optional>
(Deprecated: use Promise) the fail callback.
Called if theComponent
s 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 ofComponent
s 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 ofComponent
s.This will unsubscribe the mounted
Component
s if they are not already
unsubscribed.If the
Component
s are able to be unsubscribed, this will result in
an asynchronous network call.If the
Component
s are mounted in multiple component spaces, there is a slight
chance for the promise to fail because a single component space
unsubscription failed, butComponent
s 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
Component
s from aSubscriber
.If the
Component
s 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
- *