ExternalVendorCode/openmct
1
0
Fork 0
mirror of https://github.com/nasa/openmct.git synced 2025-06-14 21:28:12 +00:00
Code Issues Actions 9 Packages Projects Releases Wiki Activity

Added Capabilities

Browse Source
This commit is contained in:
Andrew Henry
2015-09-29 15:30:12 -07:00
parent b3fb06ba3f
commit 37dede568c
1 changed files with 237 additions and 233 deletions
Download Patch File Download Diff File Expand all files Collapse all files

432
docs/src/guide/index.md
View File

@ -1744,256 +1744,260 @@ by the `key​` argument. 
* `removeData(key)`​: Clear drag data associated with a given type, specified by  * `removeData(key)`​: Clear drag data associated with a given type, specified by 
the ​`key` argument.  the ​`key` argument. 
# Navigation ### Navigation
   
The ​navigationService​ provides information about the current navigation state of  The ​`navigationService​` provides information about the current navigation state 
the application; that is, which object is the user currently viewing? This service merely tracks this  of the application; that is, which object is the user currently viewing? This 
state and notifies listeners; it does not take immediate action when navigation changes,  service merely tracks this state and notifies listeners; it does not take 
although its listeners might.  immediate action when navigation changes, although its listeners might. 
The ​navigationService​ has the following methods: 
  The `​navigationService​` has the following methods:
* getNavigation()​: Get the current navigation state. Returns a ​DomainObject​. 
* setNavigation(domainObject)​: Set the current navigation state. Returns a  * `getNavigation()`​: Get the current navigation state. Returns a ​`DomainObject​`. 
DomainObject​.  * `setNavigation(domainObject)`​: Set the current navigation state. Returns a 
* addListener(callback)​: Listen for changes in navigation state. The provided  `DomainObject​`. 
callback​ should be a ​Function​ which takes a single ​DomainObject​ as an  * `addListener(callback)`​: Listen for changes in navigation state. The provided 
`callback​` should be a `​Function​` which takes a single `​DomainObject​` as an 
argument.  argument. 
* removeListener(callback)​: Stop listening for changes in navigation state. The  * `removeListener(callback)`​: Stop listening for changes in navigation state. 
provided ​callback​ should be a ​Function​ which has previously been passed to  The provided `​callback​` should be a `​Function​` which has previously been passed 
addListener​.  to addListener​.
 
Now ### Now
 
The service ​now​ is a function which acts as a simple wrapper for ​Date.now()​. It is  The service ​now​ is a function which acts as a simple wrapper for ​Date.now()​. It 
present mainly so that this functionality may be more easily mocked in tests for scripts which  is present mainly so that this functionality may be more easily mocked in tests 
use the current time.  for scripts which use the current time. 
 
Telemetry Formatter ### Telemetry Formatter
 
The ​telemetryFormatter​ is a utility for formatting domain and range values read  The `​telemetryFormatter​` is a utility for formatting domain and range values 
from a telemetry series.  read from a telemetry series. 
The ​telemetryFormatter​ has the following methods: 
  The ​`telemetryFormatter​` has the following methods: 
* formatDomainValue(value)​: Format the provided domain value (which will be 
* `formatDomainValue(value)`​: Format the provided domain value (which will be 
assumed to be a timestamp) for display; returns a string.  assumed to be a timestamp) for display; returns a string. 
* formatRangeValue(value)​: Format the provided range value (a number) for  * `formatRangeValue(value)`​: Format the provided range value (a number) for 
display; returns a string.  display; returns a string.
 
### Telemetry Handler
51 
Telemetry Handler
 
The ​telemetryHandler​ is a utility for retrieving telemetry data associated with  The ​telemetryHandler​ is a utility for retrieving telemetry data associated with 
domain objects; it is particularly useful for dealing with cases where the ​telemetry​ capability  domain objects; it is particularly useful for dealing with cases where the 
is delegated to contained objects (as occurs in Telemetry Panels.)  ​telemetry​ capability is delegated to contained objects (as occurs in Telemetry 
Panels.) 
The ​telemetryHandler​ has the following methods:  The ​telemetryHandler​ has the following methods: 
 
