diff --git a/docs/gendocs.js b/docs/gendocs.js index 329a9b607f..71d8ac6bf7 100644 --- a/docs/gendocs.js +++ b/docs/gendocs.js @@ -117,6 +117,22 @@ GLOBAL.window = GLOBAL.window || GLOBAL; // nomnoml expects window to be define }; return transform; } + + function strip() { + var patternsToStrip = [ + "^ + +**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* + +- [Overview](#overview) + - [Application Initialization](#application-initialization) + - [Architectural Paradigm](#architectural-paradigm) + - [Extension Categories](#extension-categories) + - [Composite Services](#composite-services) + + + # Overview The framework layer's most basic responsibility is allowing individual diff --git a/docs/src/architecture/Platform.md b/docs/src/architecture/Platform.md index a59a6ebf9c..cd788c3cd8 100644 --- a/docs/src/architecture/Platform.md +++ b/docs/src/architecture/Platform.md @@ -1,3 +1,28 @@ + + +**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* + +- [Overview](#overview) + - [Platform Architecture](#platform-architecture) + - [Application Start-up](#application-start-up) +- [Presentation Layer](#presentation-layer) + - [Angular built-ins](#angular-built-ins) + - [Domain object representation](#domain-object-representation) +- [Information Model](#information-model) + - [Capabilities and Services](#capabilities-and-services) +- [Service Infrastructure](#service-infrastructure) + - [Object Service](#object-service) + - [Model Service](#model-service) + - [Capability Service](#capability-service) + - [Telemetry Service](#telemetry-service) + - [Persistence Service](#persistence-service) + - [Action Service](#action-service) + - [View Service](#view-service) + - [Policy Service](#policy-service) + - [Type Service](#type-service) + + + # Overview The Open MCT Web platform utilizes the [framework layer](Framework.md) diff --git a/docs/src/architecture/index.md b/docs/src/architecture/index.md index fd9e0961e1..cbf73592db 100644 --- a/docs/src/architecture/index.md +++ b/docs/src/architecture/index.md @@ -1,3 +1,13 @@ + + +**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* + +- [Introduction](#introduction) +- [Overview](#overview) + - [Software Architecture](#software-architecture) + + + # Introduction The purpose of this document is to familiarize developers with the diff --git a/docs/src/guide/index.md b/docs/src/guide/index.md index c1a48797ab..2261511280 100644 --- a/docs/src/guide/index.md +++ b/docs/src/guide/index.md @@ -13,11 +13,149 @@ May 12, 2015 | 0.1 | | Victor Woeltjen June 4, 2015 | 1.0 | Name Changes | Victor Woeltjen October 4, 2015 | 1.1 | Conversion to MarkDown | Andrew Henry +# Contents + + + + + +- [Introduction](#introduction) + - [What is Open MCT Web](#what-is-open-mct-web) + - [Client-Server Relationship](#client-server-relationship) + - [Developing with Open MCT Web](#developing-with-open-mct-web) + - [Technologies](#technologies) + - [Forking](#forking) +- [Overview](#overview) + - [Framework Overview](#framework-overview) + - [Tiers](#tiers) + - [Platform Overview](#platform-overview) + - [Web Services](#web-services) + - [Glossary](#glossary) +- [Framework](#framework) + - [Bundles](#bundles) + - [Configuring Active Bundles](#configuring-active-bundles) + - [Bundle Definition](#bundle-definition) + - [Bundle Directory Structure](#bundle-directory-structure) + - [Extensions](#extensions) + - [General Extensions](#general-extensions) + - [Extension Definitions](#extension-definitions) + - [Partial Construction](#partial-construction) + - [Priority](#priority) + - [Angular Built-ins](#angular-built-ins) + - [Angular Directives](#angular-directives) + - [Angular Controllers](#angular-controllers) + - [Angular Services](#angular-services) + - [Angular Constants](#angular-constants) + - [Angular Runs](#angular-runs) + - [Angular Routes](#angular-routes) + - [Composite Services](#composite-services) +- [Core API](#core-api) + - [Domain Objects](#domain-objects) + - [Domain Object Actions](#domain-object-actions) + - [Action Contexts](#action-contexts) + - [Telemetry](#telemetry) + - [Telemetry Requests](#telemetry-requests) + - [Telemetry Responses](#telemetry-responses) + - [Telemetry Series](#telemetry-series) + - [Telemetry Metadata](#telemetry-metadata) + - [Types](#types) + - [Type Features](#type-features) + - [Type Properties](#type-properties) +- [Extension Categories](#extension-categories) + - [Actions Category](#actions-category) + - [Capabilities Category](#capabilities-category) + - [Controls Category](#controls-category) + - [Gestures Category](#gestures-category) + - [Indicators Category](#indicators-category) + - [Standard Indicators](#standard-indicators) + - [Custom Indicators](#custom-indicators) + - [Licenses Category](#licenses-category) + - [Policies Category](#policies-category) + - [Representations Category](#representations-category) + - [Representation Scope](#representation-scope) + - [Representers Category](#representers-category) + - [Roots Category](#roots-category) + - [Stylesheets Category](#stylesheets-category) + - [Templates Category](#templates-category) + - [Types Category](#types-category) + - [Versions Category](#versions-category) + - [Views Category](#views-category) + - [View Scope](#view-scope) + - [Selection State](#selection-state) +- [Directives](#directives) + - [Before Unload](#before-unload) + - [Chart](#chart) + - [Container](#container) + - [Control](#control) + - [Drag](#drag) + - [Form](#form) + - [Form Structure](#form-structure) + - [Form Controls](#form-controls) + - [Include](#include) + - [Representation](#representation) + - [Resize](#resize) + - [Scroll](#scroll) + - [Toolbar](#toolbar) + - [Toolbar Structure](#toolbar-structure) +- [Services](#services) + - [Composite Type Services](#composite-type-services) + - [Action Service](#action-service) + - [Capability Service](#capability-service) + - [Dialog Service](#dialog-service) + - [Dialog Structure](#dialog-structure) + - [Domain Object Service](#domain-object-service) + - [Gesture Service](#gesture-service) + - [Model Service](#model-service) + - [Persistence Service](#persistence-service) + - [Policy Service](#policy-service) + - [Telemetry Service](#telemetry-service) + - [Type Service](#type-service) + - [View Service](#view-service) + - [Other Services](#other-services) + - [Drag and Drop](#drag-and-drop) + - [Navigation](#navigation) + - [Now](#now) + - [Telemetry Formatter](#telemetry-formatter) + - [Telemetry Handler](#telemetry-handler) + - [Telemetry Handle](#telemetry-handle) +- [Models](#models) + - [General Metadata](#general-metadata) + - [Extension-specific Properties](#extension-specific-properties) + - [Capability-specific Properties](#capability-specific-properties) + - [View Configurations](#view-configurations) + - [Modifying Models](#modifying-models) +- [Capabilities](#capabilities) + - [Action Capability](#action-capability) + - [Composition Capability](#composition-capability) + - [Delegation Capability](#delegation-capability) + - [Editor Capability](#editor-capability) + - [Mutation Capability](#mutation-capability) + - [Mutator Function](#mutator-function) + - [Persistence Capability](#persistence-capability) + - [Relationship Capability](#relationship-capability) + - [Telemetry Capability](#telemetry-capability) + - [Type Capability](#type-capability) + - [View Capability](#view-capability) +- [Actions](#actions) + - [Action Categories](#action-categories) + - [Platform Actions](#platform-actions) +- [Policies](#policies) + - [Policy Categories](#policy-categories) +- [Build-Test-Deploy](#build-test-deploy) + - [Command-line Build](#command-line-build) + - [Test Suite](#test-suite) + - [Code Coverage](#code-coverage) + - [Deployment](#deployment) + - [Configuration](#configuration) + - [Configuration Constants](#configuration-constants) + + + # Introduction The purpose of this guide is to familiarize software developers with the Open MCT Web platform. -## What is Open MCT Web? +## What is Open MCT Web Open MCT Web is a platform for building user interface and display tools, developed at the NASA Ames Research Center in collaboration with teams at the Jet Propulsion Laboratory. It is written in HTML5, CSS3, and JavaScript, using @@ -676,7 +814,7 @@ 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 +## Domain Object Actions An `Action` is behavior that can be performed upon/using a `DomainObject`. An Action has the following interface: @@ -820,7 +958,7 @@ 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 +## Actions Category An action is a thing that can be done to or using a domain object, typically as initiated by the user. @@ -853,7 +991,7 @@ Categories supported by the platform include: * `glyph`: A single character which will be rendered in Open MCT Web's custom font set as an icon for this action. -## Capabilities +## Capabilities Category Capabilities are exposed by domain objects (e.g. via the `getCapability` method) but most commonly originate as extensions of this category. @@ -876,7 +1014,7 @@ which should return a boolean value, and will be used by the platform to filter down capabilities to those which should be exposed by specific domain objects, based on their domain object models. -## Controls +## Controls Category Controls provide options for the `mct-control` directive. @@ -911,7 +1049,7 @@ of an individual row definition. * `field`: Name of the field in `ngModel` which will hold the value for this control. -## Gestures +## Gestures Category A _gesture_ is a user action which can be taken upon a representation of a domain object. @@ -935,7 +1073,7 @@ gesture's implementation may also expose an optional `destroy()` method which will be called when the gesture should be removed, to avoid memory leaks by way of unremoved listeners. -## Indicators +## Indicators Category An indicator is an element that should appear in the status area at the bottom of a running Open MCT Web client instance. @@ -971,7 +1109,7 @@ an `mct-include` directive (so should refer to an extension of category templates .) This template will be rendered to the status area. Indicators of this variety do not need to provide an implementation. -## Licenses +## Licenses Category The extension category `licenses` can be used to add entries into the 'Licensing information' page, reachable from Open MCT Web's About dialog. @@ -985,7 +1123,7 @@ Licenses may have the following properties, all of which are strings: * `copyright`: Copyright text to display for this component. * `link`: URL to full license text. -## Policies +## Policies Category Policies are used to handle decisions made using Open MCT Web's `policyService`; examples of these decisions are determining the applicability of certain @@ -1012,7 +1150,7 @@ when and only when all policies choose to allow it. As such, policies should generally be written to reject a certain case, and allow (by returning `true`) anything else. -## Representations +## Representations Category A representation is an Angular template used to display a domain object. The `representations` extension category is used to add options for the @@ -1062,7 +1200,7 @@ representation state. * Any capabilities requested by the uses property of the representation definition. -## Representers +## Representers Category The `representers` extension category is used to add additional behavior to the `mct-representation` directive. This extension category is intended primarily @@ -1086,7 +1224,7 @@ event listeners to the element, etc. This implementation must provide a single method, `destroy()`, which will be invoked when the representer is no longer needed. -## Roots +## Roots Category The extension category `roots` is used to provide root-level domain object models. Root-level domain objects appear at the top-level of the tree hierarchy. @@ -1097,7 +1235,7 @@ Extensions of this category should have the following properties: * `id`: The machine-readable identifier for the domaiwn object being exposed. * `model`: The model, as a JSON object, for the domain object being exposed. -## Stylesheets +## Stylesheets Category The stylesheets extension category is used to add CSS files to style the application. Extension definitions for this category should include one @@ -1110,7 +1248,7 @@ include. This path is relative to the bundle's resources folder (by default, To control the order of CSS files, use priority (see the section on Extension Definitions above.) -## Templates +## Templates Category The `templates` extension category is used to expose Angular templates under symbolic identifiers. These can then be utilized using the `mct-include` @@ -1131,7 +1269,7 @@ in the bottom right, for instance.) Templates do not have implementations. -## Types +## Types Category The types extension category describes types of domain objects which may appear within Open MCT Web. @@ -1168,7 +1306,7 @@ property is described by an object containing the following properties: Types do not have implementations. -## Versions +## Versions Category The versions extension category is used to introduce line items in Open MCT Web's About dialog. These should have the following properties: @@ -1182,7 +1320,7 @@ To control the ordering of line items within the About dialog, use `priority`. This extension category does not have implementations. -## Views +## Views Category The views extension category is used to determine which options appear to the user as available views of domain objects of specific types. A view's extension @@ -1536,7 +1674,7 @@ Composite Services.) * _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 +## Composite Type Services This section describes the composite services exposed by Open MCT Web, specifically focusing on their interface and contract. @@ -1924,7 +2062,7 @@ implementation of a given capability which might not invoke the underlying service, while user code which interacts with capabilities remains indifferent to this detail. -## Action +## Action Capability The `action` capability is present for all domain objects. It allows applicable `Action` instances to be retrieved and performed for specific domain objects. @@ -1946,7 +2084,7 @@ will instead be used as the `key` of the action context. Returns a `Promise` for the result of the action that was performed, or `undefined` if no matching action was found. -## Composition +## Composition Capability The `composition` capability provides access to domain objects that are contained by this domain object. While the `composition` property of a domain @@ -1959,7 +2097,7 @@ This capability has the following interface: * `invoke()`: Returns a `Promise` for an array of `DomainObject` instances. -## Delegation +## Delegation Capability The delegation capability is used to communicate the intent of a domain object to delegate responsibilities, which would normally handled by other @@ -1980,7 +2118,7 @@ strings describing which capabilities domain objects of that type wish to delegate. If this property is not present, the delegation capability will not be present in domain objects of that type. -## Editor +## Editor Capability The editor capability is meant primarily for internal use by Edit mode, and helps to manage the behavior associated with exiting _Edit_ mode via _Save_ or @@ -1988,7 +2126,7 @@ _Cancel_. Its interface is not intended for general use. However, `domainObject.hasCapability(editor)` is a useful way of determining whether or not we are looking at an object in _Edit_ mode. -## Mutation +## Mutation Capability The `mutation` capability provides a means by which the contents of a domain object's model can be modified. This capability is provided by the platform for @@ -2005,7 +2143,7 @@ capability; other platform behavior is likely to break (either by exhibiting undesired behavior, or failing to exhibit desired behavior) if models are modified by other means. -### Mutator Function +### Mutator Function The mutator argument above is a function which will receive a cloned copy of the domain object's model as a single argument. It may return: @@ -2019,7 +2157,7 @@ for this domain object. (including any changes made in place by the mutator function) will be used as the new domain object model. -## Persistence +## Persistence Capability The persistence capability provides a mean for interacting with the underlying persistence service which stores this domain object's model. It has the @@ -2034,7 +2172,7 @@ completed. * `getSpace()`: Return the string which identifies the persistence space which stores this domain object. -## Relationship +## Relationship Capability The relationship capability provides a means for accessing other domain objects with which this domain object has some typed relationship. It has the following @@ -2051,7 +2189,7 @@ objects which has a `relationships` property in their model, whose value is an object containing key-value pairs, where keys are strings identifying relationship types, and values are arrays of domain object identifiers. -## Telemetry +## Telemetry Capability The telemetry capability provides a means for accessing telemetry data associated with a domain object. It has the following interface: @@ -2074,11 +2212,11 @@ objects which has a `telemetry` property in their model and/or type definition; this object will serve as a template for telemetry requests made using this object, and will also be returned by `getMetadata()` above. -## Type +## Type Capability The `type` capability exposes information about the domain object's type. It has the same interface as `Type`; see Core API. -## View +## View Capability The `view` capability exposes views which are applicable to a given domain object. It has the following interface: @@ -2145,7 +2283,7 @@ contained. The candidate argument is the view's extension definition; the context argument is the `DomainObject` to be viewed. -# Build, Test, Deploy +# Build-Test-Deploy Open MCT Web is designed to support a broad variety of build and deployment options. The sources can be deployed in the same directory structure used during development. A few utilities are included to support development processes. diff --git a/docs/src/tutorials/index.md b/docs/src/tutorials/index.md index 5c6ac98691..c459066969 100644 --- a/docs/src/tutorials/index.md +++ b/docs/src/tutorials/index.md @@ -14,6 +14,46 @@ July 28, 2015 | 2.0 | Telemetry adapter tutorial | Victor Woeltjen July 31, 2015 | 2.1 | Clarify telemetry adapter details | Victor Woeltjen October 14, 2015 | 2.2 | Conversion to markdown | Andrew Henry +# Contents + + + + + +- [Introduction](#introduction) + - [This document](#this-document) + - [Setting Up Open MCT Web](#setting-up-open-mct-web) + - [Prerequisites](#prerequisites) + - [Check out Open MCT Web Sources](#check-out-open-mct-web-sources) + - [Configuring Persistence](#configuring-persistence) + - [Bundle Before](#bundle-before) + - [Bundle After](#bundle-after) + - [Run a Web Server](#run-a-web-server) + - [Viewing in Browser](#viewing-in-browser) +- [Tutorials](#tutorials) + - [To-do List](#to-do-list) + - [Step 1-Create the Plugin](#step-1-create-the-plugin) + - [Before](#before) + - [After](#after) + - [Step 2-Add a Domain Object Type](#step-2-add-a-domain-object-type) + - [Step 3-Add a View](#step-3-add-a-view) + - [Step 4-Add a Controller](#step-4-add-a-controller) + - [Step 5-Support Editing](#step-5-support-editing) + - [Step 6-Customizing Look and Feel](#step-6-customizing-look-and-feel) + - [Bar Graph](#bar-graph) + - [Step 1-Define the View](#step-1-define-the-view) + - [Step 2-Add a Controller](#step-2-add-a-controller) + - [Step 3-Using Telemetry Data](#step-3-using-telemetry-data) + - [Step 4-View Configuration](#step-4-view-configuration) + - [Telemetry Adapter](#telemetry-adapter) + - [Step 0-Expose Your Telemetry](#step-0-expose-your-telemetry) + - [Step 1-Add a Top-level Object](#step-1-add-a-top-level-object) + - [Step 2-Expose the Telemetry Dictionary](#step-2-expose-the-telemetry-dictionary) + - [Step 3-Historical Telemetry](#step-3-historical-telemetry) + - [Step 4-Real-time Telemetry](#step-4-real-time-telemetry) + + + # Introduction ## This document @@ -76,7 +116,7 @@ To change this configuration, edit bundles.json (at the top level of the Open MCT Web repository) and replace platform/persistence/elastic with example/persistence. -#### Before +#### Bundle Before [ "platform/framework", @@ -102,7 +142,7 @@ example/persistence. ] __bundles.json__ -#### After +#### Bundle After [ "platform/framework", @@ -167,7 +207,7 @@ The goal of this tutorial is to add a new application feature to Open MCT Web: To-do lists. Users should be able to create and manage these to track items that they need to do. This is modelled after the to-do lists at [http://todomvc.com/](). -### Step 1. Create the Plugin +### Step 1-Create the Plugin The first step to adding a new feature to Open MCT Web is to create the plugin which will expose that feature. A plugin in Open MCT Web is represented by what @@ -254,7 +294,7 @@ should see: ...which shows that our plugin has loaded. -### Step 2. Add a Domain Object Type +### Step 2-Add a Domain Object Type Features in a Open MCT Web application are most commonly expressed as domain objects and/or views thereof. A domain object is some thing that is relevant to @@ -311,7 +351,7 @@ At this point, our to-do list doesn’t do much of anything; we can create them and give them names, but they don’t have any specific functionality attached, because we haven’t defined any yet. -### Step 3. Add a View +### Step 3-Add a View In order to allow a to-do list to be used, we need to define and display its contents. In Open MCT Web, the pattern that the user expects is that they’ll @@ -447,7 +487,7 @@ the domain object - if we click over to My Items and come back to our To-Do List, for instance, we’ll see that those check boxes have returned to their initial state. -### Step 4. Add a Controller +### Step 4-Add a Controller We need to do some scripting to add dynamic behavior to that view. In particular, we want to: @@ -613,7 +653,7 @@ able to filter down the visible list, and the changes we make will stick around if we go to My Items and come back. -### Step 5. Support Editing +### Step 5-Support Editing We now have a somewhat-functional view of our To-Do List, but we’re still missing some important functionality: Adding and removing tasks! @@ -938,7 +978,7 @@ button appear, which we can then click on to remove that task: As always in Edit mode, the user will be able to Save or Cancel any changes they have made. In terms of functionality, our To-Do List can do all the things we want, but the appearance is still lacking. In particular, we can’t distinguish our current filter choice or our current selection state. -### Step 6. Customizing Look and Feel +### Step 6-Customizing Look and Feel In this section, our goal is to: @@ -1227,7 +1267,7 @@ It is recommended that the reader completes (or is familiar with) the To-Do List tutorial before completing this tutorial, as certain concepts discussed there will be addressed in more brevity here. -### Step 1. Define the View +### Step 1-Define the View Since the goal is to introduce a new view and expose it from a plugin, we will want to create a new bundle which declares an extension of category `views`. @@ -1405,7 +1445,7 @@ _Sine Wave Generator_) as well as for _Telemetry Panel_ objects: This means that our remaining work will be to populate and position these elements based on the actual contents of the domain object. -### Step 2. Add a Controller +### Step 2-Add a Controller Our next step will be to begin dynamically populating this template’s contents. Specifically, our goals for this step will be to: @@ -1556,7 +1596,7 @@ this Telemetry Panel containing four Sine Wave Generators. ![Bar Plot](images/bar-plot-2.png) -### Step 3. Using Telemetry Data +### Step 3-Using Telemetry Data Now that our bar graph is labeled correctly, it’s time to start putting data into the view. @@ -1660,7 +1700,7 @@ When we reload Open MCT Web, our bar graph view now looks like: ![Bar Plot](images/bar-plot-3.png) -### Step 4. View Configuration +### Step 4-View Configuration The default minimum and maximum values we’ve provided happen to make sense for sine waves, but what about other values? We want to provide the user with a @@ -1849,7 +1889,7 @@ A summary of the steps we will take: * Support subscription/unsubscription to real-time streaming data. * Support historical retrieval of telemetry data. -### Step 0. Expose Your Telemetry +### Step 0-Expose Your Telemetry As a precondition to integrating telemetry data into Open MCT Web, this information needs to be available over web-based interfaces. In practice, @@ -2129,7 +2169,7 @@ like [https://www.npmjs.com/package/wscat](): Now that the example server’s interface is reasonably well-understood, a plugin can be written to adapt Open MCT Web to utilize it. -### Step 1. Add a Top-level Object +### Step 1-Add a Top-level Object Since Open MCT Web uses an “object-first” approach to accessing data, before we’ll be able to do anything with this new data source, we’ll need to have a @@ -2226,7 +2266,7 @@ __bundles.json__ Now, we have somewhere in the UI to put the contents of our telemetry dictionary. -### Step 2. Expose the Telemetry Dictionary +### Step 2-Expose the Telemetry Dictionary In order to expose the telemetry dictionary, we first need to read it from the server. Our first step will be to add a service that will handle interactions @@ -2599,7 +2639,7 @@ dictionary: Note that “My Spacecraft” has changed its name to “Example Spacecraft”, which is the name it had in the dictionary. -### Step 3. Historical Telemetry +### Step 3-Historical Telemetry After Step 2, we are able to see our dictionary in the user interface and click around our different measurements, but we don’t see any data. We need to give @@ -2870,7 +2910,7 @@ We can now visualize our data, but it doesn’t update over time - we know the server is continually producing new data, but we have to click away and come back to see it. We can fix this by adding support for telemetry subscriptions. -### Step 4. Real-time Telemetry +### Step 4-Real-time Telemetry Finally, we want to utilize the server’s ability to subscribe to telemetry from Open MCT Web. To do this, first we want to expose some new methods for diff --git a/package.json b/package.json index a1ac01f437..9ddfdefa69 100644 --- a/package.json +++ b/package.json @@ -22,7 +22,8 @@ "split": "^1.0.0", "mkdirp": "^0.5.1", "nomnoml": "^0.0.3", - "canvas": "^1.2.7" + "canvas": "^1.2.7", + "doctoc": "0.15.0" }, "scripts": { "start": "node app.js", @@ -30,8 +31,9 @@ "jshint": "jshint platform example || exit 0", "watch": "karma start", "jsdoc": "jsdoc -c jsdoc.json -r -d target/docs/api", + "doctoc": "doctoc docs/src", "otherdoc": "node docs/gendocs.js --in docs/src --out target/docs", - "docs": "npm run jsdoc ; npm run otherdoc" + "docs": "npm run jsdoc ; npm run doctoc; npm run otherdoc" }, "repository": { "type": "git",