2648f01966
Disallow composition for domain object types which will not have a composition property; WTD-1221. |
||
---|---|---|
example | ||
platform | ||
.gitignore | ||
bundles.json | ||
index.html | ||
LICENSES.md | ||
pom.xml | ||
README.md | ||
test.html |
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 asuite.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
The repository for Open MCT Web includes a test suite that can be run
directly from the web browser, test.html
. This page will:
- Load
bundles.json
to determine which bundles are in the application. - Load
test/suite.json
to determine which source files are to be tested. This should contain an array of strings, where each is the name of an AMD module in the bundle's source directory. For each source file:- Code coverage instrumentation will be added, via Blanket.
- The associated test file will be loaded, via RequireJS. These will
be located in the bundle's test folder; the test runner will presume
these follow a naming convention where each module to be tested has a
corresponding test module with the suffix
Spec
in that folder.
- Jasmine will then be invoked to run all tests defined in the loaded test modules. Code coverage reporting will be displayed at the bottom of the test page.
At present, the test runner presumes that bundle conventions are followed
as above; that is, sources are contained in src
, and tests are contained
in test
. Additionally, individual test files must use the Spec
suffix
as described above.
An example of this is expressed in platform/framework
, which follows
bundle conventions.
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), and its tests can be run in-place
similarly (that is, by viewing test.html
in a 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 unit tests. This is done by running
test.html
in a PhantomJS browser-like environment. The build will fail if any tests fail. - 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
andbundles.json
).
Run as mvn clean install
.
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.)