* handle(domainObject, callback, [lossless])​: Subscribe to and issue  * `handle(domainObject, callback, [lossless])`​: Subscribe to and issue future 
future requests for telemetry associated with the provided ​domainObject​, invoking the  requests for telemetry associated with the provided ​domainObject​, invoking the 
provided ​callback​ function when streaming data becomes available. Returns a  provided ​callback​ function when streaming data becomes available. Returns a 
TelemetryHandle​ (see below.)  `TelemetryHandle`​ (see below.) 
 
Telemetry Handle #### Telemetry Handle
 
A ​TelemetryHandle​ has the following methods:  A ​TelemetryHandle​ has the following methods: 
 
* getTelemetryObjects()​: Get the domain objects (as a ​DomainObject[]​) that  * `getTelemetryObjects()`​: Get the domain objects (as a ​`DomainObject[]`​) that 
have a ​telemetry​ capability and are being handled here. Note that these are looked  have a ​telemetry​ capability and are being handled here. Note that these are 
up asynchronously, so this method may return an empty array if the initial lookup is not  looked up asynchronously, so this method may return an empty array if the 
yet completed.  initial lookup is not yet completed. 
* promiseTelemetryObjects()​: As ​getTelemetryObjects()​, but returns a  * `promiseTelemetryObjects()`​: As `​getTelemetryObjects()`​, but returns a Promise​ 
Promise​ that will be fulfilled when the lookup is complete.  that will be fulfilled when the lookup is complete. 
* unsubscribe()​: Unsubscribe to streaming telemetry updates associated with this  * `unsubscribe()`​: Unsubscribe to streaming telemetry updates associated with 
handle.  this handle. 
* getDomainValue(domainObject)​: Get the most recent domain value received via a  * `getDomainValue(domainObject)`​: Get the most recent domain value received via 
streaming update for the specified ​domainObject​.  a streaming update for the specified `​domainObject​`. 
* getRangeValue(domainObject)​: Get the most recent range value received via a  * `getRangeValue(domainObject)`​: Get the most recent range value received via a 
streaming update for the specified ​domainObject​.  streaming update for the specified `​domainObject`​. 
* getMetadata()​: Get metadata (as reported by the ​getMetadata()​ method of a  * `getMetadata()`​: Get metadata (as reported by the `​getMetadata()`​ method of a 
telemetry​ capability) associated with telemetry­providing domain objects. Returns an  telemetry​ capability) associated with telemetry­providing domain objects. 
array, which is in the same order as ​getTelemetryObjects()​.  Returns an array, which is in the same order as ​getTelemetryObjects()​. 
* request(request, callback)​: Issue a new ​request​ for historical telemetry data.  * `request(request, callback)`​: Issue a new ​request​ for historical telemetry 
The provided ​callback​ will be invoked when new data becomes available, which may  data. The provided ​callback​ will be invoked when new data becomes available, 
occur multiple times (e.g. if there are multiple domain objects.) It will be invoked with the  which may occur multiple times (e.g. if there are multiple domain objects.) It 
DomainObject​ for which a new series is available, and the ​TelemetrySeries​ itself,  will be invoked with the DomainObject​ for which a new series is available, and 
in that order.  the ​TelemetrySeries​ itself, in that order. 
* getSeries(domainObject)​: Get the latest ​TelemetrySeries​ (as resulted from a  * `getSeries(domainObject)`​: Get the latest `​TelemetrySeries​` (as resulted from 
previous ​request(...)​ call) available for this domain object.  a previous ​`request(...)`​ call) available for this domain object.
 
52 
Models # Models
 
Domain object models in Open MCT Web are JavaScript objects describing the  Domain object models in Open MCT Web are JavaScript objects describing the 
persistent state of the domain objects they describe. Their contents include a mix of commonly  persistent state of the domain objects they describe. Their contents include a 
understood metadata attributes; attributes which are recognized by and/or determine the  mix of commonly understood metadata attributes; attributes which are recognized 
applicability of specific extensions; and properties specific to given types.  by and/or determine the applicability of specific extensions; and properties 
  specific to given types. 
General Metadata
  ## General Metadata
Some properties of domain object models have a ubiquitous meaning through Open  Some properties of domain object models have a ubiquitous meaning through Open 
MCT Web and can be utilized directly:  MCT Web and can be utilized directly: 
 
* name​: The human­readable name of the domain object.  * `name`​: The human­readable name of the domain object.
 
Extension-specific Properties ## Extension-specific Properties
 
Other properties of domain object models have specific meaning imposed by other  Other properties of domain object models have specific meaning imposed by other 
extensions within the Open MCT Web platform.  extensions within the Open MCT Web platform. 
 
