From 2f4cf44229c4d345c3edb77c658de6512b39abf9 Mon Sep 17 00:00:00 2001 From: Andrew Henry Date: Thu, 24 Sep 2015 13:17:46 -0700 Subject: [PATCH] Added additional pages to developer's guide MD version --- docs/src/guide/index.md | 1468 ++++++++++++++++++++------------------- 1 file changed, 742 insertions(+), 726 deletions(-) diff --git a/docs/src/guide/index.md b/docs/src/guide/index.md index 5c30ddb8e9..25b18575b8 100644 --- a/docs/src/guide/index.md +++ b/docs/src/guide/index.md @@ -260,24 +260,24 @@ distinguish types of extensions from specific extension instances.  identifier for a specific thing in a set of things. (Most often used in the  context of extensions or other similar application­specific object sets.) This  term is chosen to avoid attaching ambiguous meanings to “id”.  -* __model__​: The persistent state associated with a domain object. A domain object's  -model is a JavaScript object which can be converted to JSON without losing  -information (that is, it contains no methods.)  -* __name__​: When used as an object property, this refers to the human­readable name  -for a thing. (Most often used in the context of extensions, domain object  +* __model__​: The persistent state associated with a domain object. A domain  +object's model is a JavaScript object which can be converted to JSON without  +losing information (that is, it contains no methods.)  +* __name__​: When used as an object property, this refers to the human­readable  +name for a thing. (Most often used in the context of extensions, domain object  models, or other similar application­specific objects.)  -* __navigation__​: Refers to the current state of the application with respect to the  -user's expressed interest in a specific domain object; e.g. when a user clicks  -on a domain object in the tree, they are ​navigating​ to it, and it is thereafter  -considered the ​navigated object (until the user makes another such choice.) This  -term is used to distinguish navigation from selection, which occurs in an  -editing context.  +* __navigation__​: Refers to the current state of the application with respect to  +the user's expressed interest in a specific domain object; e.g. when a user  +clicks on a domain object in the tree, they are ​navigating​ to it, and it is  +thereafter considered the ​navigated object (until the user makes another such  +choice.) This term is used to distinguish navigation from selection, which  +occurs in an editing context.  * __space__​: A machine­readable name used to identify a persistence store.  Interactions with persistence with generally involve a space parameter in some  form, to distinguish multiple persistence stores from one another (for cases  where there are multiple valid persistence locations available.)  -* __source__​: A machine­readable name used to identify a source of telemetry data.  -Similar to "space", this allows multiple telemetry sources to operate  +* __source__​: A machine­readable name used to identify a source of telemetry  +data. Similar to "space", this allows multiple telemetry sources to operate  side­by­side without conflicting.  # Framework @@ -292,555 +292,571 @@ plugin mechanism.    This framework layer operates on two key concepts: -* __Bundle:__ ​A bundle is a collection of related functionality that can be added to  -the application as a group. More concretely, a bundle is a directory containing  -a JSON file declaring its contents, as well as JavaScript sources, HTML  -templates, and other resources used to support that functionality. (The term  -bundle is borrowed from [OSGi](http://www.osgi.org/)​ ­ which has also inspired  -many of the concepts used in the framework layer. A familiarity with OSGi,  -particularly Declarative Services, may be useful when working with Open MCT  -Web.) -* __Extension:__ ​An extension is an individual unit of functionality. Extensions are  -collected together in bundles, and may interact with other extensions.  +* __Bundle:__ ​A bundle is a collection of related functionality that can be  +added to the application as a group. More concretely, a bundle is a directory  +containing a JSON file declaring its contents, as well as JavaScript sources,  +HTML templates, and other resources used to support that functionality. (The  +term bundle is borrowed from [OSGi](http://www.osgi.org/)​ ­ which has also  +inspired many of the concepts used in the framework layer. A familiarity with  +OSGi, particularly Declarative Services, may be useful when working with Open  +MCT Web.) +* __Extension:__ ​An extension is an individual unit of functionality. Extensions  +are collected together in bundles, and may interact with other extensions.  -The framework layer, loaded and initiated from ​`index.html`​, is the main point of  -entry for an application built on Open MCT Web. It is responsible for wiring  +The framework layer, loaded and initiated from ​`index.html`​, is the main point  +of entry for an application built on Open MCT Web. It is responsible for wiring  together the application at run time (much of this responsibility is actually  delegated to Angular); at a high­level, the framework does this by proceeding  through four stages: -1. __Loading definitions:__​ JSON declarations are loaded for all bundles which will  -constitute the application, and wrapped in a useful API for subsequent stages.  +1. __Loading definitions:__​ JSON declarations are loaded for all bundles which  +will constitute the application, and wrapped in a useful API for subsequent  +stages.  2. __Resolving extensions:__​ Any scripts which provide implementations for  extensions exposed by bundles are loaded, using Require.  -3. __Registering extensions__​ Resolved extensions are registered with Angular, such  -that they can be used by the application at run­time. This stage includes both  -registration of Angular built­ins (directives, controllers, routes, constants,  -and services) as well as registration of non­Angular extensions.  +3. __Registering extensions__​ Resolved extensions are registered with Angular,  +such that they can be used by the application at run­time. This stage includes  +both registration of Angular built­ins (directives, controllers, routes,  +constants, and services) as well as registration of non­Angular extensions.  4. __Bootstrapping__​ The Angular application is bootstrapped; at that point,  Angular takes over and populates the body of the page using the extensions that  have been registered.  -UP TO HERE - ## Bundles -The basic configurable unit of Open MCT Web is the bundle. This term has been used a  -bit already; now we’ll get to a more formal definition.  +The basic configurable unit of Open MCT Web is the bundle. This term has been  +used a bit already; now we’ll get to a more formal definition.  -A bundle is a directory which contains:  -  - ● A bundle definition; a file named ​bundle.json​.  - ● Subdirectories for sources, resources, and tests.  - ● Optionally, a ​README.md​ Markdown file describing its contents (this is not used by  - Open MCT Web in any way, but it’s a helpful convention to follow.)  -  - The bundle definition is the main point of entry for the bundle. The framework looks at  -this to determine which components need to be loaded and how they interact.  - A plugin in Open MCT Web is a bundle. The platform itself is also decomposed into  -bundles, each of which provides some category of functionality. The difference between a  -“bundle” and a “plugin” is purely a matter of the intended use; a plugin is just a bundle that is  -meant to be easily added or removed. When developing, it is typically more useful to think in  -terms of bundles.  -  -   -Configuring Active Bundles -  - To decide ​which​ bundles should be loaded, the framework loads a file named  -bundles.json​ (peer to the index.html file which serves the application) to determine which  -bundles should be loaded. This file should contain a single JSON array of strings, where each is  -the path to a bundle. These paths should not include ​bundle.json​ (this is implicit) or a trailing  -slash.  - For instance, if bundles.json contained:  -   - [  - "example/builtins",  - "example/extensions"  - ]  -   - ...then the Open MCT Web framework would look for bundle definitions at  -example/builtins/bundle.json​ and ​example/extensions/bundle.json​, relative  -to the path of ​index.html​. No other bundles would be loaded.  -  +A bundle is a directory which contains: - - 14  -Bundle Definition +* A bundle definition; a file named `​bundle.json​`. +* Subdirectories for sources, resources, and tests.  +* Optionally, a ​`README.md`​ Markdown file describing its contents (this is not  +used by Open MCT Web in any way, but it’s a helpful convention to follow.) + +The bundle definition is the main point of entry for the bundle. The framework  +looks at this to determine which components need to be loaded and how they  +interact. + +A plugin in Open MCT Web is a bundle. The platform itself is also decomposed  +into bundles, each of which provides some category of functionality. The  +difference between a _bundle_ and a _plugin_ is purely a matter of the intended  +use; a plugin is just a bundle that is meant to be easily added or removed. When  +developing, it is typically more useful to think in terms of bundles.  +   +### Configuring Active Bundles   - A bundle definition (the ​bundle.json​ file located within a bundle) contains a  -description of the bundle itself, as well as the information exposed by the bundle.  +To decide ​which​ bundles should be loaded, the framework loads a file named  +`bundles.json`​ (peer to the `index.html` file which serves the application) to  +determine which bundles should be loaded. This file should contain a single JSON  +array of strings, where each is the path to a bundle. These paths should not  +include ​bundle.json​ (this is implicit) or a trailing slash.  + +For instance, if `bundles.json` contained:  + + [  + "example/builtins",  + "example/extensions"  + ]  +   +...then the Open MCT Web framework would look for bundle definitions at  +`example/builtins/bundle.json`​ and `​example/extensions/bundle.json`​, relative  +to the path of `​index.html`​. No other bundles would be loaded.   + +### Bundle Definition   - This definition is expressed as a single JSON object with the following properties (all of  -which are optional, falling back to reasonable defaults):  +A bundle definition (the ​`bundle.json`​ file located within a bundle) contains a  +description of the bundle itself, as well as the information exposed by the  +bundle.    - ● key​: A machine­readable name for the bundle. (Currently used only in logging.)  - ● name​: A human­readable name for the bundle. (Also only used in logging.)  - ● sources​: Names a directory in which source scripts (which will implement extensions)  - are located. Defaults to “src”  - ● resources​: Names a directory in which resource files (such as HTML templates,  - images, CS files, and other non­JavaScript files needed by this bundle) are located.  - Defaults to “res”   - ● libraries​: Names a directory in which third­party libraries are located. Defaults to “lib”  - ● configuration​: A bundle’s configuration object, which should be formatted as would  - be passed to require.config (see RequireJS documentation at  - http://requirejs.org/docs/api.html​); note that only paths and shim have been tested.  - ● extensions​: An object containing key­value pairs, where keys are extension  - categories, and values are extension definitions. See the section on Extensions for more  - information.   +This definition is expressed as a single JSON object with the following  +properties (all of which are optional, falling back to reasonable defaults): + +* `key​`: A machine­readable name for the bundle. (Currently used only in  +logging.)  +* `name​`: A human­readable name for the bundle. (Also only used in logging.)  +* `sources​`: Names a directory in which source scripts (which will implement  +extensions) are located. Defaults to “src”  +* `resources​`: Names a directory in which resource files (such as HTML templates,  +images, CS files, and other non­JavaScript files needed by this bundle) are  +located. Defaults to “res”   +* `libraries`​: Names a directory in which third­party libraries are located.  +Defaults to “lib”  +* `configuration`​: A bundle’s configuration object, which should be formatted as  +would be passed to require.config (see [RequireJS documentation](http://requirejs.org/docs/api.html​) );  +note that only paths and shim have been tested.  +* `extensions`​: An object containing key­value pairs, where keys are extension  +categories, and values are extension definitions. See the section on Extensions  +for more information.   + +For example, the bundle definition for ​example/policy​ looks like:   + + { + "name": "Example Policy",  + "description": "Provides an example of using policies.",  + "sources": "src",  + "extensions": {  + "policies": [  + {  + "implementation": "ExamplePolicy.js",  + "category": "action"  + } + ]  + }  + } + +### Bundle Directory Structure   - For example, the bundle definition for ​example/policy​ looks like:  +In addition to the directories defined in the bundle definition, a bundle will  +typically contain other directories not used at run­time. Additionally, some  +useful development scripts (such as the command line build and the test suite)  +expect this directory structure to be in use, and may ignore options chosen by  +`b​undle.json`​. It is recommended that the directory structure described below be  +used for new bundles. + +* `src`​: Contains JavaScript sources for this bundle. May contain additional  +subdirectories to organize these sources; typically, these subdirectories are  +named to correspond to the extension categories they contain and/or support, but  +this is only a convention.  +* `res`​: Contains other files needed by this bundle, such as HTML templates. May  +contain additional subdirectories to organize these sources.  +* `lib`​: Contains JavaScript sources from third­party libraries. These are  +separated from bundle sources in order to ignore them during code style checking  +from the command line build. +* `test`​: Contains JavaScript sources implementing [Jasmine](http://jasmine.github.io/)  +tests, as well as a file named `​suite.json`​ describing which files to test.  +Should have the same folder structure as the `src` directory; see the section on  +automated testing for more information.    -{  -    "name": "Example Policy",  -    "description": "Provides an example of using policies.",  -    "sources": "src",  -    "extensions": {  -        "policies": [  -            {  -                "implementation": "ExamplePolicy.js",  -                "category": "action"  -            }  -        ]  -    }  -}  -  - - - 15  -Bundle Directory Structure -  - In addition to the directories defined in the bundle definition, a bundle will typically  -contain other directories not used at run­time. Additionally, some useful development scripts  -(such as the command line build and the test suite) expect this directory structure to be in use,  -and may ignore options chosen by b​ undle.json​. It is recommended that the directory  -structure described below be used for new bundles.  -  - ● src​: Contains JavaScript sources for this bundle. May contain additional subdirectories  - to organize these sources; typically, these subdirectories are named to correspond to the  - extension categories they contain and/or support, but this is only a convention.  - ● res​: Contains other files needed by this bundle, such as HTML templates. May contain  - additional subdirectories to organize these sources.  - ● lib​: Contains JavaScript sources from third­party libraries. These are separated from  - bundle sources in order to ignore them during code style checking from the command  - line build.  - ● test​: Contains JavaScript sources implementing Jasmine (http://jasmine.github.io/)  - tests, as well as a file named ​suite.json​ describing which files to test. Should have  - the same folder structure as the src directory; see the section on automated testing for  - more information.  -  - For example, the directory structure for bundle ​platform/commonUI/about ​looks  +For example, the directory structure for bundle ​`platform/commonUI/about` ​looks  like:  -   -  -  - - 16  -Extensions +INSERT DIAGRAM HERE + +## Extensions + +While bundles provide groupings of related behaviors, the individual units of  +behavior are called extensions.  + +Extensions belong to categories; an extension category is the machine­readable  +identifier used to identify groups of extensions. In the ​`extensions`​ property  +of a bundle definition, the keys are extension categories and the values are  +arrays of extension definitions.    - While bundles provide groupings of related behaviors, the individual units of behavior  -are called extensions.  - Extensions belong to categories; an extension category is the machine­readable  -identifier used to identify groups of extensions. In the ​extensions​ property of a bundle  -definition, the keys are extension categories and the values are arrays of extension definitions.  -  -General Extensions -  - Extensions are intended as a general­purpose mechanism for adding new types of  +### General Extensions + +Extensions are intended as a general­purpose mechanism for adding new types of  functionality to Open MCT Web.  - An extension category is registered with Angular under the name of the extension, plus a  -suffix of two square brackets; so, an Angular service (or, generally, any other extension) can  -access the full set of registered extensions, from all bundles, by including this string (e.g.  -types[]​ to get all type definitions) in a dependency declaration.  - As a convention, extension categories are given single­word, plural nouns for names  -within Open MCT Web (e.g. ​types​.) This convention is not enforced by the platform in any  -way. For extension categories introduced by external plugins, it is recommended to prefix the  -extension category with a vendor identifier (or similar) followed by a dot, to avoid collisions.  -  -Extension Definitions -  - The properties used in extension definitions are typically unique to each category of  -extension; a few properties have standard interpretations by the platform.  -  - ● implementation​: Identifies a JavaScript source file (in the sources folder) which  - implements this extension. This JavaScript file is expected to contain an AMD module  - (see ​http://requirejs.org/docs/whyamd.html#amd​) which gives as its result a single  - constructor function.  - ● depends​: An array of dependencies needed by this extension; these will be passed on  - to Angular’s dependency injector, ​https://docs.angularjs.org/guide/di​. By default, this is  - treated as an empty array. Note that ​depends​ does not make sense without  - implementation​ (since these dependencies will be passed to the implementation  - when it is instantiated.)  - ● priority​: A number or string indicating the priority order (see below) of this extension  - instance. Before an extension category is registered with AngularJS, the extensions of  - this category from all bundles will be concatenated into a single array, and then sorted  - by priority.  -  - 17  - Extensions do not need to have an implementation. If no implementation is provided,  -consumers of the extension category will receive the extension definition as a plain JavaScript  -object. Otherwise, they will receive the partialized (see below) constructor for that  -implementation, which will additionally have all properties from the extension definition attached.  -Partial Construction +An extension category is registered with Angular under the name of the  +extension, plus a suffix of two square brackets; so, an Angular service (or,  +generally, any other extension) can access the full set of registered  +extensions, from all bundles, by including this string (e.g. `types[]`​ to get  +all type definitions) in a dependency declaration.  + +As a convention, extension categories are given single­word, plural nouns for  +names within Open MCT Web (e.g. ​`types`​.) This convention is not enforced by the  +platform in any way. For extension categories introduced by external plugins, it  +is recommended to prefix the extension category with a vendor identifier (or  +similar) followed by a dot, to avoid collisions.    - In general, extensions are intended to be implemented as constructor functions, which  -will be used elsewhere to instantiate new objects of that type. However, the Angular­supported  -method for dependency injection is (effectively) constructor­style injection; so, both declared  -dependencies and run­time arguments are competing for space in a constructor’s arguments.  - To resolve this, the Open MCT Web framework registers extension instances in a  -partially constructed​ form. That is, the constructor exposed by the extension’s implementation is  -effectively decomposed into two calls; the first takes the dependencies, and returns the  -constructor in its second form, which takes the remaining arguments.  - This means that, when writing implementations, the constructor function should be  -written to include all declared dependencies, followed by all run­time arguments. When using  -extensions, only the run­time arguments need to be provided.  +### Extension Definitions + +The properties used in extension definitions are typically unique to each  +category of extension; a few properties have standard interpretations by the  +platform.    -Priority +* `implementation`​: Identifies a JavaScript source file (in the sources  +folder) which implements this extension. This JavaScript file is expected to  +contain an AMD module (see ​http://requirejs.org/docs/whyamd.html#amd​) which  +gives as its result a single constructor function.  +* `depends`​: An array of dependencies needed by this extension; these will be  +passed on to Angular’s [dependency injector](https://docs.angularjs.org/guide/di​)​.  +By default, this is treated as an empty array. Note that ​depends​ does not make  +sense without `implementation`​ (since these dependencies will be passed to the  +implementation when it is instantiated.)  +* `priority`​: A number or string indicating the priority order (see below) of  +this extension instance. Before an extension category is registered with  +AngularJS, the extensions of this category from all bundles will be concatenated  +into a single array, and then sorted by priority.  + +Extensions do not need to have an implementation. If no implementation is  +provided, consumers of the extension category will receive the extension  +definition as a plain JavaScript object. Otherwise, they will receive the  +partialized (see below) constructor for that implementation, which will  +additionally have all properties from the extension definition attached.  + +#### Partial Construction + +In general, extensions are intended to be implemented as constructor functions,  +which will be used elsewhere to instantiate new objects of that type. However,  +the Angular­supported method for dependency injection is (effectively)  +constructor­style injection; so, both declared dependencies and run­time  +arguments are competing for space in a constructor’s arguments.  + +To resolve this, the Open MCT Web framework registers extension instances in a  +partially constructed​ form. That is, the constructor exposed by the extension’s  +implementation is effectively decomposed into two calls; the first takes the  +dependencies, and returns the constructor in its second form, which takes the  +remaining arguments.  + +This means that, when writing implementations, the constructor function should  +be written to include all declared dependencies, followed by all run­time  +arguments. When using extensions, only the run­time arguments need to be  +provided.    - Within each extension category, registration occurs in priority order. An extension's  -priority may be specified as a ​priority​ property in its extension definition; this may be a  -number, or a symbolic string. Extensions are registered in reverse order (highest­priority first),  -and symbolic strings are mapped to the numeric values as follows:  +#### Priority + +Within each extension category, registration occurs in priority order. An  +extension's priority may be specified as a ​`priority`​ property in its extension  +definition; this may be a number, or a symbolic string. Extensions are  +registered in reverse order (highest­priority first), and symbolic strings are  +mapped to the numeric values as follows:    - ● fallback​: Negative infinity. Used for extensions that are not intended for use (that is,  - they are meant to be overridden) but are present as an option of last resort.  - ● default​: ­100. Used for extensions that are expected to be overridden, but need a  - useful default.  - ● none​: 0. Also used if no priority is specified, or if an unknown or malformed priority is  - specified.  - ● optional​: 100. Used for extensions that are meant to be used, but may be overridden.  - ● preferred​: 1000. Used for extensions that are specifically intended to be used, but still  - may be overridden in principle.  - ● mandatory​: Positive infinity. Used when an extension should definitely not be  - overridden.  +* `fallback`​: Negative infinity. Used for extensions that are not intended for  +use (that is, they are meant to be overridden) but are present as an option of  +last resort.  +* `default​`: ­100. Used for extensions that are expected to be overridden, but  +need a useful default.  +* `none`​: 0. Also used if no priority is specified, or if an unknown or  +malformed priority is specified.  +* `optional`​: 100. Used for extensions that are meant to be used, but may be  +overridden.  +* `preferred​`: 1000. Used for extensions that are specifically intended to be  +used, but still may be overridden in principle.  +* `mandatory`​: Positive infinity. Used when an extension should definitely not  +be overridden.    - These symbolic names are chosen to support usage where many extensions may satisfy  -a given need, but only one may be used; in this case, as a convention it should be the  -lowest­ordered (highest­priority) extensions available. In other cases, a full set (or multi­element  - 18  -subset) of extensions may be desired, with a specific ordering; in these cases, it is preferable to  -specify priority numerically when declaring extensions, and to understand that extensions will be  +These symbolic names are chosen to support usage where many extensions may  +satisfy a given need, but only one may be used; in this case, as a convention it  +should be the lowest­ordered (highest­priority) extensions available. In other  +cases, a full set (or multi­element subset) of extensions may be desired, with a  +specific ordering; in these cases, it is preferable to specify priority  +numerically when declaring extensions, and to understand that extensions will be  sorted according to these conventions when using them.    -Angular Built-ins +### Angular Built-ins + +Several entities supported Angular are expressed and managed as extensions in  +Open MCT Web. Specifically, these extension categories are _directives​_,  +_​controllers​_, _services​_, _​constants​_, _​runs​_, and _​routes​_.    - Several entities supported Angular are expressed and managed as extensions in Open  -MCT Web. Specifically, these extension categories are ​directives​, ​controllers​,  -services​, ​constants​, ​runs​, and ​routes​.  +#### Angular Directives + +New [directives](​https://docs.angularjs.org/guide/directive​) may be  +registered as extensions of the ​directives​ category. Implementations of  +directives in this category should take only dependencies as arguments, and  +should return a directive definition object.  + +The directive’s name should be provided as a ​key​ property of its extension  +definition, in camel­case format.    -Directives -  - New directives (see ​https://docs.angularjs.org/guide/directive​) may be registered as  -extensions of the ​directives​ category. Implementations of directives in this category should  -take only dependencies as arguments, and should return a directive definition object.   - The directive’s name should be provided as a ​key​ property of its extension definition, in  -camel­case format.  -  -Controllers -  - New controllers (see ​https://docs.angularjs.org/guide/controller​) may be registered as  -extensions of the ​controllers​ category. The implementation is registered directly as the  -controller; its only constructor arguments are its declared dependencies.  - The directive’s identifier should be provided as a ​key​ property of its extension definition.  +#### Angular Controllers + +New [controllers](​https://docs.angularjs.org/guide/controller​) may be registered  +as extensions of the ​controllers​ category. The implementation is registered  +directly as the controller; its only constructor arguments are its declared  +dependencies.  + +The directive’s identifier should be provided as a ​key​ property of its extension  +definition.      -Services -  - New services (see ​https://docs.angularjs.org/guide/services​) may be registered as  -extensions of the ​services​ category. The implementation is registered via a service call  -(​https://docs.angularjs.org/api/auto/service/$provide#service​), so it will be instantiated with the  -new​ operator.  -  -  +#### Angular Services -Constants -  - Constant values may be registered as extensions of the ​constants​ category; see  -https://docs.angularjs.org/api/ng/type/angular.Module#constant​. These extensions have no  - 19  -implementation; instead, they should contain a property ​key​, which is the name under which the  -constant will be registered, and a property ​value​, which is the constant value that will be  -registered.  -  -  -Runs -  - In some cases, you want to register code to run as soon as the application starts; these  -can be registered as extensions of the ​runs​ category; see  -https://docs.angularjs.org/api/ng/type/angular.Module#run​. Implementations registered in this  -category will be invoked (with their declared dependencies) when the Open MCT Web  -application first starts. (Note that, in this case, the implementation is better thought of as just a  -function, as opposed to a constructor function.)  -  -  -Routes -  - Extensions of category ​routes​ will be registered with Angular’s route provider,  -https://docs.angularjs.org/api/ngRoute/provider/$routeProvider​. Extensions of this category have  -no implementations, and need only two properties in their definition:  -  - ● when​: The value that will be passed as the path argument to ​$routeProvider.when​;  - specifically, the string that will appear in the trailing part of the URL corresponding to this  - route. This property may be omitted, in which case this extension instance will be treated  - as the default route.  - ● templateUrl​: A path to the template to render for this route. Specified as a path  - relative to the bundle’s resource directory (​res​ by default.)  -  -  +New [services](https://docs.angularjs.org/guide/services​) may be registered as  +extensions of the ​services​ category. The implementation is registered via a  +[service call](​https://docs.angularjs.org/api/auto/service/$provide#service​), so  +it will be instantiated with the new​ operator.  - - 20  -Composite Services +#### Angular Constants + +Constant values may be registered as extensions of the [​constants​ category](https://docs.angularjs.org/api/ng/type/angular.Module#constant​).  +These extensions have no implementation; instead, they should contain a property  +​key​, which is the name under which the constant will be registered, and a  +property ​value​, which is the constant value that will be registered. + +#### Angular Runs + +In some cases, you want to register code to run as soon as the application  +starts; these can be registered as extensions of the [​runs​ category](https://docs.angularjs.org/api/ng/type/angular.Module#run​).  +Implementations registered in this category will be invoked (with their declared  +dependencies) when the Open MCT Web application first starts. (Note that, in  +this case, the implementation is better thought of as just a function, as  +opposed to a constructor function.) + +#### Angular Routes + +Extensions of category `​routes`​ will be registered with Angular’s [route provider](https://docs.angularjs.org/api/ngRoute/provider/$routeProvider​).  +Extensions of this category have no implementations, and need only two  +properties in their definition:    - A special category of extensions recognized by the framework are ​components​; these  -are parts of services intended to be fit together in a common pattern.  -  -   -  - Components all implement the same interface, which is the interface expected for  -services of the type that they create. Components fall into three types:  -  - ● provider​: Provides an actual implementation of the service in question.  - ● aggregator​: Makes many implementations of the service in question appear as one.  - ● decorator​: Modifies the inputs or outputs of another implementation of the service.  -  - When the framework layer encounters components, it assembles them into single  -service instances that can be referred to elsewhere as single dependencies. All providers are  -instantiated, and passed to the first available aggregator; decorators are then layered on in  -priority order to create the final form of the service.  - A component should include the following properties in its extension definition:  -  - ● provides​: The symbolic identifier for the service that will be composed. The  - fully­composed service will be registered with Angular under this name.  - ● type​: One of ​provider​, ​aggregator​, or ​decorator​ (as above)  -  - In addition to any declared dependencies, aggregators and decorators both receive one  -more argument (immediately following declared dependencies) that is provided by the  -framework. For an aggregator, this will be an array of all providers of the same service (that is,  -with matching ​provides​ properties); for a decorator, this will be whichever provider, decorator,  -or aggregator is next in the sequence of decorators.  - Services exposed by the Open MCT Web platform are often declared as composite  +* `when​`: The value that will be passed as the path argument to ​ +`$routeProvider.when`​; specifically, the string that will appear in the trailing  +part of the URL corresponding to this route. This property may be omitted, in  +which case this extension instance will be treated as the default route.  +* `templateUrl`​: A path to the template to render for this route. Specified as a  +path relative to the bundle’s resource directory (​`res​` by default.)  + +### Composite Services + +A special category of extensions recognized by the framework are ​`components`​;  +these are parts of services intended to be fit together in a common pattern.  + +INSERT DIAGRAM HERE + +Components all implement the same interface, which is the interface expected for  +services of the type that they create. Components fall into three types: + +* `provider​`: Provides an actual implementation of the service in question.  +* `aggregator`​: Makes many implementations of the service in question appear as  +one.  +* `decorator​`: Modifies the inputs or outputs of another implementation of the  +service.  + +When the framework layer encounters components, it assembles them into single  +service instances that can be referred to elsewhere as single dependencies. All  +providers are instantiated, and passed to the first available aggregator;  +decorators are then layered on in priority order to create the final form of the  +service. + +A component should include the following properties in its extension definition: + +* `provides`​: The symbolic identifier for the service that will be composed. The  + fully­composed service will be registered with Angular under this name. +* `type​`: One of `​provider`​, ​`aggregator​`, or `​decorator​` (as above)  + +In addition to any declared dependencies, aggregators and decorators both  +receive one more argument (immediately following declared dependencies) that is  +provided by the framework. For an aggregator, this will be an array of all  +providers of the same service (that is, with matching `​provides`​ properties);  +for a decorator, this will be whichever provider, decorator, or aggregator is  +next in the sequence of decorators.  + +Services exposed by the Open MCT Web platform are often declared as composite  services, as this form is open for a variety of common modifications.  - - 21  -Core API -  - Most of Open MCT Web’s relevant API is provided and/or mediated by the framework;  -that is, much of developing for Open MCT Web is a matter of adding extensions which access  -other parts of the platform by means of dependency injection.  - The core bundle (​platform/core​) introduces a few additional object types meant to  -be passed along by other services.  -  -Domain Objects -  - Domain objects are the most fundamental component of Open MCT Web’s information  -model. A domain object is some distinct thing relevant to a user’s work flow, such as a telemetry  -channel, display, or similar. Open MCT Web is a tool for viewing, browsing, manipulating, and  -otherwise interacting with a graph of domain objects.  - A domain object should be conceived of as the union of the following:  -   - ● Identifier: A machine­readable string that uniquely identifies the domain object within this  - application instance.  - ● Model: The persistent state of the domain object. A domain object’s model is a  - JavaScript object that can be losslessly converted to JSON.  - ● Capabilities: Dynamic behavior associated with the domain object. Capabilities are  - JavaScript objects which provide additional methods for interacting with the domain  - objects which expose those capabilities. Not all domain objects expose all capabilities.  -  - At run­time, a domain object has the following interface:  -  - ● getId()​: Get the identifier for this domain object.  - ● getModel()​: Get the plain state associated with this domain object. This will return a  - JavaScript object that can be losslessly converted to JSON. Note that the model  - returned here can be modified directly but should not be; instead, use the ​mutation  - capability.  - ● getCapability(key)​: Get the specified capability associated with this domain object.  - This will return a JavaScript object whose interface is specific to the type of capability  - being requested. If the requested capability is not exposed by this domain object, this  - will return ​undefined​.  - 22  - ● hasCapability(key)​: Shorthand for checking if a domain object exposes the  - requested capability.  - ● useCapability(key, arguments…)​: Shorthand for  - getCapability(key).invoke(arguments)​, with additional checking between  - calls. If the provided capability has no invoke method, the return value here functions as  - getCapability​, including returning ​undefined​ if the capability is not exposed.  -  -Actions -  - An ​Action​ is behavior that can be performed upon/using a ​DomainObject​. An Action  -has the following interface:  -  - ● perform()​: Do this action. For example, if one had an instance of a ​RemoveAction​,  - invoking its ​perform​ method would cause the domain object which exposed it to be  - removed from its container.  - ● getMetadata()​: Get metadata associated with this action. Returns an object  - containing:  - ○ name​: Human­readable name.  - ○ description​: Human­readable summary of this action.  - ○ glyph​: Single character to be displayed in Open MCT Web’s icon font set.  - ○ context​: The context in which this action is being performed (see below)  -  - Action instances are typically obtained via a domain object’s ​action​ capability.  -  -Action Contexts -  - An action context is a JavaScript object with the following properties:  -  - ● domainObject​: The domain object being acted upon.  - ● selectedObject​: Optional; the selection at the time of action (e.g. the dragged object  - in a drag­and­drop operation.)  +# Core API - - 23  -Telemetry -  - Telemetry series data in Open MCT Web is represented by a common interface, and  -packaged in a consistent manner to facilitate passing telemetry updates around multiple  -visualizations.  -  -Telemetry Requests -  - A telemetry request is a JavaScript object containing the following properties:  -  - ● source​: A machine­readable identifier for the source of this telemetry. This is useful  - when multiple distinct data sources are in use side­by­side.  - ● key​: A machine­readable identifier for a unique series of telemetry within that source.  - ● Note: This API is still under development; additional properties, such as start and end  - time, should be present in future versions of Open MCT Web.  -  - Additional properties may be included in telemetry requests which have specific  -interpretations for specific sources.  -  -Telemetry Responses -  - When returned from the ​telemetryService​ (see Services section), telemetry series  -data will be packaged in a ​source ­> key ­> TelemetrySeries​ fashion. That is,  -telemetry is passed in an object containing key­value pairs. Keys identify telemetry sources;  -values are objects containing additional key­value pairs. In this object, keys identify individual  -telemetry series (and match they ​key​ property from corresponding requests) and values are  -TelemetrySeries​ objects (see below.)  -  +Most of Open MCT Web’s relevant API is provided and/or mediated by the  +framework; that is, much of developing for Open MCT Web is a matter of adding  +extensions which access other parts of the platform by means of dependency  +injection.  - - 24  -Telemetry Series +The core bundle (`​platform/core`​) introduces a few additional object types meant  +to be passed along by other services.  + +## Domain Objects + +Domain objects are the most fundamental component of Open MCT Web’s information  +model. A domain object is some distinct thing relevant to a user’s work flow,  +such as a telemetry channel, display, or similar. Open MCT Web is a tool for  +viewing, browsing, manipulating, and otherwise interacting with a graph of  +domain objects.  + +A domain object should be conceived of as the union of the following: + +* __Identifier__: A machine­readable string that uniquely identifies the domain  +object within this application instance.  +* __Model__: The persistent state of the domain object. A domain object’s model  +is a JavaScript object that can be losslessly converted to JSON.  +* __Capabilities__: Dynamic behavior associated with the domain object.  +Capabilities are JavaScript objects which provide additional methods for  +interacting with the domain objects which expose those capabilities. Not all  +domain objects expose all capabilities.  + +At run­time, a domain object has the following interface: + +* `getId()`​: Get the identifier for this domain object.  +* `getModel()`​: Get the plain state associated with this domain object. This  +will return a JavaScript object that can be losslessly converted to JSON. Note  +that the model returned here can be modified directly but should not be;  +instead, use the ​mutation capability.  +* `getCapability(key)`​: Get the specified capability associated with this domain  +object. This will return a JavaScript object whose interface is specific to the  +type of capability being requested. If the requested capability is not exposed  +by this domain object, this will return ​undefined​. +* `hasCapability(key)`​: Shorthand for checking if a domain object exposes the  +requested capability. +* `useCapability(key, arguments…)`​: Shorthand for  +`getCapability(key).invoke(arguments)`​, with additional checking between calls.  +If the provided capability has no invoke method, the return value here functions  +as `getCapability​`, including returning ​`undefined​` if the capability is not  +exposed. + +## Actions + +An ​`Action​` is behavior that can be performed upon/using a `​DomainObject​`. An  +Action has the following interface: + +* `perform()`​: Do this action. For example, if one had an instance of a  +`​RemoveAction​`, invoking its ​perform​ method would cause the domain object which  +exposed it to be removed from its container. +* `getMetadata()`​: Get metadata associated with this action. Returns an object  +containing:  + * `name`​: Human­readable name. + * `description`​: Human­readable summary of this action.  + * `glyph​`: Single character to be displayed in Open MCT Web’s icon font set.  + * `context`​: The context in which this action is being performed (see below) + +Action instances are typically obtained via a domain object’s `​action​`  +capability.    - A telemetry series is a specific sequence of data, typically associated with a specific  -instrument. Telemetry is modeled as an ordered sequence of domain and range values, where  -domain values must be non­decreasing but range values do not. (Typically, domain values are  -interpreted as UTC timestamps in milliseconds relative to the UNIX epoch.) A series must have  -at least one domain and one range, and may have more than one.  - Telemetry series data in Open MCT Web is expressed via the following  -TelemetrySeries​ interface:  +### Action Contexts + +An action context is a JavaScript object with the following properties:  + +* `domainObject​`: The domain object being acted upon.  +* `selectedObject`​: Optional; the selection at the time of action (e.g. the  +dragged object in a drag­and­drop operation.) + +## Telemetry + +Telemetry series data in Open MCT Web is represented by a common interface, and  +packaged in a consistent manner to facilitate passing telemetry updates around  +multiple visualizations.    - ● getPointCount()​: Returns the number of unique points/samples in this series.  - ● getDomainValue(index, [domain]):​ Get the domain value at the specified  - index​. If a second ​domain​ argument is provided, this is taken as a string identifier  - indicating which domain option (of, presumably, multiple) should be returned.  - ● getRangeValue(index, [range]):​ Get the domain value at the specified ​index​.  - If a second ​range​ argument is provided, this is taken as a string identifier indicating  - which range option (of, presumably, multiple) should be returned.  +### Telemetry Requests + +A telemetry request is a JavaScript object containing the following properties:  + +* `source​`: A machine­readable identifier for the source of this telemetry. This  +is useful when multiple distinct data sources are in use side­by­side.  +* `key​`: A machine­readable identifier for a unique series of telemetry within  +that source.  +* _Note: This API is still under development; additional properties, such as  +start and end time, should be present in future versions of Open MCT Web._  + +Additional properties may be included in telemetry requests which have specific  +interpretations for specific sources. + +### Telemetry Responses + +When returned from the `​telemetryService​` (see [Services](#Services) section),  +telemetry series data will be packaged in a ​`source ­> key ­> TelemetrySeries​`  +fashion. That is, telemetry is passed in an object containing key­value pairs.  +Keys identify telemetry sources; values are objects containing additional  +key­value pairs. In this object, keys identify individual telemetry series (and  +match they ​`key​` property from corresponding requests) and values are  +`TelemetrySeries​` objects (see below.)  + +### Telemetry Series + +A telemetry series is a specific sequence of data, typically associated with a  +specific instrument. Telemetry is modeled as an ordered sequence of domain and  +range values, where domain values must be non­decreasing but range values do  +not. (Typically, domain values are interpreted as UTC timestamps in milliseconds  +relative to the UNIX epoch.) A series must have at least one domain and one  +range, and may have more than one. + +Telemetry series data in Open MCT Web is expressed via the following  +`TelemetrySeries​` interface:    -Telemetry Metadata +* `getPointCount()`​: Returns the number of unique points/samples in this series.  +* `getDomainValue(index, [domain])`:​ Get the domain value at the specified index​.  +If a second ​domain​ argument is provided, this is taken as a string identifier  +indicating which domain option (of, presumably, multiple) should be returned.  +* `getRangeValue(index, [range])`:​ Get the domain value at the specified ​index​.  +If a second ​range​ argument is provided, this is taken as a string identifier  +indicating which range option (of, presumably, multiple) should be returned.    - Domain objects which have associated telemetry also expose metadata about that  -telemetry; this is retrievable via the ​getMetadata()​ of the telemetry capability. This will return  -a single JavaScript object containing the following properties:  +### Telemetry Metadata + +Domain objects which have associated telemetry also expose metadata about that  +telemetry; this is retrievable via the `​getMetadata()`​ of the telemetry  +capability. This will return a single JavaScript object containing the following  +properties:    - ● source​: The machine­readable identifier for the source of telemetry data for this object.  - ● key​: The machine­readable identifier for the individual telemetry series.  - ● domains​: An array of supported domains (see ​TelemetrySeries​ above.) Each  - domain should be expressed as an object which includes:  - ○ key​: Machine­readable identifier for this domain, as will be passed into a  - getDomainValue(index, domain)​ call.  - ○ name​: Human­readable name for this domain.  - ● ranges​: An array of supported ranges; same format as ​domains​.  -  - Note that this metadata is also used as the prototype for telemetry requests made using  -this capability.  -  -  -Types -  - A domain object’s type is represented as a ​Type​ object, which has the following  +* `source​`: The machine­readable identifier for the source of telemetry data for  +this object.  +* `key​`: The machine­readable identifier for the individual telemetry series.  +* `domains​`: An array of supported domains (see ​TelemetrySeries​ above.) Each  +domain should be expressed as an object which includes:  + * `key​`: Machine­readable identifier for this domain, as will be passed  + into a getDomainValue(index, domain)​ call.  + * `name​`: Human­readable name for this domain.  +* `ranges​`: An array of supported ranges; same format as ​domains​.  + +Note that this metadata is also used as the prototype for telemetry requests  +made using this capability.  + +## Types +A domain object’s type is represented as a ​Type​ object, which has the following  interface:  - 25  -  - ● getKey()​: Get the machine­readable identifier for this type.  - ● getName()​: Get the human­readable name for this type.  - ● getDescription()​: Get a human­readable summary of this type.  - ● getGlyph()​: Get the single character to be rendered as an icon for this type in Open  - MCT Web’s custom font set.  - ● getInitialModel()​: Get a domain object model that represents the initial state  - (before user specification of properties) for domain objects of this type.  - ● getDefinition()​: Get the extension definition for this type, as a JavaScript object.  - ● instanceOf(type)​: Check if this type is (or inherits from) a specified ​type​. This type  - can be either a string, in which case it is taken to be that type’s ​key​, or it may be a ​Type  - instance.  - ● hasFeature(feature)​: Returns a boolean value indicating whether or not this type  - supports the specified ​feature​, which is a symbolic string.  - ● getProperties()​: Get all properties associated with this type, expressed as an array  - of ​TypeProperty​ instances.  -  -Type Features -  - Features of a domain object type are expressed as symbolic string identifiers. They are  -defined in practice by usage; currently, the Open MCT Web platform only uses the ​creation  -feature to determine which domain object types should appear in the Create menu.  -  -Type Properties -  - Types declare the user­editable properties of their domain object instances in order to  -allow the forms which appear in the Create and Edit Properties dialogs to be generated by the  -platform. A ​TypeProperty​ has the following interface:  -  - ● getValue(model)​: Get the current value for this property, as it appears in the  - provided domain object ​model​.  - ● setValue(model, value)​: Set a new ​value​ for this property in the provided  - domain object ​model​.  - ● getDefinition()​: Get the raw definition for this property as a JavaScript object (as it  - was declared in this type’s extension definition.)  -Extension Categories -  - The information in this section is focused on registering new extensions of specific types;  -it does not contain a catalog of the extension instances of these categories provided by the  -platform. Relevant summaries there are provided in subsequent sections.  - 26  -  -Actions -  - An action is a thing that can be done to or using a domain object, typically as initiated by  -the user.  -  - An action’s implementation:  - ● Should take a single ​context​ argument in its constructor. (See Action Contexts, under  - Core API.)  - ● Should provide a method ​perform​, which causes the behavior associated with the  - action to occur.  - ● May provide a method ​getMetadata​, which provides metadata associated with the  - action. If omitted, one will be provided by the platform which includes metadata from the  - action’s extension definition.  - ● May provide a static method ​appliesTo(context)​ (that is, a function available as a  - property of the implementation’s constructor itself), which will be used by the platform to  - filter out actions from contexts in which they are inherently inapplicable.  -  - An action’s bundle definition (and/or ​getMetadata()​ return value) may include:  - ● category​: A string or dearray of strings identifying which category or categories an  - action falls into; used to determine when an action is displayed. Categories supported by  - the platform include:  - ○ contextual​: Actions in a context menu.  - ○ view­control​: Actions triggered by buttons in the top­right of Browse view.  - ● key​: A machine­readable identifier for this action.  - ● name​: A human­readable name for this action (e.g. to show in a menu)  - ● description​: A human­readable summary of the behavior of this action.  - ● glyph​: A single character which will be rendered in Open MCT Web’s custom font set  - as an icon for this action.  -  +* `getKey()`​: Get the machine­readable identifier for this type.  +* `getName()​`: Get the human­readable name for this type.  +* `getDescription()`​: Get a human­readable summary of this type.  +* `getGlyph()​`: Get the single character to be rendered as an icon for this type  +in Open MCT Web’s custom font set.  +* `getInitialModel()`​: Get a domain object model that represents the initial  +state (before user specification of properties) for domain objects of this type.  +* `getDefinition()​`: Get the extension definition for this type, as a JavaScript  +object.  +* `instanceOf(type)`​: Check if this type is (or inherits from) a specified ​type​.  +This type can be either a string, in which case it is taken to be that type’s  +​key​, or it may be a ​Type instance.  +* `hasFeature(feature)`​: Returns a boolean value indicating whether or not this  +type supports the specified ​feature​, which is a symbolic string.  +* `getProperties()​`: Get all properties associated with this type, expressed as  +an array of ​TypeProperty​ instances.    +### Type Features +Features of a domain object type are expressed as symbolic string identifiers.  +They are defined in practice by usage; currently, the Open MCT Web platform only  +uses the ​creation feature to determine which domain object types should appear  +in the Create menu.  +  +### Type Properties + +Types declare the user­editable properties of their domain object instances in  +order to allow the forms which appear in the Create and Edit Properties dialogs  +to be generated by the platform. A ​TypeProperty​ has the following interface: + +* `getValue(model)`​: Get the current value for this property, as it appears in  +the provided domain object ​model​.  +* `setValue(model, value)`​: Set a new ​value​ for this property in the provided  +domain object ​model​.  +* `getDefinition()​`: Get the raw definition for this property as a JavaScript  +object (as it was declared in this type’s extension definition.)  + +#Extension Categories + +The information in this section is focused on registering new extensions of  +specific types; it does not contain a catalog of the extension instances of  +these categories provided by the platform. Relevant summaries there are provided  +in subsequent sections. +  +## Actions + +An action is a thing that can be done to or using a domain object, typically as  +initiated by the user.  + +An action’s implementation: + +* Should take a single `​context​` argument in its constructor. (See Action  +Contexts, under Core API.)  +* Should provide a method ​`perform​`, which causes the behavior associated with  +the action to occur.  +* May provide a method `​getMetadata​`, which provides metadata associated with  +the action. If omitted, one will be provided by the platform which includes  +metadata from the action’s extension definition. +* May provide a static method ​`appliesTo(context)`​ (that is, a function  +available as a property of the implementation’s constructor itself), which will  +be used by the platform to filter out actions from contexts in which they are  +inherently inapplicable. + +An action’s bundle definition (and/or `​getMetadata()`​ return value) may include:  +* `category​`: A string or dearray of strings identifying which category or  +categories an action falls into; used to determine when an action is displayed.  +Categories supported by the platform include:  + * `contextual​`: Actions in a context menu.  + * `view­control​`: Actions triggered by buttons in the top­right of Browse view.  +* `key​`: A machine­readable identifier for this action.  +* `name​`: A human­readable name for this action (e.g. to show in a menu)  +* `description​`: A human­readable summary of the behavior of this action.  +* `glyph`​: A single character which will be rendered in Open MCT Web’s custom font  +set as an icon for this action.  27  Capabilities @@ -869,41 +885,41 @@ Controls   Four standard control types are included in the forms bundle:    - ● textfield​: An area to enter plain text.  - ● select​: A drop­down list of options.  - ● checkbox​: A box which may be checked/unchecked.  - ● color​: A color picker.  - ● button​: A button.  - ● datetime​: An input for UTC date/time entry; gives result as a UNIX timestamp, in  + * textfield​: An area to enter plain text.  + * select​: A drop­down list of options.  + * checkbox​: A box which may be checked/unchecked.  + * color​: A color picker.  + * button​: A button.  + * datetime​: An input for UTC date/time entry; gives result as a UNIX timestamp, in  milliseconds since start of 1970, UTC.    New controls may be added as extensions of the controls category. Extensions of this  category have two properties:    - ● key​: The symbolic name for this control (matched against the control field in rows of the  + * key​: The symbolic name for this control (matched against the control field in rows of the  form structure).  - ● templateUrl​: The URL to the control's Angular template, relative to the resources  + * templateUrl​: The URL to the control's Angular template, relative to the resources  directory of the bundle which exposes the extension.  28    Within the template for a control, the following variables will be included in scope:    - ● ngModel​: The model where form input will be stored. Notably we also need to look at  + * ngModel​: The model where form input will be stored. Notably we also need to look at  field​ (see below) to determine which field in the model should be modified.  - ● ngRequired​: True if input is required.  - ● ngPattern​: The pattern to match against (for text entry.)  - ● options​: The options for this control, as passed from the ​options​ property of an  + * ngRequired​: True if input is required.  + * ngPattern​: The pattern to match against (for text entry.)  + * options​: The options for this control, as passed from the ​options​ property of an  individual row definition.  - ● field​: Name of the field in ​ngModel​ which will hold the value for this control.  + * field​: Name of the field in ​ngModel​ which will hold the value for this control.    Gestures   A gesture is a user action which can be taken upon a representation of a domain object.  Examples of gestures included in the platform are:    - ● drag​: For representations that can be used to initiate drag­and­drop composition.  - ● drop​: For representations that can be drop targets for drag­and­drop composition.  - ● menu​: For representations that can be used to pop up a context menu.  + * drag​: For representations that can be used to initiate drag­and­drop composition.  + * drop​: For representations that can be drop targets for drag­and­drop composition.  + * menu​: For representations that can be used to pop up a context menu.    Gesture definitions have a property ​key​ which is used as a machine­readable identifier  for the gesture (e.g. ​drag​, ​drop​, ​menu​ above.)  @@ -928,15 +944,15 @@ Standard Indicators Indicators which wish to appear in the common form of an icon­text pair should provide  implementations with the following methods:    - ● getText()​: Provides the human­readable text that will be displayed for this indicator.  - ● getGlyph()​: Provides a single­character string that will be displayed as an icon in  + * getText()​: Provides the human­readable text that will be displayed for this indicator.  + * getGlyph()​: Provides a single­character string that will be displayed as an icon in  Open MCT Web’s custom font set.  - ● getDescription()​: Provides a human­readable summary of the current state of this  + * getDescription()​: Provides a human­readable summary of the current state of this  indicator; will be displayed in a tooltip on hover.  - ● getClass()​: Get a CSS class that will be applied to this indicator.  - ● getTextClass()​: Get a CSS class that will be applied to this indicator’s text portion.  - ● getGlyphClass()​: Get a CSS class that will be applied to this indicator’s icon portion.  - ● configure()​: If present, a configuration icon will appear to the right of this indicator,  + * getClass()​: Get a CSS class that will be applied to this indicator.  + * getTextClass()​: Get a CSS class that will be applied to this indicator’s text portion.  + * getGlyphClass()​: Get a CSS class that will be applied to this indicator’s icon portion.  + * configure()​: If present, a configuration icon will appear to the right of this indicator,  and clicking it will invoke this method.    Note that all methods are optional, and are called directly from an Angular template, so  @@ -957,12 +973,12 @@ Licenses information” page, reachable from Open MCT Web’s About dialog.  Licenses may have the following properties, all of which are strings:    - ● name​: Human­readable name of the licensed component. (e.g. “AngularJS”.)  - ● version​: Human­readable version of the licensed component. (e.g. “1.2.26”.)  - ● description​: Human­readable summary of the component.  - ● author​: Name or names of entities to which authorship should be attributed.  - ● copyright​: Copyright text to display for this component.  - ● link​: URL to full license text.  + * name​: Human­readable name of the licensed component. (e.g. “AngularJS”.)  + * version​: Human­readable version of the licensed component. (e.g. “1.2.26”.)  + * description​: Human­readable summary of the component.  + * author​: Name or names of entities to which authorship should be attributed.  + * copyright​: Copyright text to display for this component.  + * link​: URL to full license text.    30    @@ -974,10 +990,10 @@ whether or not a domain object of one type can contain a domain obj the section on the Policies for an overview of Open MCT Web’s policy model.  A policy’s extension definition should include:    - ● category​: The machine­readable identifier for the type of policy decision being  + * category​: The machine­readable identifier for the type of policy decision being  supported here. For a list of categories supported by the platform, see the section on  Policies. Plugins may introduce and utilize additional policy categories not in that list.  - ● message​: Optional; a human­readable message describing the policy, intended for  + * message​: Optional; a human­readable message describing the policy, intended for  display in situations where this specific policy has disallowed something.    A policy’s implementation should include a single method, ​allow(candidate,  @@ -996,17 +1012,17 @@ directive.    A representation definition should include the following properties:    - ● key​: The machine­readable name which identifies the representation.  - ● templateUrl​: The path to the representation's Angular template. This path is relative  + * key​: The machine­readable name which identifies the representation.  + * templateUrl​: The path to the representation's Angular template. This path is relative  to the bundle's resources directory.  - ● uses​: Optional; an array of capability names. Indicates that this representation intends  + * uses​: Optional; an array of capability names. Indicates that this representation intends  to use those capabilities of a domain object (via a ​useCapability​ call), and expects to  find the latest results of that ​useCapability​ call in the scope of the presented  template (under the same name as the capability itself.) Note that, if ​useCapability  returns a promise, this will be resolved before being placed in the representation’s  scope.  31  - ● gestures​: An array of keys identifying gestures (see the ​gestures​ extension  + * gestures​: An array of keys identifying gestures (see the ​gestures​ extension  category) which should be available upon this representation. Examples of gestures  include ​drag​ (for representations that should act as draggable sources for drag­drop  operations) and ​menu​ (for representations which should show a domain­object­specific  @@ -1023,17 +1039,17 @@ https://docs.angularjs.org/guide/controller​ for more information on cont   A representation’s scope will contain:    - ● domainObject​: The represented domain object.  - ● model​: The domain object’s model.  - ● configuration​: An object containing configuration information for this representation  + * domainObject​: The represented domain object.  + * model​: The domain object’s model.  + * configuration​: An object containing configuration information for this representation  (an empty object if there is no saved configuration.) The contents of this object are  managed entirely by the view/representation which receives it.  - ● representation​: An empty object, useful as a “scratch pad” for representation state.  - ● ngModel​: An object passed through the ​ng­model​ attribute of the  + * representation​: An empty object, useful as a “scratch pad” for representation state.  + * ngModel​: An object passed through the ​ng­model​ attribute of the  mct­representation​, if any.  - ● parameters​: An object passed through the ​parameters​ attribute of the  + * parameters​: An object passed through the ​parameters​ attribute of the  mct­representation​, if any.  - ● Any capabilities requested by the ​uses​ property of the representation definition.  + * Any capabilities requested by the ​uses​ property of the representation definition.    Representers   @@ -1062,15 +1078,15 @@ Root­level domain objects appear at the top­level of the tree hierar Items” folder is added as an extension of this category.  Extensions of this category should have the following properties:    - ● id​: The machine­readable identifier for the domain object being exposed.  - ● model​: The model, as a JSON object, for the domain object being exposed.  + * id​: The machine­readable identifier for the domain object being exposed.  + * model​: The model, as a JSON object, for the domain object being exposed.    Stylesheets   The ​stylesheets​ extension category is used to add CSS files to style the application.  Extension definitions for this category should include one property:    - ● stylesheetUrl​: Path and filename, including extension, for the stylesheet to include.  + * stylesheetUrl​: Path and filename, including extension, for the stylesheet to include.  This path is relative to the bundle’s resources folder (by default, ​res​)    To control the order of CSS files, use ​priority​ (see the section on Extension  @@ -1088,9 +1104,9 @@ behaves similarly to ​ng­include​, except that it uses these symbo paths.  A template’s extension definition should include the following properties:    - ● key​: The machine­readable name which identifies this template, matched against the  + * key​: The machine­readable name which identifies this template, matched against the  value given to the key attribute of the mct­include directive.  - ● templateUrl​: The path to the relevant Angular template. This path is relative to the  + * templateUrl​: The path to the relevant Angular template. This path is relative to the  bundle's resources directory.    Note that, when multiple templates are present with the same ​key​, the one with the  @@ -1105,19 +1121,19 @@ Types within Open MCT Web.  A type’s extension definition should have the following properties:    - ● key​: The machine­readable identifier for this domain object type. Will be stored to and  + * key​: The machine­readable identifier for this domain object type. Will be stored to and  matched against the ​type​ property of domain object models.  - ● name​: The human­readable name for this domain object type.  - ● description​: A human­readable summary of this domain object type.  - ● glyph​: A single character to be rendered as an icon in Open MCT Web’s custom font  + * name​: The human­readable name for this domain object type.  + * description​: A human­readable summary of this domain object type.  + * glyph​: A single character to be rendered as an icon in Open MCT Web’s custom font  set.  - ● model​: A domain object model, used as the initial state for created domain objects of  + * model​: A domain object model, used as the initial state for created domain objects of  this type (before any properties are specified.)  - ● features​: Optional; an array of strings describing features of this domain object type.  + * features​: Optional; an array of strings describing features of this domain object type.  Currently, only ​creation​ is recognized by the platform; this is used to determine that  this type should appear in the Create menu. More generally, this is used to support the  hasFeature(...)​ method of the ​type​ capability.  - ● properties​: An array describing individual properties of this domain object (as should  + * properties​: An array describing individual properties of this domain object (as should  appear in the Create or the Edit Properties dialog.) Each property is described by an  object containing the following properties:  34  @@ -1139,9 +1155,9 @@ Versions The ​versions​ extension category is used to introduce line items in Open MCT Web’s  About dialog. These should have the following properties:    - ● name​: The name of this line item, as should appear in the left­hand side of the list of  + * name​: The name of this line item, as should appear in the left­hand side of the list of  version information in the About dialog.  - ● value​: The value which should appear to the right of the name in the About dialog.  + * value​: The value which should appear to the right of the name in the About dialog.    To control the ordering of line items within the About dialog, use ​priority​. (See  section on Extension Definitions above.)  @@ -1155,19 +1171,19 @@ available views of domain objects of specific types. A view’s extens properties as a representation (and views can be utilized via ​mct­representation​);  additionally:    - ● name​: The human­readable name for this view type.  - ● description​: A human­readable summary of this view type.  - ● glyph​: A single character to be rendered as an icon in Open MCT Web’s custom font  + * name​: The human­readable name for this view type.  + * description​: A human­readable summary of this view type.  + * glyph​: A single character to be rendered as an icon in Open MCT Web’s custom font  set.  - ● type​: Optional; if present, this representation is only applicable for domain object’s of  + * type​: Optional; if present, this representation is only applicable for domain object’s of  this type.  35  - ● needs​: Optional array of strings; if present, this representation is only applicable for  + * needs​: Optional array of strings; if present, this representation is only applicable for  domain objects which have the capabilities identified by these strings.  - ● delegation​: Optional boolean, intended to be used in conjunction with ​needs​;  if  + * delegation​: Optional boolean, intended to be used in conjunction with ​needs​;  if  present, allow required capabilities to be satisfied by means of capability delegation.  (See the ​delegation​ capability, in the Capabilities section.)  - ● toolbar​: Optional; a definition for the toolbar which may appear in a toolbar when  + * toolbar​: Optional; a definition for the toolbar which may appear in a toolbar when  using this view in Edit mode. This should be specified as a structure for ​mct­toolbar​,  with additional properties available for each item in that toolbar:  ○ property​: A property name. This will refer to a property in the view’s current  @@ -1186,9 +1202,9 @@ provided for ​representations​.    When a view is in Edit mode, this scope will additionally contain:    - ● commit()​: A function which can be invoked to mark any changes to the view’s  + * commit()​: A function which can be invoked to mark any changes to the view’s  configuration​ as ready to persist.  - ● selection​: An object representing the current selection state.  + * selection​: An object representing the current selection state.    Selection State   @@ -1204,15 +1220,15 @@ within the view. (Future versions of Open MCT Web may support multipl 36  The ​selection​ object made available during Edit mode has the following methods:    - ● proxy([object])​: Get (or set, if called with an argument) the current view proxy.   - ● select(object)​: Make this object the selected object.  - ● deselect()​: Clear the currently selected object.  - ● get()​: Get the currently selected object. Returns ​undefined​ if there is no currently  + * proxy([object])​: Get (or set, if called with an argument) the current view proxy.   + * select(object)​: Make this object the selected object.  + * deselect()​: Clear the currently selected object.  + * get()​: Get the currently selected object. Returns ​undefined​ if there is no currently  selected object.  - ● selected(object)​: Check if the JavaScript object is currently in the selection set.  + * selected(object)​: Check if the JavaScript object is currently in the selection set.  Returns ​true​ if the object is either the currently selected object, or the current view  proxy.  - ● all()​: Get an array of all objects in the selection state. Will include either or both of the  + * all()​: Get an array of all objects in the selection state. Will include either or both of the  view proxy and selected object.    @@ -1242,18 +1258,18 @@ view.  This directive is used at the element level and takes one attribute, ​draw​, which is an  Angular expression which will should evaluate to a drawing object. This drawing object should  contain the following properties:  - ● dimensions​: The size, in logical coordinates, of the chart area. A two­element  + * dimensions​: The size, in logical coordinates, of the chart area. A two­element  array or numbers.  - ● origin​: The position, in logical coordinates, of the lower­left corner of the chart  + * origin​: The position, in logical coordinates, of the lower­left corner of the chart  area. A two­element array or numbers.  - ● lines​: An array of lines (e.g. as a plot line) to draw, where each line is  + * lines​: An array of lines (e.g. as a plot line) to draw, where each line is  expressed as an object containing:  ○ buffer​: A Float32Array containing points in the line, in logical  coordinates, in sequential x,y pairs.  ○ color​: The color of the line, as a four­element RGBA array, where each  element is a number in the range of 0.0­1.0.  ○ points​: The number of points in the line.  - ● boxes​: An array of rectangles to draw in the chart area. Each is an object  + * boxes​: An array of rectangles to draw in the chart area. Each is an object  containing:  ○ start​: The first corner of the rectangle, as a two­element array of  numbers, in logical coordinates.  @@ -1289,11 +1305,11 @@ delegate to other ​mct­control​ instances, and also facilitates usa This directive supports the following additional attributes, all specified as Angular  expressions:    - ● key​: A machine­readable identifier for the specific type of control to display.  - ● options​: A set of options to display in this control.  - ● structure​: In practice, contains the definition object which describes this form row or  + * key​: A machine­readable identifier for the specific type of control to display.  + * options​: A set of options to display in this control.  + * structure​: In practice, contains the definition object which describes this form row or  toolbar item. Used to pass additional control­specific parameters.  - ● field​: The field in the ​ngModel​ under which to read/store the property associated with  + * field​: The field in the ​ngModel​ under which to read/store the property associated with  this control.    Drag @@ -1304,9 +1320,9 @@ Note that this is not “drag” in the “drag­and­drop” sense, b down, mouse move, mouse up” sense.  This takes the form of three attributes:    - ● mct­drag​: An Angular expression to evaluate during drag movement.  - ● mct­drag­down​: An Angular expression to evaluate when the drag starts.  - ● mct­drag­up​: An Angular expression to evaluate when the drag ends.  + * mct­drag​: An Angular expression to evaluate during drag movement.  + * mct­drag­down​: An Angular expression to evaluate when the drag starts.  + * mct­drag­up​: An Angular expression to evaluate when the drag ends.    In each case, a variable ​delta​ will be provided to the expression; this is a two­element  array or the horizontal and vertical pixel offset of the current mouse position relative to the  @@ -1317,12 +1333,12 @@ Form The ​mct­form​ directive is used to generate forms using a declarative structure, and to  gather back user input. It is applicable at the element level and supports the following attributes:    - ● ng­model​: The object which should contain the full form input. Individual fields in this  + * ng­model​: The object which should contain the full form input. Individual fields in this  model are bound to individual controls; the names used for these fields are provided in  the form structure (see below).  - ● structure​: The structure of the form; e.g. sections, rows, their names, and so forth.  + * structure​: The structure of the form; e.g. sections, rows, their names, and so forth.  The value of this attribute should be an Angular expression.  - ● name​: The name in the containing scope under which to publish form "meta­state", e.g.  + * name​: The name in the containing scope under which to publish form "meta­state", e.g.  $valid​, ​$dirty​, etc. This is as the behavior of ​ng­form​. Passed as plain text in the  attribute.    @@ -1371,12 +1387,12 @@ Form Controls   A few standard control types are included in the ​platform/forms​ bundle:    - ● textfield​: An area to enter plain text.  - ● select​: A drop­down list of options.  - ● checkbox​: A box which may be checked/unchecked.  - ● color​: A color picker.  - ● button​: A button.  - ● datetime​: An input for UTC date/time entry; gives result as a UNIX timestamp, in  + * textfield​: An area to enter plain text.  + * select​: A drop­down list of options.  + * checkbox​: A box which may be checked/unchecked.  + * color​: A color picker.  + * button​: A button.  + * datetime​: An input for UTC date/time entry; gives result as a UNIX timestamp, in  milliseconds since start of 1970, UTC.    Include @@ -1387,11 +1403,11 @@ will have an isolated scope.  The directive should be used at the element level and supports the following attributes,  all of which are specified as Angular expressions:    - ● key​: Machine­readable identifier for the template (of extension category ​templates​) to  + * key​: Machine­readable identifier for the template (of extension category ​templates​) to  be displayed.  - ● ng­model​: Optional; will be passed into the template’s scope as ​ngModel​. Intended  + * ng­model​: Optional; will be passed into the template’s scope as ​ngModel​. Intended  usage is for two­way bound user input.  - ● parameters​: Optional; will be passed into the template’s scope as ​parameters​.  + * parameters​: Optional; will be passed into the template’s scope as ​parameters​.  Intended usage is for template­specific display parameters.    @@ -1404,12 +1420,12 @@ represent domain objects. Usage is similar to ​mct­include​.  The directive should be used at the element level and supports the following attributes,  all of which are specified as Angular expressions:    - ● key​: Machine­readable identifier for the representation (of extension category  + * key​: Machine­readable identifier for the representation (of extension category  representations​ or ​views​) to be displayed.  - ● mct­object​: The domain object being represented.  - ● ng­model​: Optional; will be passed into the template’s scope as ​ngModel​. Intended  + * mct­object​: The domain object being represented.  + * ng­model​: Optional; will be passed into the template’s scope as ​ngModel​. Intended  usage is for two­way bound user input.  - ● parameters​: Optional; will be passed into the template’s scope as ​parameters​.  + * parameters​: Optional; will be passed into the template’s scope as ​parameters​.  Intended usage is for template­specific display parameters.    Resize @@ -1440,12 +1456,12 @@ Toolbar and to gather back user input. It is applicable at the element level and supports the following  attributes:    - ● ng­model​: The object which should contain the full toolbar input. Individual fields in this  + * ng­model​: The object which should contain the full toolbar input. Individual fields in this  model are bound to individual controls; the names used for these fields are provided in  the form structure (see below).  - ● structure​: The structure of the toolbar; e.g. sections, rows, their names, and so forth.  + * structure​: The structure of the toolbar; e.g. sections, rows, their names, and so forth.  The value of this attribute should be an Angular expression.  - ● name​: The name in the containing scope under which to publish form "meta­state", e.g.  + * name​: The name in the containing scope under which to publish form "meta­state", e.g.  $valid​, ​$dirty​, etc. This is as the behavior of ​ng­form​. Passed as plain text in the  attribute.    @@ -1484,18 +1500,18 @@ items​.          },          ... and other sections ...      ]  -}  -  -Services -  - The Open MCT Web platform provides a variety of services which can be retrieved and  +} + +# Services + +The Open MCT Web platform provides a variety of services which can be retrieved and  utilized via dependency injection. These services fall into two categories:    - ● Composite Services are defined by a set of ​components​ extensions; plugins may  + * Composite Services are defined by a set of ​components​ extensions; plugins may  introduce additional components with matching interfaces to extend or augment the  functionality of the composed service. (See the Framework section on Composite  Services.)  - ● Other services which are defined as standalone service objects; these can be utilized by  + * Other services which are defined as standalone service objects; these can be utilized by  plugins but are not intended to be modified or augmented.    Composite Services @@ -1524,7 +1540,7 @@ Action Service contexts. See Core API for additional notes on the interface for actions.  The ​actionService​ has the following interface:    - ● getActions(context)​: Returns an array of ​Action​ objects which are applicable in  + * getActions(context)​: Returns an array of ​Action​ objects which are applicable in  the specified action context.        @@ -1534,7 +1550,7 @@ Capability Service for a given domain object.  The ​capabilityService​ has the following interface:    - ● getCapabilities(model)​: Returns a an object containing key­value pairs,  + * getCapabilities(model)​: Returns a an object containing key­value pairs,  representing capabilities which should be exposed by the domain object with this model.  Keys in this object are the capability keys (as used in a ​getCapability(...)​ call)  and values are either:  @@ -1552,12 +1568,12 @@ Dialog Service The ​dialogService​ provides a means for requesting user input via a modal dialog. It  has the following interface:    - ● getUserInput(formStructure, formState)​: Prompt the user to fill out a form.  + * getUserInput(formStructure, formState)​: Prompt the user to fill out a form.  The first argument describes the form’s structure (as will be passed to ​mct­form​) while  the second argument contains the initial state of that form. This returns a ​Promise​ for  the state of the form after the user has filled it in; this promise will be rejected if the user  cancels input.  - ● getUserChoice(dialogStructure)​: Prompt the user to make a single choice from  + * getUserChoice(dialogStructure)​: Prompt the user to make a single choice from  a set of options, which (in the platform implementation) will be expressed as buttons in  the displayed dialog. Returns a ​Promise​ for the user’s choice, which will be rejected if  the user cancels input.  @@ -1568,13 +1584,13 @@ Dialog Structure The object passed as the ​dialogStructure​ to ​getUserChoice​ should have the  following properties:    - ● title​: The title to display at the top of the dialog.  - ● hint​: Short message to display below the title.  - ● template​: Identifying ​key​ (as will be passed to ​mct­include​) for the template which  + * title​: The title to display at the top of the dialog.  + * hint​: Short message to display below the title.  + * template​: Identifying ​key​ (as will be passed to ​mct­include​) for the template which  will be used to populate the inner area of the dialog.  - ● model​: Model to pass in the ​ng­model​ attribute of ​mct­include​.  - ● parameters​: Parameters to pass in the ​parameters​ attribute of ​mct­include​.  - ● options​: An array of options describing each button at the bottom. Each option may  + * model​: Model to pass in the ​ng­model​ attribute of ​mct­include​.  + * parameters​: Parameters to pass in the ​parameters​ attribute of ​mct­include​.  + * options​: An array of options describing each button at the bottom. Each option may  have the following properties:  ○ name​: Human­readable name to display in the button.  ○ key​: Machine­readable key, to pass as the result of the resolved promise when  @@ -1586,7 +1602,7 @@ Domain Object Service   The ​objectService​ provides domain object instances. It has the following interface:    - ● getObjects(ids)​: For the provided array of domain object identifiers, returns a  + * getObjects(ids)​: For the provided array of domain object identifiers, returns a  Promise​ for an object containing key­value pairs, where keys are domain object  identifiers and values are corresponding ​DomainObject​ instances. Note that the result  may contain a superset or subset of the objects requested.  @@ -1597,7 +1613,7 @@ Gesture Service The ​gestureService​ is used to attach gestures (see extension category ​gestures​)  to representations. It has the following interface:    - ● attachGestures(element, domainObject, keys)​: Attach gestures specified  + * attachGestures(element, domainObject, keys)​: Attach gestures specified  by the provided gesture ​keys​ (an array of strings) to this jqLite­wrapped HTML  element​, which represents the specified ​domainObject​. Returns an object with a  single method ​destroy()​, to be invoked when it is time to detach these gestures.  @@ -1608,7 +1624,7 @@ Model Service   The ​modelService​ provides domain object models. It has the following interface:    - ● getModels(ids)​: For the provided array of domain object identifiers, returns a  + * getModels(ids)​: For the provided array of domain object identifiers, returns a  Promise​ for an object containing key­value pairs, where keys are domain object  identifiers and values are corresponding domain object models. Note that the result may  contain a superset or subset of the models requested.  @@ -1620,21 +1636,21 @@ Persistence Service (presumably serializing/deserializing to JSON in the process.) This is used primarily to store  domain object models. It has the following interface:    - ● listSpaces()​: Returns a ​Promise​ for an array of strings identifying the different  + * listSpaces()​: Returns a ​Promise​ for an array of strings identifying the different  persistence spaces this service supports. Spaces are intended to be used to distinguish  between different underlying persistence stores, to allow these to live side by side.  - ● listObjects()​: Returns a Promise for an array of strings identifying all documents  + * listObjects()​: Returns a Promise for an array of strings identifying all documents  stored in this persistence service.  - ● createObject(space, key, value)​: Create a new document in the specified  + * createObject(space, key, value)​: Create a new document in the specified  persistence ​space​, identified by the specified ​key​, the contents of which shall match  the specified ​value​. Returns a promise that will be rejected if creation fails.  - ● readObject(space, key)​: Read an existing document in the specified persistence  + * readObject(space, key)​: Read an existing document in the specified persistence  space​, identified by the specified ​key​. Returns a promise for the specified document;  this promise will resolve to ​undefined​ if the document does not exist.  - ● updateObject(space, key, value)​: Update an existing document in the  + * updateObject(space, key, value)​: Update an existing document in the  specified persistence ​space​, identified by the specified ​key​, such that its contents  match the specified ​value​. Returns a promise that will be rejected if the update fails.  - ● deleteObject(space, key)​: Delete an existing document from the specified  + * deleteObject(space, key)​: Delete an existing document from the specified  persistence ​space​, identified by the specified ​key​. Returns a promise which will be  rejected if deletion fails.    @@ -1647,7 +1663,7 @@ Policy Service The ​policyService​ may be used to determine whether or not certain behaviors are  allowed within the application. It has the following interface:    - ● allow(category, candidate, context, [callback])​: Check if this decision  + * allow(category, candidate, context, [callback])​: Check if this decision  should be allowed. Returns a boolean. Its arguments are interpreted as:  ○ category​: A string identifying which kind of decision is being made. See the  section on Policies for categories supported by the platform; plugins may define  @@ -1676,9 +1692,9 @@ subscribing to and requesting telemetry data associated with domain obj domain objects. See the Other Services section for more information.  The ​telemetryService​ has the following interface:    - ● requestTelemetry(requests)​: Issue a request for telemetry, matching the  + * requestTelemetry(requests)​: Issue a request for telemetry, matching the  specified telemetry ​requests​. Returns a ​Promise​ for a telemetry response object.   - ● subscribe(callback, requests)​: Subscribe to real­time updates for telemetry,  + * subscribe(callback, requests)​: Subscribe to real­time updates for telemetry,  matching the specified ​requests​. The specified ​callback​ will be invoked with  telemetry response objects as they become available. This method returns a function  which can be invoked to terminate the subscription.  @@ -1688,9 +1704,9 @@ Type Service   The ​typeService​ exposes domain object types. It has the following interface:    - ● listTypes()​: Returns all domain object types supported in the application, as an  + * listTypes()​: Returns all domain object types supported in the application, as an  array of ​Type​ instances.  - ● getType(key)​: Returns the ​Type​ instance identified by the provided key, or  + * getType(key)​: Returns the ​Type​ instance identified by the provided key, or  undefined​ if no such type exists.    View Service @@ -1698,7 +1714,7 @@ View Service The ​viewService​ exposes definitions for views of domain objects. It has the following  interface:    - ● getViews(domainObject):​ Get an array of extension definitions of category ​views  + * getViews(domainObject):​ Get an array of extension definitions of category ​views  which are valid and applicable to the specified ​domainObject​.    Other Services @@ -1712,11 +1728,11 @@ as by permitting inspection during drag (which is normally prohibited  reasons.)  The ​dndService​ has the following methods:    - ● setData(key, value)​: Set drag data associated with a given type, specified by the  + * setData(key, value)​: Set drag data associated with a given type, specified by the  key​ argument.  - ● getData(key)​: Get drag data associated with a given type, specified by the ​key  + * getData(key)​: Get drag data associated with a given type, specified by the ​key  argument.  - ● removeData(key)​: Clear drag data associated with a given type, specified by the ​key  + * removeData(key)​: Clear drag data associated with a given type, specified by the ​key  argument.    @@ -1730,13 +1746,13 @@ state and notifies listeners; it does not take immediate action when  although its listeners might.  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​.  + * setNavigation(domainObject)​: Set the current navigation state. Returns a  DomainObject​.  - ● addListener(callback)​: Listen for changes in navigation state. The provided  + * addListener(callback)​: Listen for changes in navigation state. The provided  callback​ should be a ​Function​ which takes a single ​DomainObject​ as an  argument.  - ● removeListener(callback)​: Stop listening for changes in navigation state. The  + * removeListener(callback)​: Stop listening for changes in navigation state. The  provided ​callback​ should be a ​Function​ which has previously been passed to  addListener​.    @@ -1752,9 +1768,9 @@ Telemetry Formatter from a telemetry series.  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.  - ● formatRangeValue(value)​: Format the provided range value (a number) for  + * formatRangeValue(value)​: Format the provided range value (a number) for  display; returns a string.    @@ -1767,7 +1783,7 @@ domain objects; it is particularly useful for dealing with cases where is delegated to contained objects (as occurs in Telemetry Panels.)  The ​telemetryHandler​ has the following methods:    - ● handle(domainObject, callback, [lossless])​: Subscribe to and issue  + * handle(domainObject, callback, [lossless])​: Subscribe to and issue  future requests for telemetry associated with the provided ​domainObject​, invoking the  provided ​callback​ function when streaming data becomes available. Returns a  TelemetryHandle​ (see below.)  @@ -1776,27 +1792,27 @@ Telemetry Handle   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  up asynchronously, so this method may return an empty array if the initial lookup is not  yet completed.  - ● promiseTelemetryObjects()​: As ​getTelemetryObjects()​, but returns a  + * promiseTelemetryObjects()​: As ​getTelemetryObjects()​, but returns a  Promise​ 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 this  handle.  - ● getDomainValue(domainObject)​: Get the most recent domain value received via a  + * getDomainValue(domainObject)​: Get the most recent domain value received via 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​.  - ● 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  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 data.  The provided ​callback​ will be invoked when new data becomes available, which may  occur multiple times (e.g. if there are multiple domain objects.) It will be invoked with the  DomainObject​ for which a new series is available, and 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 a  previous ​request(...)​ call) available for this domain object.    52  @@ -1812,7 +1828,7 @@ General Metadata Some properties of domain object models have a ubiquitous meaning through Open  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   @@ -1824,25 +1840,25 @@ Capability-specific Properties Some properties either trigger the presence/absence of certain capabilities, or 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 contents of this  domain object (e.g. as will appear in the tree hierarchy.) Understood by the  composition​ capability; the presence or absence of this property determines the  presence or absence of that capability.  - ● modified​: The timestamp (in milliseconds since the UNIX epoch) of the last  + * 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  + * 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  + * 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  + * 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.  - ● type​: A string identifying the type of this domain object. Used by the ​type​ capability.  + * type​: A string identifying the type of this domain object. Used by the ​type​ capability.    View Configurations   @@ -1888,11 +1904,11 @@ defined.    This capability has the following interface:    - ● getActions(context)​: Get the actions that are applicable in the specified action  + * 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  + * 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  @@ -1908,7 +1924,7 @@ corresponding ​DomainObject​ instances in the same order. The absenc model will result in the absence of this capability in the domain object.  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   @@ -1917,10 +1933,10 @@ delegate responsibilities, which would normally handled by other capabil objects in its composition.  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​.  - ● invoke(key)​: Alias of ​getDelegates(key)​.  - ● doesDelegate(key)​: Returns ​true​ if the domain object does delegate the capability  + * invoke(key)​: Alias of ​getDelegates(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  @@ -1946,11 +1962,11 @@ Mutation model can be modified. This capability is provided by the platform for all domain objects, and  has the following interface:    - ● mutate(mutator, [timestamp])​: Modify the domain object’s model using the  + * mutate(mutator, [timestamp])​: Modify the domain object’s model using the  specified ​mutator​ function. After changes are made, the ​modified​ property of the  model will be updated with the specified ​timestamp​, if one was provided, or with the  current system time.  - ● invoke(...)​: Alias of ​mutate​.  + * 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  @@ -1961,13 +1977,13 @@ Mutator Function 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:    - ● 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 determine  which of the following forms is used.  - ● 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  + * 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  domain object.  57  - ● No value (or, equivalently, ​undefined​), in which case the cloned copy (including any  + * No value (or, equivalently, ​undefined​), in which case the cloned copy (including any  changes made in place by the mutator function) will be used as the new domain object  model.    @@ -1976,12 +1992,12 @@ Persistence 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:    - ● persist()​: Store the local version of this domain object, including any changes, to the  + * persist()​: Store the local version of this domain object, including any changes, to the  persistence store. Returns a ​Promise​ for a boolean value, which will be true when the  object was successfully persisted.  - ● refresh()​: Replace this domain object’s model with the most recent version from  + * refresh()​: Replace this domain object’s model with the most recent version from  persistence. Returns a ​Promise​ which will resolve when the change has completed.  - ● getSpace()​: Return the string which identifies the persistence space which stores this  + * getSpace()​: Return the string which identifies the persistence space which stores this  domain object.    Relationship @@ -1989,9 +2005,9 @@ Relationship The ​relationship​ capability provides a means for accessing other domain objects  with which this domain object has some typed relationship. It has the following interface:    - ● listRelationships()​: List all types of relationships exposed by this object. Returns  + * listRelationships()​: List all types of relationships exposed by this object. Returns  an array of strings identifying the types of relationships.  - ● getRelatedObjects(relationship)​: Get all domain objects to which this domain  + * getRelatedObjects(relationship)​: Get all domain objects to which this domain  object has the specified type of ​relationship​, which is a string identifier (as above.)  Returns a ​Promise​ for an array of ​DomainObject​ instances.    @@ -2006,17 +2022,17 @@ Telemetry The ​telemetry​ capability provides a means for accessing telemetry data associated  with a domain object. It has the following interface:    - ● requestData([request])​: Request telemetry data for this specific domain object,  + * requestData([request])​: Request telemetry data for this specific domain object,  using telemetry request parameters from the specified ​request​ if provided. This  capability will fill in telemetry request properties as­needed for this domain object.  Returns a ​Promise​ for a ​TelemetrySeries​.  - ● subscribe(callback, [request])​:  Subscribe to telemetry data updates for this  + * subscribe(callback, [request])​:  Subscribe to telemetry data updates for this  specific domain object, using telemetry request parameters from the specified ​request  if provided. This capability will fill in telemetry request properties as­needed for this  domain object. The specified ​callback​ will be invoked with ​TelemetrySeries  instances as they arrive. Returns a function which can be invoked to terminate the  subscription, or ​undefined​ if no subscription could be obtained.  - ● getMetadata()​: Get metadata associated with this domain object’s telemetry.  + * getMetadata()​: Get metadata associated with this domain object’s telemetry.    The platform implementation of the ​telemetry​ capability is present for domain objects  which has a ​telemetry​ property in their model and/or type definition; this object will serve as a  @@ -2033,7 +2049,7 @@ View The ​view​ capability exposes views which are applicable to a given domain object. It has  the following interface:    - ● invoke()​: Returns an array of extension definitions for views which are applicable for  + * invoke()​: Returns an array of extension definitions for views which are applicable for  this domain object.  59  Actions @@ -2045,8 +2061,8 @@ Action Categories The platform understands the following action categories (specifiable as the ​category  parameter of an action’s extension definition.)    - ● contextual​: Appears in context menus.  - ● view­control​: Appears in top­right area of view (as buttons) in Browse mode  + * contextual​: Appears in context menus.  + * view­control​: Appears in top­right area of view (as buttons) in Browse mode    Platform Actions   @@ -2054,19 +2070,19 @@ Platform Actions action​ capability. Unless otherwise specified, these act upon (and modify) the object  described by the ​domainObject​ property of the action’s context.    - ● cancel​: Cancel the current editing action (invoked from Edit mode.)  - ● compose​: Place an object in another object’s composition. The object to be added  + * cancel​: Cancel the current editing action (invoked from Edit mode.)  + * compose​: Place an object in another object’s composition. The object to be added  should be provided as the ​selectedObject​ of the action context.  - ● edit​: Start editing an object (enter Edit mode.)  - ● fullscreen​: Enter full screen mode.  - ● navigate​: Make this object the focus of navigation (e.g. highlight it within the tree,  + * edit​: Start editing an object (enter Edit mode.)  + * fullscreen​: Enter full screen mode.  + * navigate​: Make this object the focus of navigation (e.g. highlight it within the tree,  display a view of it to the right.)  - ● properties​: Show the “Edit Properties” dialog.  - ● remove​: Remove this domain object from its parent’s composition. (The parent, in this  + * properties​: Show the “Edit Properties” dialog.  + * remove​: Remove this domain object from its parent’s composition. (The parent, in this  case, is whichever other domain object exposed this object by way of its ​composition  capability.)  - ● save​: Save changes (invoked from Edit mode.)  - ● window​: Open this object in a new window.  + * save​: Save changes (invoked from Edit mode.)  + * window​: Open this object in a new window.    @@ -2085,12 +2101,12 @@ Policy Categories The platform understands the following policy categories (specifiable as the ​category  parameter of an policy’s extension definition.)    - ● action​: Determines whether or not a given action is allowable. The candidate  + * action​: Determines whether or not a given action is allowable. The candidate  argument here is an ​Action​; the context is its action context object.  - ● composition​: Determines whether or not domain objects of a given type are allowed  + * composition​: Determines whether or not domain objects of a given type are allowed  to contain domain objects of another type. The candidate argument here is the  container’s ​Type​; the context argument is the ​Type​ of the object to be contained.  - ● view​: Determines whether or not a view is applicable for a domain object. The  + * view​: Determines whether or not a view is applicable for a domain object. The  candidate argument is the view’s extension definition; the context argument is the  DomainObject​ to be viewed.    @@ -2112,10 +2128,10 @@ Command-line Build   Invoking ​mvn clean install​ will:    - ● Check code style using JSLint. The build will fail if JSLint raises any warnings.  - ● Run the test suite (see below.) The build will fail if any tests fail.  - ● Populate version info (e.g. commit hash, build time.)  - ● Produce a web archive (​.war​) artifact in the ​target​ directory.  + * Check code style using JSLint. The build will fail if JSLint raises any warnings.  + * Run the test suite (see below.) The build will fail if any tests fail.  + * Populate version info (e.g. commit hash, build time.)  + * Produce a web archive (​.war​) artifact in the ​target​ directory.    The produced artifact contains a subset of the repository’s own folder hierarchy, omitting  tests and example bundles.   @@ -2129,25 +2145,25 @@ test.html​, included at the top level of the source repository, can perform tests for all active bundles, as defined in ​bundle.json​.  To define tests for a bundle:    - ● Include a directory named ​test​ within that bundle.  - ● In the ​test​ directory, include a file named ​suite.json​. This will identify which scripts  + * Include a directory named ​test​ within that bundle.  + * In the ​test​ directory, include a file named ​suite.json​. This will identify which scripts  will be tested.  - ● The file ​suite.json​ must contain a JSON array of strings, where each string is the  + * The file ​suite.json​ must contain a JSON array of strings, where each string is the  name of a script to be tested. These names should include any directory paths to the  script after (but not including) the ​src​ folder, and should not include the file’s ​.js  extension. (Note that while Open MCT Web’s framework allows a different name to be  chosen for the ​src​ directory, the test runner does not: This directory must be named  src​ for the test runner to find it.)  62  - ● For each script to be tested, a corresponding test script should be located in the bundle’s  + * For each script to be tested, a corresponding test script should be located in the bundle’s  test​ directory. This should include the suffix ​Spec​ at the end of the filename (but  before the ​.js​ extension.) This test script should be an AMD module which uses the  Jasmine API to declare its test behavior. It should declare an AMD dependency on the  script to be tested, using a relative path.    For example, if writing tests for a bundle at ​example/foo​ with two scripts:  - ● example/foo/src/controllers/FooController.js  - ● example/foo/src/directives/FooDirective.js  + * example/foo/src/controllers/FooController.js  + * example/foo/src/directives/FooDirective.js    First, these scripts should be identified in ​example/foo/test/suite.json​, e.g. with  contents:  @@ -2199,9 +2215,9 @@ manner in which they are exposed) that determine how to deploy Open  One important constraint to consider in this context is the browser’s same origin policy. If  external services are not on the same apparent host and port as the client (from the perspective  of the browser) then access may be disallowed. There are two workarounds if this occurs:  - ● Make the external service appear to be on the same host/port, either by actually  + * Make the external service appear to be on the same host/port, either by actually  deploying it there, or by proxying requests to it.  - ● Enable CORS (cross­origin resource sharing) on the external service. This is only  + * Enable CORS (cross­origin resource sharing) on the external service. This is only  possible if the external service can be configured to support CORS. Care should be  exercised if choosing this option to ensure that the chosen configuration does not create  a security vulnerability.  @@ -2209,28 +2225,28 @@ of the browser) then access may be disallowed. There are two workarou Examples of deployment strategies (and the conditions under which they make the most  sense) include:    - ● If the external services that Open MCT Web will utilize are all running on Apache Tomcat  + * If the external services that Open MCT Web will utilize are all running on Apache Tomcat  (​https://tomcat.apache.org/​), then it makes sense to run Open MCT Web from the same  Tomcat instance as a separate web application. The ​.war​ artifact produced by the  command line build facilitates this deployment option. (See  https://tomcat.apache.org/tomcat­8.0­doc/deployer­howto.html ​ for general information on  deploying in Tomcat.)  - ● If a variety of external services will be running from a variety of hosts/ports, then it may  + * If a variety of external services will be running from a variety of hosts/ports, then it may  make sense to use a web server that supports proxying, such as the Apache HTTP  Server (​http://httpd.apache.org/​). In this configuration, the HTTP server would be  configured to proxy (or reverse proxy) requests at specific paths to the various external  services, while providing Open MCT Web as flat files from a different path.  64  - ● If a single server component is being developed to handle all server­side needs of an  + * If a single server component is being developed to handle all server­side needs of an  Open MCT Web instance, it can make sense to serve Open MCT Web (as flat files) from  the same component using an embedded HTTP server such as Nancy  (​http://nancyfx.org/​).  - ● If no external services are needed (or if the “external services” will just be generating flat  + * If no external services are needed (or if the “external services” will just be generating flat  files to read) it makes sense to utilize a lightweight flat file HTTP server such as Lighttpd  (​http://www.lighttpd.net/​). In this configuration, Open MCT Web sources/resources would  be placed at one path, while the files generated by the external service are placed at  another path.  - ● If all external services support CORS, it may make sense to have an HTTP server that is  + * If all external services support CORS, it may make sense to have an HTTP server that is  solely responsible for making Open MCT Web sources/resources available, and to have  Open MCT Web contact these external services directly. Again, lightweight HTTP  servers such as Lighttpd (​http://www.lighttpd.net/​) are useful in this circumstance. The  @@ -2258,25 +2274,25 @@ specifying constants with higher priority.    This permits at least three configuration approaches:    - ● Modify the constants defined in their original bundles when deploying. This is generally  + * Modify the constants defined in their original bundles when deploying. This is generally  undesirable due to the amount of manual work required and potential for error, but is  viable if there are a small number of constants to change.  - ● Add a separate configuration bundle which overrides the values of these constants. This  + * Add a separate configuration bundle which overrides the values of these constants. This  is particularly appropriate when multiple configurations (e.g. development, test,  65  production) need to be managed easily; these can be swapped quickly by changing the  set of active bundles in ​bundles.json​.  - ● Deploy Open MCT Web and its external services in such a fashion that the default paths  + * Deploy Open MCT Web and its external services in such a fashion that the default paths  to reach external services are all correct.    Configuration Constants   The following configuration constants are recognized by Open MCT Web bundles:    - ● CouchDB adapter, ​platform/persistence/coucb  + * CouchDB adapter, ​platform/persistence/coucb  ○ COUCHDB_PATH​: URL or path to the CouchDB database to be used for domain  object persistence. Should not include a trailing slash.  - ● ElasticSearch adapter, ​platform/persistence/elastic  + * ElasticSearch adapter, ​platform/persistence/elastic  ○ ELASTIC_ROOT​: URL or path to the ElasticSearch instance to be used for  domain object persistence. Should not include a trailing slash.  ○ ELASTIC_PATH​: Path relative to the ElasticSearch instance where domain