ExternalVendorCode/openmct
1
0
Fork 0
mirror of https://github.com/nasa/openmct.git synced 2025-04-08 20:04:27 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

[Representation] Update documentation

Browse Source 
Update documentation of the representation component,
WTD-521.
This commit is contained in:
Victor Woeltjen 2014-11-22 13:02:51 -08:00
parent 26cb03c555
commit 2e0178ffa9
3 changed files with 158 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
platform/representation/README.md
View File

@ -2,3 +2,114 @@ This bundle introduces the notion of "representations" to Open MCT Web,
primarily via an Angular directive, `mct-representation`.
A representation is used to display domain objects as Angular templates.
# Extension Categories
This bundle introduces four new categories of extension:
* `templates`: Reusable Angular templates. This category of extension is
present to support the `mct-include` directive, which in turn is present
to allow templates to be loaded from across bundles, without knowing
their path ahead of time. A template has the following fields:
* `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 bundle's resources directory.
* `representations`: Ways of representing a domain object. A representation
is defined with the following fields:
* `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`: 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.)
* `gestures`: An array of keys identifying gestures 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 context menu on right-click.)
* `views`: A view is a representation with a visible identity to the user
(e.g. something they can switch among in the view menu.) A view
supports the same fields as a representation, and additionally:
* `name`: The human-readable name of the view.
* `glyph`: A character to display as an icon for this view.
* `description`: The human-readable description of the view.
* `gestures`: A gesture is a user action which can be taken upon a
representation of a domain object. Gestures are described by:
* `key`: The machine-readable name used to look up the gesture.
* `implementation`: The class (relative to the bundle's sources
directory) which implements the gesture. This is instantiated once
per representation that uses the gesture. This class will
receive the jqLite-wrapped `mct-representation` element and the
domain object being represented as arguments, and should do any
necessary "wiring" (e.g. listening for events) during its
constructor call. This class may also expose an optional `destroy()`
method which should be called when the gesture should be removed,
to avoid memory leaks by way of unremoved listeners.
# Extensions
## Directives
* `mct-include`: Includes a template by symbolic key; used to augment the
capability of Angular's `ng-include`, which loads templates by path.
Takes three attributes as Angular expressions:
* `key`: The symbolic identifier of the template to load, matched
against keys defined in extensions of category `templates`.
Note that this is an Angular expression, so internal quotes
may be necessary (see documentation of `ng-include`, which has the same
"gotcha" for URLs.)
* `ng-model`: Optional (and not often used); a model which should appear
in the included template's scope, for it to modify. The specific
interpretation of this attribute will vary depending on the included
template.
* `parameters`: Optional (and not often used); as `ng-model`, except the
intent is to provide information about how to display the included
template (e.g. "title", "color"). The specific interpretation of
this attribute will vary depending on the included template.
* `mct-representation`: Similar to `mct-include`, except the template to
include is specifically a representation of a domain object.
* `key`: As used in `mct-include`, except it will refer to an extension
or category `representations` or of `views`.
* `mct-object`: An Angular expression; the domain object to be
represented.
* `parameters`: As defined for `mct-include`.
### Examples
<mct-include key="'status-bar'"></mct-include>
<mct-representation key="'grid-item'"></mct-representation>
<mct-include key="'title-bar'"
parameters="{title: 'Hello', tooltip: 'Hello, world.'}">
</mct-include>
## Components
* `gestureService`: A provider of type `gestureService` is included to
remove the need to depend on `gestures[]` directly; instead, the
gesture service can be used to add/remove gestures in groups. This is
present primarily for bundle-internal use (it is used by the
`mct-representation` directive) but it is exposed as a service component
for convenience.
## Gestures
In addition to introducing `gestures` as a category of extension, this bundle
introduces three specific gestures as "built in" options, listed by key:
* `drag`: Representations with this gesture can serve as drag sources for
drag-drop domain object composition.
* `drop`: Representations with this gesture can serve as drop targets for
drag-drop domain object composition.
* `menu`: Representations with this gesture will provide a custom context
menu (instead of the browser default).
* It should be noted that this gesture does _not_ define the appearance
or functionality of this menu; rather, it simply adds a
representation of key `context-menu` to the document at an appropriate
location. This representation will be supplied by the commonUI bundle.

29
platform/representation/src/MCTInclude.js
View File

@ -11,12 +11,31 @@ define(
/**
* Defines the mct-include directive. This acts like the
* ng-include directive, except it accepts a symbolic
* key which can be exposed by bundles.
* key which can be exposed by bundles, instead of requiring
* an explicit path.
*
* This directive uses two-way binding for three attributes:
*
* * `key`, matched against the key of a defined template extension
* in order to determine which actual template to include.
* * `ng-model`, populated as `ngModel` in the loaded template's
* scope; used for normal ng-model purposes (e.g. if the
* included template is meant to two-way bind to a data model.)
* * `parameters`, used to communicate display parameters to
* the included template (e.g. title.) The difference between
* `parameters` and `ngModel` is intent: Both are two-way
* bound, but `ngModel` is useful for data models (more like
* an output) and `parameters` is meant to be useful for
* display parameterization (more like an input.)
*
* @constructor
* @param {TemplateDefinition[]} templates an array of
* template extensions
*/
function MCTInclude(templates) {
var templateMap = {};
// Prepopulate templateMap for easy look up by key
templates.forEach(function (template) {
var path = [
template.bundle.path,
@ -27,13 +46,21 @@ define(
});
function controller($scope) {
// Pass the template URL to ng-include via scope.
$scope.inclusion = templateMap[$scope.key];
}
return {
// Only show at the element level
restrict: "E",
// Use the included controller to populate scope
controller: controller,
// Use ng-include as a template; it gets the real template path
template: '<ng-include src="inclusion"></ng-include>',
// Two-way bind key, ngModel, and parameters
scope: { key: "=", ngModel: "=", parameters: "=" }
};
}

19
platform/representation/src/MCTRepresentation.js
View File

@ -8,9 +8,28 @@ define(
function () {
"use strict";
/**
* Defines the mct-representation directive. This may be used to
* present domain objects as HTML (with event wiring), with the
* specific representation being mapped to a defined extension
* (as defined in either the `representation` category-of-extension,
* or the `views` category-of-extension.)
*
* This directive uses two-way binding for three attributes:
*
* * `key`, matched against the key of a defined template extension
* in order to determine which actual template to include.
* * `mct-object`, populated as `domainObject` in the loaded
* template's scope. This is the domain object being
* represented as HTML by this directive.
* * `parameters`, used to communicate display parameters to
* the included template (e.g. title.)
*
* @constructor
* @param {RepresentationDefinition[]} representations an array of
* representation extensions
* @param {ViewDefinition[]} views an array of view extensions
*/
function MCTRepresentation(representations, views, gestureService, $q, $log) {
var pathMap = {},