Capability-specific Properties ### Capability-specific Properties
 
Some properties either trigger the presence/absence of certain capabilities, or are  Some properties either trigger the presence/absence of certain capabilities, or 
managed by specific capabilities:  are managed by specific capabilities:
 
* composition​: An array of domain object identifiers that represents the contents of this  * `composition​`: An array of domain object identifiers that represents the 
domain object (e.g. as will appear in the tree hierarchy.) Understood by the  contents of this domain object (e.g. as will appear in the tree hierarchy.) 
composition​ capability; the presence or absence of this property determines the  Understood by the composition​ capability; the presence or absence of this 
presence or absence of that capability. 
* modified​: The timestamp (in milliseconds since the UNIX epoch) of the last 
modification made to this domain object. Managed by the ​mutation​ capability. 
* persisted​: The timestamp (in milliseconds since the UNIX epoch) of the last time 
when changes to this domain object were persisted. Managed by the ​persistence 
capability. 
* relationships​: An object containing key­value pairs, where keys are symbolic 
identifiers for relationship types, and values are arrays of domain object identifiers. Used 
by the ​relationship​ capability; the presence or absence of this property determines 
the presence or absence of that capability. 
* telemetry​: An object which serves as a template for telemetry requests associated 
with this domain object (e.g. specifying ​source​ and ​key​; see Telemetry Requests 
53 
under Core API.) Used by the ​telemetry​ capability; the presence or absence of this 
property determines the presence or absence of that capability.  property determines the presence or absence of that capability. 
* type​: A string identifying the type of this domain object. Used by the ​type​ capability.  * `modified​`: The timestamp (in milliseconds since the UNIX epoch) of the last 
  modification made to this domain object. Managed by the ​mutation​ capability. 
View Configurations * `persisted​`: The timestamp (in milliseconds since the UNIX epoch) of the last 
  time when changes to this domain object were persisted. Managed by the 
Persistent configurations for specific views of domain objects are stored in the domain  ​persistence capability. 
object model under the property ​configurations​. This is an object containing key­value  * `relationships​`: An object containing key­value pairs, where keys are symbolic 
pairs, where keys identify the view, and values are objects containing view­specific (and  identifiers for relationship types, and values are arrays of domain object 
view­managed) configuration properties.  identifiers. Used by the ​relationship​ capability; the presence or absence of 
  this property determines the presence or absence of that capability. 
Modifying Models * `telemetry​`: An object which serves as a template for telemetry requests 
  associated with this domain object (e.g. specifying ​`source`​ and ​`key​`; see 
When interacting with a domain object’s model, it is possible to make modifications to it  Telemetry Requests under Core API.) Used by the ​telemetry​ capability; the 
directly. ​Don’t! ​These changes may not be properly detected by the platform, meaning that  presence or absence of this property determines the presence or absence of that 
other representations of the domain object may not be updated, changes may not be saved at  capability.
the expected times, and generally, that unexpected behavior may occur.  * `type`​: A string identifying the type of this domain object. Used by the ​type​ 
Instead, use the ​mutation​ capability.  capability. 
   
### View Configurations
Persistent configurations for specific views of domain objects are stored in the 
54  domain object model under the property ​configurations​. This is an object 
Capabilities containing key­value pairs, where keys identify the view, and values are objects 
containing view­specific (and view­managed) configuration properties. 
   
## Modifying Models
When interacting with a domain object’s model, it is possible to make 
modifications to it directly. __​Don't!__ ​These changes may not be properly detected 
by the platform, meaning that other representations of the domain object may not 
be updated, changes may not be saved at the expected times, and generally, that 
unexpected behavior may occur. Instead, use the `​mutation​` capability. 
# Capabilities
Dynamic behavior associated with a domain object is expressed as capabilities. A  Dynamic behavior associated with a domain object is expressed as capabilities. A 
capability is a JavaScript object with an interface that is specific to the type of capability in use.  capability is a JavaScript object with an interface that is specific to the type 
Often, there is a relationship between capabilities and services. For instance, there is an  of capability in use. 
action​ capability and an ​actionService​, and there is a ​telemetry​ capability as well as a 
telemetryService​. Typically, the pattern here is that the capability will utilize the service ​for  Often, there is a relationship between capabilities and services. For instance, 
the specific domain object​.   there is an action​ capability and an ​actionService​, and there is a ​telemetry​ 
When interacting with domain objects, it is generally preferable to use a capability  capability as well as a `telemetryService​`. Typically, the pattern here is that 
instead of a service when the option is available. Capability interfaces are typically easier to use  the capability will utilize the service ​for the specific domain object​.  
and/or more powerful in these situations. Additionally, this usage provides a more robust 
substitutability mechanism; for instance, one could configure a plugin such that it provided a  When interacting with domain objects, it is generally preferable to use a 
totally new implementation of a given capability which might not invoke the underlying service,  capability instead of a service when the option is available. Capability 
while user code which interacts with capabilities remains indifferent to this detail.  interfaces are typically easier to use and/or more powerful in these situations. 
Additionally, this usage provides a more robust substitutability mechanism; for 
instance, one could configure a plugin such that it provided a totally new 
implementation of a given capability which might not invoke the underlying 
service, while user code which interacts with capabilities remains indifferent 
to this detail. 
   
