openmct/README.md

# Open MCT Web

Open MCT Web is a web-based platform for mission operations user interface
software.

## Bundles

A bundle is a group of software components (including source code, declared
as AMD modules, as well as resources such as images and HTML templates)
that are intended to be added or removed as a single unit. A plug-in for
Open MCT Web will be expressed as a bundle; platform components are also
expressed as bundles.

A bundle is also just a directory which contains a file `bundle.json`,
which declares its contents.

The file `bundles.json` (note the plural), at the top level of the
repository, is a JSON file containing an array of all bundles (expressed as
directory names) to include in a running instance of Open MCT Web. Adding or
removing paths from this list will add or remove bundles from the running
application.

### Bundle Contents

A bundle directory will contain:

* `bundle.json`, the declaration of the bundles contents.
* A source code directory, named `src` by convention. This contains all
  JavaScript sources exposed by the bundle. These are declared as
  AMD modules.
* A directory for other resources, named `res` by convention. This
  contains all HTML templates, CSS files, images, and so forth to be
  used within a given bundle.
* A library directory, named `lib` by convention. This contains all
  external libraries used and/or exposed by the bundle.
* A test directory, named `test` by convention. This contains all unit
  tests declared for the bundle, as well as a `suite.json` that acts
  as a listing of these dependencies. See the section on unit testing
  below.

Following these bundle conventions is required, at present, to ensure
that Open MCT Web (and its build and tests) execute correctly.

## Tests

Tests are written for [Jasmine 1.3](http://jasmine.github.io/1.3/introduction.html)
and run by [Karma](http://karma-runner.github.io). To run:

`npm test`

The test suite is configured to load any scripts ending with `Spec.js` found
in the `src` hierarchy. Full configuration details are found in
`karma.conf.js`. By convention, unit test scripts should be located
alongside the units that they test; for example, `src/foo/Bar.js` would be
tested by `src/foo/BarSpec.js`. (For legacy reasons, some existing tests may
be located in separate `test` folders near the units they test, but the
naming convention is otherwise the same.)

### Test Reporting

When `npm test` is run, test results will be written as HTML to
`target/tests`. Code coverage information is written to `target/coverage`.


### Functional Testing

The tests described above are all at the unit-level; an additional
test suite using [Protractor](https://angular.github.io/protractor/)
us under development, in the `protractor` folder.

To run:

* Install protractor following the instructions above.
* `cd protractor`
* `npm install`
* `npm run all`

## Build

Open MCT Web includes a Maven command line build. Although Open MCT Web
can be run as-is using the repository contents (that is, by viewing
`index.html` in a web browser), the command
line build allows machine-driven verification and packaging.

This build will:

* Check all sources (excluding those in directories named `lib`) with
  JSLint for code style compliance. The build will fail if any sources
  do not satisfy JSLint.
* Run the [unit test suite](#tests).
* Package the application as a `war` (web archive) file. This is
  convenient for deployment on Tomcat or similar. This archive will
  include sources, resources, and libraries for bundles, as well
  as the top-level files used to initiate running of the application
  (`index.html` and `bundles.json`).

Run as `mvn clean install`.

### Building Documentation

Open MCT Web's documentation is generated by an
[npm](https://www.npmjs.com/)-based build.  It has additional dependencies that
may not be available on every platform and thus is not covered in the standard
npm install.  Ensure your system has [libcairo](http://cairographics.org/)
installed and then run the following commands:

* `npm install`
* `npm install nomnoml`
* `npm run docs`

Documentation will be generated in `target/docs`.

# Glossary

Certain terms are used throughout Open MCT Web with consistent meanings
or conventions. Any deviations from the below are issues and should be
addressed (either by updating this glossary or changing code to reflect
correct usage.) Other developer documentation, particularly in-line
documentation, may presume an understanding of these terms.

* _bundle_: A bundle is a removable, reusable grouping of software elements.
  The application is composed of bundles. Plug-ins are bundles. For more
  information, refer to framework documentation (under `platform/framework`.)
* _capability_: An object which exposes dynamic behavior or non-persistent
  state associated with a domain object.
* _composition_: In the context of a domain object, this refers to the set of
  other domain objects that compose or are contained by that object. A domain
  object's composition is the set of domain objects that should appear
  immediately beneath it in a tree hierarchy. A domain object's composition is
  described in its model as an array of id's; its composition capability
  provides a means to retrieve the actual domain object instances associated
  with these identifiers asynchronously.
* _description_: When used as an object property, this refers to the human-readable
  description of a thing; usually a single sentence or short paragraph.
  (Most often used in the context of extensions, domain
  object models, or other similar application-specific objects.)
* _domain object_: A meaningful object to the user; a distinct thing in
  the work support by Open MCT Web. Anything that appears in the left-hand
  tree is a domain object.
* _extension_: An extension is a unit of functionality exposed to the
  platform in a declarative fashion by a bundle. For more
  information, refer to framework documentation (under `platform/framework`.)
* _id_: A string which uniquely identifies a domain object.
* _key_: When used as an object property, this refers to the machine-readable
  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.)
* _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.)
* _space_: A 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.)