Composer

​Composer is an Angular library that simplifies interacting with Engine. It abstracts the complexity of the WebSocket API and manages the following:
Directives for binding to Status variables
Calling functions in the Driver
Resource access (database manipulation)
Authentication with Engine
Driver debug binding directives
The magic of Angular is that it allows you to build a dynamic web page in a declarative manner.
NOTE:: for universal support between mouse and touch devices we use the Hammer library which has action recognizers, such as pressing, swiping, pinching, etc.
Status Variable Bindings
Imagine the driver below running on Engine.
​https://github.com/acaprojects/aca-device-modules/blob/master/modules/philips/display/sicp_protocol.rb#L117​
It is a type of Display
It has a status variable called input
Input can be changed on the device by calling Display.switch_to(input_name)
You can request the status values available in drivers so you can present these graphically to a user. This is performed using the binding directive and the data requested is updated in real time as the status changes.
1
<span binding [sys]="system" mod="Display" bind="input" [(value)]="model.input" exec="switch_to" [params]="[model.input]">
2
    Display's current input: {{input}}
3
</span>
4
<button (press)="model.input = 'hdmi'">Switch to HDMI</button>
5
<button (press)="model.input = 'dvi'">Switch to DVI</button>
6
<button (press)="model.input = 'usb'">Switch to USB</button>
Copied!
Our aim with the client library was to make the interface code as self describing as possible, no abstract channel codes or feedback numbers. Let’s break this line down a little more.
binding: this tells Angular that we want to use the binding directive
[sys]: this is the system ID we want to connect to. The [] indicate that this is an input variable
mod: this is a raw string indicating the driver we would like to reference.
by default the driver index is 1 so in the example we are referencing Display_1
this could be more explicit: mod="Display_1"
or even more explicit mod="Display" [index]="model.selected_index"
[(value)]: this is the variable that will hold the status value requested
The binding is two way [()] so we can send any changes to the server / device
If the value is changed, by a user interacting with the interface, the function defined by exec will be called on the device module.
This is the primary method for updating state on the server / device
exec this is the function to run on the device module if the status value changes
The function is called with the parameters defined by [params]
There are times where execute can be simplified.
When the status variable and function used to update that status variable have the same name, the exec process can be simplified. This is an example of controlling volume and power for the same device.
1
<!-- Power Toggle Button -->
2
<button
3
    binding
4
    [sys]="system"
5
    mod="Display"
6
    bind="power"
7
    [(value)]="model.power"
8
    exec
9
    (press)="model.power = !model.power"
10
>Touch to Power {{ model.power ? 'Off' : 'On' }}</button>
11
​
12
<!-- Hide unless powered on -->
13
<div *ngIf="model.power == true">
14
    <span
15
        binding
16
        [sys]="system"
17
        mod="Display"
18
        bind="volume"
19
        [(value)]="model.volume"
20
        exec
21
    >Volume is {{model.volume}}</span>
22
    <input #volSlider type="range" (change)="model.volume = volSlider.value" min="0" max="100" />
23
</div>
Copied!
You can see that exec is present with no value configured. The result of this code is a power toggle button for the device and when the device is on there is a volume slider available.
Calling Functions in the Driver
You can call functions without binding to values first.
1
<!-- template method -->
2
<button
3
    binding
4
    [sys]="system"
5
    mod="Display"
6
    <!-- a change to this value will cause execute to fire, inital value is ignored -->
7
    [value]="model.power"
8
    exec="power"
9
    <!-- params that will be passed to the function can be customised -->
10
    [params]="[model.power, model.index]"
11
​
12
    <!-- Event triggering the exec -->
13
    (press)="model.power = !model.power"
14
>Touch to Toggle Power</button>
Copied!
You can also execute functions from type script
1
import { SystemsService } from `@acaprojects/ngx-composer`
2
@Component({ ... })
3
class DemoExec {
4
  constructor(private service: SystemsService) { }
5
​
6
  // use route or query params or local storgage for system ID
7
  power_on_display() {
8
    this.service.get(`sys-B0`).get(`Display`).exec(`power`, true);
9
  }
10
}
Copied!
Resource Access
Engine exposes a rich set of APIs that can be easily accessed via composer resources on the SystemsService
1
import { SystemsService } from `@acaprojects/ngx-composer`
2
@Component({ ... })
3
class DemoExec {
4
  constructor(private service: SystemsService) { }
5
​
6
  get_list_of_systems() {
7
    // Returns a list of systems matching the seatch query
8
    this.service.resources.get(`System`).get({
9
      q: `search`
10
    });
11
​
12
    // Gets the system information for this system
13
    this.service.resources.get(`System`).get({
14
      id: `sys-B0`
15
    });
16
  }
17
}
Copied!
You can get the following resource factories:
Dependency: available drivers
Trigger: trigger CRUD
System: control system CRUD
Module: module CRUD
Zone: zone CRUD
User: Current user details
Log: Access logs
Authentication
Authentication with Engine is handled automatically by composer.
1.Composer will request /auth/authority which contains information about how to authenticate
2.If composer doesn’t have a valid OAuth2 token it will redirect to the defined login page
3.A light weight page oauth-resp.html is used to extract the token and save it in local storage
4.A client side redirect back to the initial route
For this to occur composer must be configured as part of the applications load sequence.
See the example of this in Composer Starter​
The composer starter example
1.ensures the request to /auth/authority succeeds
2.configures connection and OAuth2 details
3.configures mode: production, development and if a mock / virtual control system should be used
4.calls this.systems.setup(config); which kicks off the authentication process as required
Driver Debug Bindings
It is possible to request debug logging to be redirected to your browser. This provides a real time window into the inner workings of the driver as it is executing.
1
<div
2
    debug
3
    [sys]="model.system_id"
4
    [mod]="model.module_id"
5
    numLines="20"
6
    [(output)]="model.output"
7
>{{model.output.join("<br />")}}</div>
Copied!
Useful for technical or administration pages.
Developer Guide - Previous
User Interfaces
Virtual Systems
Last modified 2yr ago
Copy link
Contents
Status Variable Bindings
Calling Functions in the Driver
Resource Access
Authentication
Driver Debug Bindings