Action ## Action
 
The ​action​ capability is present for all domain objects. It allows applicable ​Action  The ​`action​` capability is present for all domain objects. It allows applicable 
instances to be retrieved and performed for specific domain objects.  ​`Action` instances to be retrieved and performed for specific domain objects. 
For example:  For example: 
domainObject.getCapability("action").perform("navigate");  `domainObject.getCapability("action").perform("navigate"); `
...will initiate a navigate action upon the domain object, if an action with key "navigate" is  ...will initiate a navigate action upon the domain object, if an action with 
defined.  key "navigate" is defined. 
   
This capability has the following interface:  This capability has the following interface: 
* `getActions(context)`​: Get the actions that are applicable in the specified 
action `context​`; the capability will fill in the `​domainObject​` field of this 
context if necessary. If context​ is specified as a string, they will instead be 
used as the ​`key`​ of the action context. Returns an array of ​`Action​` instances.
* `perform(context)​`: Perform an action. This will find and perform the first 
matching action available for the specified action ​context​, filling in the 
`​domainObject​` field as necessary. If ​`context​` is specified as a string, they 
will instead be used as the `​key​` of the action context. Returns a `​Promise​` for 
the result of the action that was performed, or `undefined` if no matching action 
was found. 
## Composition
   
* getActions(context)​: Get the actions that are applicable in the specified action  The `​composition​` capability provides access to domain objects that are 
context​; the capability will fill in the ​domainObject​ field of this context if necessary. If  contained by this domain object. While the ​`composition​` property of a domain 
context​ is specified as a string, they will instead be used as the ​key​ of the action  object’s model describes these contents (by their identifiers), the ​
context. Returns an array of ​Action​ instances.  `composition​` capability provides a means to load the corresponding 
* perform(context)​: Perform an action. This will find and perform the first matching  `​DomainObject​` instances in the same order. The absence of this property in the 
action available for the specified action ​context​, filling in the ​domainObject​ field as 
necessary. If ​context​ is specified as a string, they will instead be used as the ​key​ of 
the action context. Returns a ​Promise​ for the result of the action that was performed, or 
undefined if no matching action was found. 
 
55 
Composition
 
The ​composition​ capability provides access to domain objects that are contained by 
this domain object. While the ​composition​ property of a domain object’s model describes 
these contents (by their identifiers), the ​composition​ capability provides a means to load the 
corresponding ​DomainObject​ instances in the same order. The absence of this property in the 
model will result in the absence of this capability in the domain object.  model will result in the absence of this capability in the domain object. 
This capability has the following interface:  This capability has the following interface: 
   
* invoke()​: Returns a ​Promise​ for an array of ​DomainObject​ instances.  * `invoke()`​: Returns a `​Promise​` for an array of `​DomainObject​` instances.
## Delegation
The ​delegation​ capability is used to communicate the intent of a domain object 
to delegate responsibilities, which would normally handled by other 
capabilities, to the domain objects in its composition. 
Delegation
 
The ​delegation​ capability is used to communicate the intent of a domain object to 
delegate responsibilities, which would normally handled by other capabilities, to the domain 
objects in its composition. 
This capability has the following interface:  This capability has the following interface: 
   
