ExternalVendorCode/openmct
1
0
Fork 0
mirror of https://github.com/nasa/openmct.git synced 2025-01-07 05:38:42 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

[Time Conductor] Made corrections to Time API documentation. Added a key field to the NumberFormat so that it can be used with the new format registration mechanism

Browse Source
This commit is contained in:
Henry 2017-05-01 11:27:00 -07:00
parent 0981e99256
commit 37c9c6dfaf
2 changed files with 127 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

190
API.md
View File

@ -355,6 +355,56 @@ request object with a start and end time is included below:
### Telemetry Formats ### Telemetry Formats
Telemetry format objects define how to interpret and display telemetry data.
They have a simple structure:
* `key`: A `string` that uniquely identifies this formatter.
* `format`: A `function` that takes a raw telemetry value, and returns a human-readable
`string` representation of that value. It has one required argument, and three
optional arguments that provide context and can be used for returning scaled
representations of a value. An example of this is representing time values in a
scale such as the time conductor scale. There are multiple ways of representing
a point in time, and by providing a minimum scale value, maximum scale value,
and a count, it's possible to provide more useful representations of time given
the provided limitations.
* `value`: The raw telemetry value in its native type.
* `minValue`: An __optional__ argument specifying the minimum displayed value.
* `maxValue`: An __optional__ argument specifying the maximum displayed value.
* `count`: An __optional__ argument specifying the number of displayed values.
* `parse`: A `function` that takes a `string` representation of a telemetry value,
and returns the value in its native type. It accepts one argument:
* `text`: A `string` representation of a telemetry value.
* `validate`: A `function` that takes a `string` representation of a telemetry
value, and returns a `boolean` value indicating whether the provided string can be
parsed.
#### Registering Formats
Formats are registered with the Telemetry API using the `addFormat` function. eg.
``` javascript
openmct.telemetry.addFormat({
key: 'number-to-string',
format: function (number) {
return number + '';
},
parse: function (text) {
return Number(text);
},
validate: function (text) {
return !isNaN(text);
}
});
```
#### Examples of Formats in Use
* The [NumberFormat](https://github.com/nasa/openmct/blob/time-api-redo/platform/features/conductor/core/src/ui/NumberFormat.js)
provides an example of a simple format available by default
in OpenMCT.
* The [UTCTimeFormat](https://github.com/nasa/openmct/blob/master/src/plugins/utcTimeSystem/UTCTimeFormat.js)
is a more complex implementation of a format that uses the optional context
arguments in `format` to provide scale-appropriate values.
### Telemetry Data ### Telemetry Data
Telemetry data is provided to Open MCT by _[Telemetry Providers](#telemetry-providers)_ Telemetry data is provided to Open MCT by _[Telemetry Providers](#telemetry-providers)_
@ -394,8 +444,10 @@ openmct.telemetry.addProvider({
``` ```
## Time API ## Time API
Telemetry requests and the data visible in views is typically constrained by Open MCT provides API for managing the temporal state of the application. Central
temporal bounds, and the Time API provides a way to centrally manage these bounds. to this is the concept of "time bounds". Views in Open MCT will typically show
telemetry data for some prescribed date range, and the Time API provides a way
to centrally manage these bounds.
The Time API exposes a number of methods for querying and setting the temporal The Time API exposes a number of methods for querying and setting the temporal
state of the application, and emits events to inform listeners when the state changes. state of the application, and emits events to inform listeners when the state changes.
@ -409,10 +461,11 @@ activating a time system is simple, and is covered
### Time Systems and Bounds ### Time Systems and Bounds
#### Defining and Registering Time Systems #### Defining and Registering Time Systems
A Time System gives meaning to the time values returned from the Time API. Absent The time bounds of an Open MCT application are defined as numbers, and a Time
a time system, time bounds are simply numbers. Time Systems are simply objects that System gives meaning and context to these numbers so that they can be correctly
provide some information about the current time reference frame. An example of interpreted. Time Systems are javscript objects that provide some information
defining and registering a new time system is given below. about the current time reference frame. An example of defining and registering
a new time system is given below:
``` javascript ``` javascript
openmct.time.addTimeSystem({ openmct.time.addTimeSystem({
@ -427,24 +480,24 @@ openmct.time.addTimeSystem({
The example above defines a new utc based time system. In fact, this time system The example above defines a new utc based time system. In fact, this time system
is configured and activated by default from `index.html` in the default is configured and activated by default from `index.html` in the default
installation of Open MCT if you download the source from GitHub. some details of installation of Open MCT if you download the source from GitHub. Some details of
each of the required properties is provided below. each of the required properties is provided below.
* `key`: A `string` that uniquely identifies this time system. * `key`: A `string` that uniquely identifies this time system.
* `name`: A `string` providing a brief human readable label. If the [Time Conductor]() * `name`: A `string` providing a brief human readable label. If the [Time Conductor](#the-time-conductor)
plugin is enabled, this name will identify the time system in a dropdown menu. plugin is enabled, this name will identify the time system in a dropdown menu.
* `cssClass`: A class name `string` that will be applied to the time system when * `cssClass`: A class name `string` that will be applied to the time system when
it appears in the UI. This will be used to represent the time system with an icon. it appears in the UI. This will be used to represent the time system with an icon.
There are a number of built-in icon classes [available in Open MCT](https://github.com/nasa/openmct/blob/master/platform/commonUI/general/res/sass/_glyphs.scss), There are a number of built-in icon classes [available in Open MCT](https://github.com/nasa/openmct/blob/master/platform/commonUI/general/res/sass/_glyphs.scss),
or a custom class can be used here. or a custom class can be used here.
* `timeFormat`: A `string` corresponding to the key of a registered * `timeFormat`: A `string` corresponding to the key of a registered
[telemetry time format](#Telemetry-Formats). The format will be used for [telemetry time format](#telemetry-formats). The format will be used for
displaying discrete timestamps from telemetry streams when this time system is displaying discrete timestamps from telemetry streams when this time system is
activated. If the [UTCTimeSystem](#included-plugins) is enabled, then the `utc` activated. If the [UTCTimeSystem](#included-plugins) is enabled, then the `utc`
format can be used if this is a utc-based time system format can be used if this is a utc-based time system
* `durationFormat`: A `string` corresponding to the key of a registered * `durationFormat`: A `string` corresponding to the key of a registered
[telemetry time format](#Telemetry-Formats). The format will be used for [telemetry time format](#telemetry-formats). The format will be used for
displaying time ranges, for example 00:15:00 might be used to represent a time displaying time ranges, for example `00:15:00` might be used to represent a time
period of fifteen minutes. These are used by the Time Conductor plugin to specify period of fifteen minutes. These are used by the Time Conductor plugin to specify
relative time offsets. If the [UTCTimeSystem](#included-plugins) is enabled, relative time offsets. If the [UTCTimeSystem](#included-plugins) is enabled,
then the `duration` format can be used if this is a utc-based time system then the `duration` format can be used if this is a utc-based time system
@ -453,8 +506,8 @@ numbers in UTC terrestrial time.
#### Getting and Setting the Active Time System #### Getting and Setting the Active Time System
Once registered, a time system can be activated using via a key, or an instance Once registered, a time system can be activated using a key, or an instance of
of the time system itself. the time system itself.
```javascript ```javascript
openmct.time.timeSystem('utc'); openmct.time.timeSystem('utc');
@ -480,7 +533,7 @@ Setting the active time system will trigger a [time system event](#time-events).
### Time Bounds ### Time Bounds
The TimeAPI provides a getter/setter for querying and setting time bounds. Time The TimeAPI provides a getter/setter for querying and setting time bounds. Time
bounds are simply an object with a single `start` and a single `end` attribute. bounds are simply an object with a `start` and an end `end` attribute.
* `start`: A `number` representing a moment in time in the active [Time System](#defining-and-registering-time-systems). * `start`: A `number` representing a moment in time in the active [Time System](#defining-and-registering-time-systems).
This will be used as the beginning of the time period displayed by time-responsive This will be used as the beginning of the time period displayed by time-responsive
@ -540,7 +593,7 @@ invoked when the clock next ticks. It will be invoked with two arguments:
* `eventName`: A `string` specifying the event to listen on. For now, clocks * `eventName`: A `string` specifying the event to listen on. For now, clocks
support one event - `tick`. support one event - `tick`.
* `callback`: A `function` that will be invoked when this clock ticks. The * `callback`: A `function` that will be invoked when this clock ticks. The
function should be invoked with one parameter - a `number` representing a valid function must be invoked with one parameter - a `number` representing a valid
time in the current time system. time in the current time system.
* `off`: A `function` that allows deregistration of a tick listener. It accepts * `off`: A `function` that allows deregistration of a tick listener. It accepts
the same arguments as `on`. the same arguments as `on`.
@ -556,7 +609,7 @@ var someClock = {
key: 'someClock', key: 'someClock',
cssClass: 'icon-clock', cssClass: 'icon-clock',
name: 'Some clock', name: 'Some clock',
description: "Presumably does something useful" description: "Presumably does something useful",
on: function (event, callback) { on: function (event, callback) {
// Some function that registers listeners, and updates them on a tick // Some function that registers listeners, and updates them on a tick
}, },
@ -578,13 +631,13 @@ An example clock implementation is provided in the form of the [LocalClock](http
Once registered a clock can be activated by calling the `clock` function on the Once registered a clock can be activated by calling the `clock` function on the
Time API passing in the key or instance of a registered clock. Only one clock Time API passing in the key or instance of a registered clock. Only one clock
may be active at once, so activating a clock will deactivate any currently may be active at once, so activating a clock will deactivate any currently
active clock. Setting the clock will also trigger a 'clock' event. active clock. Setting the clock will also trigger a ['clock' event](#time-events).
``` ```
openmct.time.clock(someClock); openmct.time.clock(someClock);
``` ```
Upon being set, a clock's `on` function will be immediately called to subscribe Upon being activated, a clock's `on` function will be immediately called to subscribe
to `tick` events. to `tick` events.
The currently active clock (if any) can be retrieved by calling the same The currently active clock (if any) can be retrieved by calling the same
@ -593,8 +646,7 @@ function without any arguments.
#### Stopping an active clock #### Stopping an active clock
The `stopClock` method can be used to stop an active clock, and to clear it. It The `stopClock` method can be used to stop an active clock, and to clear it. It
will stop the clock from ticking, and the effect of setting the active clock to will stop the clock from ticking, and set the active clock to `undefined`.
`undefined`.
``` javascript ``` javascript
openmct.time.stopClock(); openmct.time.stopClock();
@ -603,18 +655,18 @@ openmct.time.stopClock();
#### Clock Offsets #### Clock Offsets
When a clock is active, the time bounds of the application will be updated When a clock is active, the time bounds of the application will be updated
automatically each time the clock `ticks`. The bounds are calculated based on automatically each time the clock "ticks". The bounds are calculated based on
the current value provided by the active clock (via its `tick` event, and its the current value provided by the active clock (via its `tick` event, or its
`currentValue()` method). `currentValue()` method).
Unlike bounds, which represent absolute time values, clock offsets represent Unlike bounds, which represent absolute time values, clock offsets represent
relative time spans. Offsets are defined as an object with two properties: relative time spans. Offsets are defined as an object with two properties:
* `start`: A `number` that must be < 0, and is used to calculate the start bounds * `start`: A `number` that must be < 0 and which is used to calculate the start
on each clock tick. The start offset will be calculated relative to the value bounds on each clock tick. The start offset will be calculated relative to the
provided by a clock's tick callback, or its `currentValue` function. value provided by a clock's tick callback, or its `currentValue()` function.
* `end`: A `number` that must be >=0, and is used to calculate the end bounds on * `end`: A `number` that must be >=0 and which is used to calculate the end
each clock tick. bounds on each clock tick.
The `clockOffsets` function can be used to get or set clock offsets. For example, The `clockOffsets` function can be used to get or set clock offsets. For example,
to show the last fifteen minutes in a ms-based time system: to show the last fifteen minutes in a ms-based time system:
@ -628,23 +680,24 @@ openmct.time.clockOffsets({
}) })
``` ```
Setting the clock offsets will trigger an immediate bounds change, as new bounds __Note:__ Setting the clock offsets will trigger an immediate bounds change, as
will be calculated based on the `currentValue()` of the active clock. Clock new bounds will be calculated based on the `currentValue()` of the active clock.
offsets are only relevant when a clock source is active. Clock offsets are only relevant when a clock source is active.
## Time Events ## Time Events
The time API supports the registration of listeners that will be invoked when the The time API supports the registration of listeners that will be invoked when the
application's temporal state changes. Events listeners can be registered using application's temporal state changes. Events listeners can be registered using
the `on` function. They can be deregistered using the `off` function. The arguments the `on` function. They can be deregistered using the `off` function. The arguments
accepted by the `on` and `off` functions are: accepted by the `on` and `off` functions are:
* `event`: A `string` name for the event to listen to. Event names correspond to
the property you're interested in. A [full list of time events](#list-of-time-events) * `event`: A `string` naming the event to subscribe to. Event names correspond to
the property of the Time API you're interested in. A [full list of time events](#list-of-time-events)
is provided later. is provided later.
As an example, code to listen to bounds change events might look like: As an example, the code to listen to bounds change events looks like:
``` javascript ``` javascript
openmct.time.on('bounds', function callback (bounds) { openmct.time.on('bounds', function callback (newBounds, tick) {
// Do something with new bounds // Do something with new bounds
}); });
``` ```
@ -657,17 +710,18 @@ with two arguments:
* `bounds`: A [bounds](#getting-and-setting-bounds) bounds object representing * `bounds`: A [bounds](#getting-and-setting-bounds) bounds object representing
a new time period bound by the specified start and send times. a new time period bound by the specified start and send times.
* `tick`: A `boolean` indicating whether or not this bounds change is due to a * `tick`: A `boolean` indicating whether or not this bounds change is due to a
"tick" from a [clock source](#automatically-updating-bounds-from-a-clock-source). "tick" from a [clock source](#clocks). This information can be useful when
This information can be useful when determining a strategy for fetching telemetry determining a strategy for fetching telemetry data in response to a bounds
data in response to a bounds change event. For example, if the bounds change was change event. For example, if the bounds change was automatic, and is due
automatic, and is due to a tick then it's unlikely that you would need to perform to a tick then it's unlikely that you would need to perform a historical
a historical data query. It should be sufficient to just show any new telemetry data query. It should be sufficient to just show any new telemetry received
received via subscription since the last tick, and optionally to discard any via subscription since the last tick, and optionally to discard any older
older data that now falls outside of the currently set bounds. If `tick` is false, data that now falls outside of the currently set bounds. If `tick` is false,
then the bounds change was not due to a tick, and a query for historical data then the bounds change was not due to an automatic tick, and a query for
may be necessary. historical data may be necessary, depending on your data caching strategy,
and how significantly the start bound has changed.
* `timeSystem`: Listen for changes to the active [time system](#defining-and-registering-time-systems). * `timeSystem`: Listen for changes to the active [time system](#defining-and-registering-time-systems).
The callback will be invoked with a single argument, the newly active time system. The callback will be invoked with a single argument - the newly active time system.
* `timeSystem`: The newly active [time system](#defining-and-registering-time-systems) object. * `timeSystem`: The newly active [time system](#defining-and-registering-time-systems) object.
* `clock`: Listen for changes to the active clock. When invoked, the callback * `clock`: Listen for changes to the active clock. When invoked, the callback
will be provided with the new clock. will be provided with the new clock.
@ -687,32 +741,34 @@ If activated, the time conductor must be provided with configuration options,
detailed below. detailed below.
#### Time Conductor Configuration #### Time Conductor Configuration
The time conductor is configured by specifying some options available to the user The time conductor is configured by specifying the options that will be
from the menus in the time conductor. These will determine the clocks available available to the user from the menus in the time conductor. These will determine
from the conductor, the time systems available for each clock, and some default the clocks available from the conductor, the time systems available for each
bounds and clock offsets for each combination of clock and time system. By default, clock, and some default bounds and clock offsets for each combination of clock
the conductor always supports a `fixed` mode where no clock is active. and time system. By default, the conductor always supports a `fixed` mode where
Fixed mode configuration is specified by not specifying a `clock` in the provided no clock is active. To specify configuration for fixed mode, simply leave out a
configuration. `clock` attribute in the configuration entry object.
Configuration is provided as an `array` of menu options. Each entry of the Configuration is provided as an `array` of menu options. Each entry of the
array is an object with some properties specifying configuration. The configuration array is an object with some properties specifying configuration. The configuration
options specified depend on whether or not it is for an active clock mode. options specified are slightly different depending on whether or not it is for
an active clock mode.
__Configuration for Fixed Time Mode (no active clock)__ __Configuration for Fixed Time Mode (no active clock)__
* `timeSystem`: A `string`, the key for the time system that this configuration * `timeSystem`: A `string`, the key for the time system that this configuration
relates to. relates to.
* `bounds`: A [`Time Bounds`](#time-bounds) object. These bounds will be applied when the * `bounds`: A [`Time Bounds`](#time-bounds) object. These bounds will be applied
user selects the time system specified in the previous `timeSystem` property. when the user selects the time system specified in the previous `timeSystem`
* `zoomOutLimit`: An __optional__ `number` representing the maximum span of property.
time that can be represented by the conductor. If a `zoomOutLimit` is provided, * `zoomOutLimit`: An __optional__ `number` specifying the longest period of time
then a `zoomInLimit` must also be provided. If provided, the zoom slider will that can be represented by the conductor when zooming. If a `zoomOutLimit` is
automatically become available in the Time Conductor UI. provided, then a `zoomInLimit` must also be provided. If provided, the zoom
* `zoomInLimit`: An __optional__ `number` representing the maximum span of slider will automatically become available in the Time Conductor UI.
time that can be represented by the conductor. If a `zoomInLimit` is provided, * `zoomInLimit`: An __optional__ `number` specifying the shortest period of time
then a `zoomOutLimit` must also be provided. If provided, the zoom slider will that can be represented by the conductor when zooming. If a `zoomInLimit` is
automatically become available in the Time Conductor UI. provided, then a `zoomOutLimit` must also be provided. If provided, the zoom
slider will automatically become available in the Time Conductor UI.
__Configuration for Active Clock__ __Configuration for Active Clock__
@ -722,17 +778,21 @@ relates to. Separate configuration must be provided for each time system that yo
wish to be available to users when they select the specified clock. wish to be available to users when they select the specified clock.
* `clockOffsets`: A [`clockOffsets`](#clock-offsets) object that will be * `clockOffsets`: A [`clockOffsets`](#clock-offsets) object that will be
automatically applied when the combination of clock and time system specified in automatically applied when the combination of clock and time system specified in
this configuration is selected. this configuration is selected from the UI.
#### Example conductor configuration #### Example conductor configuration
An example time conductor configuration is provided below. It sets up some An example time conductor configuration is provided below. It sets up some
default options for the [UTCTimeSystem]() and [LocalTimeSystem](), in both fixed default options for the [UTCTimeSystem](https://github.com/nasa/openmct/blob/master/src/plugins/utcTimeSystem/UTCTimeSystem.js)
mode, and for the [LocalClock](https://github.com/nasa/openmct/blob/master/src/plugins/utcTimeSystem/LocalClock.js) and [LocalTimeSystem](https://github.com/nasa/openmct/blob/master/src/plugins/localTimeSystem/LocalTimeSystem.js),
in both fixed mode, and for the [LocalClock](https://github.com/nasa/openmct/blob/master/src/plugins/utcTimeSystem/LocalClock.js)
source. In this configutation, the local clock supports both the UTCTimeSystem source. In this configutation, the local clock supports both the UTCTimeSystem
and LocalTimeSystem. Configuration for fixed bounds mode is specified by omitting and LocalTimeSystem. Configuration for fixed bounds mode is specified by omitting
a clock key. a clock key.
``` javascript ``` javascript
const ONE_YEAR = 365 * 24 * 60 * 60 * 1000;
const ONE_MINUTE = 60 * 1000;
openmct.install(openmct.plugins.Conductor({ openmct.install(openmct.plugins.Conductor({
menuOptions: [ menuOptions: [
// 'Fixed' bounds mode configuation for the UTCTimeSystem // 'Fixed' bounds mode configuation for the UTCTimeSystem

1
platform/features/conductor/core/src/ui/NumberFormat.js
View File

@ -31,6 +31,7 @@ define([], function () {
* @memberof platform/commonUI/formats * @memberof platform/commonUI/formats
*/ */
function NumberFormat() { function NumberFormat() {
this.key = 'number';
} }
NumberFormat.prototype.format = function (value) { NumberFormat.prototype.format = function (value) {