cap:children
- access child things¶
This capability is used when a thing has children. Children are used to map when a thing is a bridge or when a physical thing has several virtual children. An example of such use is for power strips that support control or monitoring of their indivudal outlets.
if(thing.matches('cap:children')) {
// Get all children
const children = thing.children();
// Get a single child
const child = thing.child('usb');
}
API¶
-
children
()¶ Get the children of the thing as an iterable.
Example:
for(const child of thing.children) { console.log('Child:', child); }
-
child
(id)¶ Get a child based on its identifier. The identifier can either be a full identifier or a partial one.
Arguments: - id (string) – The identifier to get thing for.
Returns: The thing if found or
null
.Example:
const child = thing.child(fullIdOrPartial);
Partial identifiers¶
Partial identifiers are identifiers that make it easier to find a child. The are constructed in such a way that the full identifier is a combination of the parent id with a short logical id for the child.
For a thing with id example:thing
a child with the partial identifier
usb
would have the full id example:thing:usb
.
Events¶
-
thing:available
A new child is available for this thing. Emitted whenver a child is added.
Example:
thing.on('thing:available', child => console.log('Added child:', child));
-
thing:unavailable
A child is no longer available. Emitted when a child is no longer available.
Example:
thing.on('thing:unavailable', child => console.log('Removed child:', child));
Protected methods¶
-
addChild
(thing)¶ Add a child to this thing. This will add the thing and emit the
thing:available
event.Arguments: - thing – The thing to add as a child.
Example:
this.addChild(new ChildThing(...));
-
removeChild
(thingOrId)¶ Remove a child from this thing. This will remove the thing and emit the
thing:unavailable
event.Arguments: - thingOrId – The thing instance or identifier that should be removed.
Example:
this.removeChild(existingChild); this.removeChild('id-of-thing');
-
findChild
(filter)¶ Find the first child that matches the given filter function.
Arguments: - filter (function) – Filter function to apply, should return
true
when a thing matches.
Returns: Thing if found, otherwise
null
.Example:
// Get the first power outlet this.findChild(thing => thing.matches('type:power-outlet'));
- filter (function) – Filter function to apply, should return
Implementing capability¶
When implementing this capability children need to be managed. This can either
be done manually or via a method such as ChildSyncer
.
Manual management is recommended if only a few known children exist:
const { Thing, Children } = require('abstract-things');
class Example extends Thing.with(Children) {
constructor() {
super();
this.addChild(new ChildThing(this, ...));
}
}
Using ChildSyncer
, commonly for things such as bridges:
const { ChildSyncer } = require('abstract-things/children');
class Example extends Thing.with(Children) {
constructor() {
super();
this.syncer = new ChildSyncer(this, (def, thing) => {
});
}
async initCallback() {
await super.initCallback();
await this.loadChildren();
}
async loadChildren() {
/*
* Load the children, should be an array with objects that contain
* at least an `id` property.
*/
const defs = await loadChildrenSomehow();
await syncer.update(defs);
}
}