* getDelegates(key)​: Returns a ​Promise​ for an array of ​DomainObject​ instances,  * `getDelegates(key)`​: Returns a ​Promise​ for an array of ​DomainObject​ instances, 
to which this domain object wishes to delegate the capability with the specified ​key​.  to which this domain object wishes to delegate the capability with the specified ​
* invoke(key)​: Alias of ​getDelegates(key)​.  key​. 
* doesDelegate(key)​: Returns ​true​ if the domain object does delegate the capability  * `invoke(key)`​: Alias of ​getDelegates(key)​. 
with the specified ​key​.   * `doesDelegate(key)`​: Returns ​true​ if the domain object does delegate the 
  capability with the specified ​key​.  
The platform implementation of the ​delegation​ capability inspects the domain object’s 
type definition for a property ​delegates​, whose value is an array of strings describing which 
capabilities domain objects of that type wish to delegate. If this property is not present, the 
delegation​ capability will not be present in domain objects of that type.  
 
 
The platform implementation of the ​delegation​ capability inspects the domain 
object’s type definition for a property ​delegates​, whose value is an array of 
strings describing which capabilities domain objects of that type wish to 
delegate. If this property is not present, the delegation​ capability will not be 
present in domain objects of that type.  
56  ## Editor
Editor
The ​editor​ capability is meant primarily for internal use by Edit mode, and 
helps to manage the behavior associated with exiting Edit mode via Save or 
Cancel. Its interface is not intended for general use. However, 
`​domainObject.hasCapability(‘editor’)`​ is a useful way of determining whether or 
not we are looking at an object in Edit mode.
   
The ​editor​ capability is meant primarily for internal use by Edit mode, and helps to  ## Mutation
manage the behavior associated with exiting Edit mode via Save or Cancel. Its interface is not 
intended for general use. However, ​domainObject.hasCapability(‘editor’)​ is a  The ​`mutation​` capability provides a means by which the contents of a domain 
useful way of determining whether or not we are looking at an object in Edit mode.  object’s model can be modified. This capability is provided by the platform for 
  all domain objects, and has the following interface:
 
Mutation * `mutate(mutator, [timestamp])`​: Modify the domain object’s model using the 
  specified `​mutator​` function. After changes are made, the ​`modified​` property of 
The ​mutation​ capability provides a means by which the contents of a domain object’s  the model will be updated with the specified ​`timestamp​`, if one was provided, 
model can be modified. This capability is provided by the platform for all domain objects, and  or with the current system time. 
has the following interface:  * `invoke(...)​`: Alias of ​`mutate​`.
 
* mutate(mutator, [timestamp])​: Modify the domain object’s model using the  Changes to domain object models should only be made via the ​`mutation​` 
specified ​mutator​ function. After changes are made, the ​modified​ property of the  capability; other platform behavior is likely to break (either by exhibiting 
model will be updated with the specified ​timestamp​, if one was provided, or with the  undesired behavior, or failing to exhibit desired behavior) if models are 
current system time.  modified by other means.
* invoke(...)​: Alias of ​mutate​. 
 
Changes to domain object models should only be made via the ​mutation​ capability; 
other platform behavior is likely to break (either by exhibiting undesired behavior, or failing to 
exhibit desired behavior) if models are modified by other means. 
 
Mutator Function
   
### Mutator Function
The ​mutator​ argument above is a function which will receive a cloned copy of the  The ​mutator​ argument above is a function which will receive a cloned copy of the 
domain object’s model as a single argument. It may return:  domain object’s model as a single argument. It may return: 
 
* A ​Promise​, in which case the resolved value of the promise will be used to determine  * A ​`Promise​`, in which case the resolved value of the promise will be used to 
which of the following forms is used.  determine which of the following forms is used. 
* Boolean ​false​, in which case the mutation is cancelled.  * Boolean ​`false​`, in which case the mutation is cancelled. 
* A JavaScript object, in which case this object will be used as the new model for this  * A JavaScript object, in which case this object will be used as the new model 
domain object.  for this domain object.
57  * No value (or, equivalently, `​undefined​`), in which case the cloned copy 
* No value (or, equivalently, ​undefined​), in which case the cloned copy (including any  (including any changes made in place by the mutator function) will be used as 
changes made in place by the mutator function) will be used as the new domain object  the new domain object model. 
model. 
  ## Persistence
Persistence
   
The ​persistence​ capability provides a mean for interacting with the underlying  The ​persistence​ capability provides a mean for interacting with the underlying 
persistence service which stores this domain object’s model. It has the following interface:  persistence service which stores this domain object’s model. It has the following interface: