From 3246480f825e5e07dc5cf884c416c175889b5acc Mon Sep 17 00:00:00 2001 From: Andrew Henry Date: Mon, 16 Jul 2018 15:21:38 -0700 Subject: [PATCH] Indicators api (#1837) * [API] Added Indicators API * [Indicators] Converted Follow Indicator to new Indicators API * [Indicators] Converted URL Indicator to new Indicators API * [Indicators] Changes to some legacy indicators for compatibility with new Indicators API * [Indicators] Addressed code review items from https://github.com/nasa/openmct/pull/1837 * Updated tests for URL Indicator * Adding Indicator API spec * Address linting issues * Switched to direct DOM manipulation rather than template compilation to avoid an unnecessary extra holder element * Updated documentation to reflect changes to API * Indicators api styling (#2076) Updated styling for Indicators * Update API TOC * Fix color of items w-mct-example areas of Style Guide Fixes #1837 * Status class refactoring and cleanups Fixes #1837 - Significant cleanups and name refactoring to allow more concise selector definitions, with changes in js, html and scss files; - Updates in Style Guide > Status page, with some content reorganization and clarification; * Corrected out of date API * de-zeptoed Indicator API test spec * Remove promise from URLIndicator * Separated legacy indicators support * Updated Indicator specs to Jasmine 3 * Fixed checkstyle and lint issues * Moved legacy indicators support to adapter folder * Various fixes for Indicators Fixes #1837 - Added SASS constants for Indicator colors; - Removed commented code; - Removed unused indicator classes from _messages.scss - Fixed missing s-status-on class; * Significant revisions to Style Guide Indicators content Fixes #1837 - Better documentation including recommendations; - Better and more concrete examples; * Style Guide example tweaks Fixes #1837 * Refinement to Style Guide Status and Limits content Fixes #1837 - More detail and clarification on Status and Limits; * Cleanup code Fixes #1837 - Remove commented styles; - Line return refinements; --- API.md | 88 ++++++- example/identity/bundle.js | 3 +- .../identity/src/ExampleIdentityService.js | 34 ++- example/notifications/res/dialog-launch.html | 12 +- .../res/notification-launch.html | 12 +- .../res/sass/_style-guide-base.scss | 5 +- example/styleguide/res/templates/status.html | 239 ++++++++++++------ example/worker/src/FibonacciIndicator.js | 2 +- platform/commonUI/general/bundle.js | 18 +- platform/commonUI/general/res/sass/_main.scss | 1 + .../commonUI/general/res/sass/_status.scss | 148 +++++++---- .../res/sass/controls/_indicators.scss | 146 +++++++++++ .../general/res/sass/controls/_messages.scss | 109 +------- .../res/sass/user-environ/_layout.scss | 28 +- ...{indicator.html => angular-indicator.html} | 10 +- .../general/res/templates/bottombar.html | 9 +- .../MCTIndicators.js} | 41 +-- .../controllers/BottomBarControllerSpec.js | 76 ------ .../res/notification-indicator.html | 11 +- .../themes/espresso/res/sass/_constants.scss | 16 +- .../themes/snow/res/sass/_constants.scss | 12 +- platform/features/clock/bundle.js | 10 +- .../clock/src/indicators/ClockIndicator.js | 4 +- .../clock/src/indicators/FollowIndicator.js | 58 ++--- .../clock/src/services/TimerService.js | 2 +- .../test/indicators/FollowIndicatorSpec.js | 76 ++++-- .../persistence/couch/src/CouchIndicator.js | 8 +- .../couch/test/CouchIndicatorSpec.js | 2 +- .../elastic/src/ElasticIndicator.js | 2 + .../local/src/LocalStorageIndicator.js | 4 +- .../local/test/LocalStorageIndicatorSpec.js | 2 +- src/MCT.js | 18 +- .../indicators/legacy-indicators-plugin.js | 68 +++++ .../legacy-indicators-pluginSpec.js | 114 +++++++++ src/api/api.js | 9 +- src/api/indicators/IndicatorAPI.js | 68 +++++ src/api/indicators/IndicatorAPISpec.js | 115 +++++++++ src/api/indicators/SimpleIndicator.js | 96 +++++++ .../indicators/res/indicator-template.html | 3 + .../URLIndicatorPlugin/URLIndicator.js | 108 ++++---- .../URLIndicatorPlugin/URLIndicatorPlugin.js | 53 ++-- .../URLIndicatorPlugin/URLIndicatorSpec.js | 216 +++++++--------- src/plugins/plugins.js | 2 +- 43 files changed, 1380 insertions(+), 678 deletions(-) create mode 100644 platform/commonUI/general/res/sass/controls/_indicators.scss rename platform/commonUI/general/res/templates/{indicator.html => angular-indicator.html} (78%) rename platform/commonUI/general/src/{controllers/BottomBarController.js => directives/MCTIndicators.js} (53%) delete mode 100644 platform/commonUI/general/test/controllers/BottomBarControllerSpec.js create mode 100644 src/adapter/indicators/legacy-indicators-plugin.js create mode 100644 src/adapter/indicators/legacy-indicators-pluginSpec.js create mode 100644 src/api/indicators/IndicatorAPI.js create mode 100644 src/api/indicators/IndicatorAPISpec.js create mode 100644 src/api/indicators/SimpleIndicator.js create mode 100644 src/api/indicators/res/indicator-template.html diff --git a/API.md b/API.md index 0ec11959f6..e681378b56 100644 --- a/API.md +++ b/API.md @@ -37,7 +37,7 @@ - [Time Systems and Bounds](#time-systems-and-bounds) - [Defining and Registering Time Systems](#defining-and-registering-time-systems) - [Getting and Setting the Active Time System](#getting-and-setting-the-active-time-system) - - [Time Bounds](#time-bounds) + - [Time Bounds](#time-bounds) - [Clocks](#clocks) - [Defining and registering clocks](#defining-and-registering-clocks) - [Getting and setting active clock](#getting-and-setting-active-clock) @@ -48,6 +48,10 @@ - [The Time Conductor](#the-time-conductor) - [Time Conductor Configuration](#time-conductor-configuration) - [Example conductor configuration](#example-conductor-configuration) + - [Indicators](#indicators) + - [The URL Status Indicator](#the-url-status-indicator) + - [Creating a Simple Indicator](#creating-a-simple-indicator) + - [Custom Indicators](#custom-indicators) - [Included Plugins](#included-plugins) @@ -688,7 +692,7 @@ openmct.time.timeSystem(utcTimeSystem, bounds); Setting the active time system will trigger a [`'timeSystem'`](#time-events) event. If you supplied bounds, a [`'bounds'`](#time-events) event will be triggered afterwards with your newly supplied bounds. -### Time Bounds +#### Time Bounds The TimeAPI provides a getter/setter for querying and setting time bounds. Time bounds are simply an object with a `start` and an end `end` attribute. @@ -977,6 +981,72 @@ openmct.install(openmct.plugins.Conductor({ })); ``` +## Indicators + +Indicators are small widgets that reside at the bottom of the screen and are visible from +every screen in Open MCT. They can be used to convey system state using an icon and text. +Typically an indicator will display an icon (customizable with a CSS class) that will +reveal additional information when the mouse cursor is hovered over it. + +### The URL Status Indicator + +A common use case for indicators is to convey the state of some external system such as a +persistence backend or HTTP server. So long as this system is accessible via HTTP request, +Open MCT provides a general purpose indicator to show whether the server is available and +returing a 2xx status code. The URL Status Indicator is made available as a default plugin. See +[Included Plugins](#included-plugins) below for details on how to install and configure the +URL Status Indicator. + +### Creating a Simple Indicator + +A simple indicator with an icon and some text can be created and added with minimal code. An indicator +of this type exposes functions for customizing the text, icon, and style of the indicator. + +eg. +``` javascript +var myIndicator = openmct.indicators.simpleIndicator(); +myIndicator.text("Hello World!"); +openmct.indicators.add(myIndicator); +``` + +This will create a new indicator and add it to the bottom of the screen in Open MCT. +By default, the indicator will appear as an information icon. Hovering over the icon will +reveal the text set via the call to `.text()`. The Indicator object returned by the API +call exposes a number of functions for customizing the content and appearance of the indicator: + +* `.text([text])`: Gets or sets the text shown when the user hovers over the indicator. +Accepts an __optional__ `string` argument that, if provided, will be used to set the text. +Hovering over the indicator will expand it to its full size, revealing this text alongside +the icon. Returns the currently set text as a `string`. +* `.description([description])`: Gets or sets the indicator's description. Accepts an +__optional__ `string` argument that, if provided, will be used to set the text. The description +allows for more detail to be provided in a tooltip when the user hovers over the indicator. +Returns the currently set text as a `string`. +* `.iconClass([className])`: Gets or sets the CSS class used to define the icon. Accepts an __optional__ +`string` parameter to be used to set the class applied to the indicator. Any of +[the built-in glyphs](https://nasa.github.io/openmct/style-guide/#/browse/styleguide:home/glyphs?view=styleguide.glyphs) +may be used here, or a custom CSS class can be provided. Returns the currently defined CSS +class as a `string`. +* `.statusClass([className])`: Gets or sets the CSS class used to determine status. Accepts an __optional __ +`string` parameter to be used to set a status class applied to the indicator. May be used to apply +different colors to indicate status. + +### Custom Indicators + +A completely custom indicator can be added by simple providing a DOM element to place alongside other indicators. + +``` javascript + var domNode = document.createElement('div'); + domNode.innerText = new Date().toString(); + setInterval(function () { + domNode.innerText = new Date().toString(); + }, 1000); + + openmct.indicators.add({ + element: domNode + }); +``` + ## Included Plugins Open MCT is packaged along with a few general-purpose plugins: @@ -1000,18 +1070,18 @@ openmct.install(openmct.plugins.CouchDB('http://localhost:9200')) * `openmct.plugins.Espresso` and `openmct.plugins.Snow` are two different themes (dark and light) available for Open MCT. Note that at least one of these themes must be installed for Open MCT to appear correctly. -* `openmct.plugins.URLIndicatorPlugin` adds an indicator which shows the +* `openmct.plugins.URLIndicator` adds an indicator which shows the availability of a URL with the following options: - `url` : URL to indicate the status of - - `cssClass`: Icon to show in the status bar, defaults to `icon-database`, [list of all icons](https://nasa.github.io/openmct/style-guide/#/browse/styleguide:home?view=items) + - `iconClass`: Icon to show in the status bar, defaults to `icon-database`, [list of all icons](https://nasa.github.io/openmct/style-guide/#/browse/styleguide:home?view=items) - `interval`: Interval between checking the connection, defaults to `10000` - `label` Name showing up as text in the status bar, defaults to url ```javascript -openmct.install(openmct.plugins.URLIndicatorPlugin({ - url: 'http://google.com', - cssClass: 'check', - interval: 10000, - label: 'Google' +openmct.install(openmct.plugins.URLIndicator({ + url: 'http://localhost:8080', + iconClass: 'check', + interval: 10000, + label: 'Localhost' }) ); ``` diff --git a/example/identity/bundle.js b/example/identity/bundle.js index fe2c5114a0..6a1fad72bd 100644 --- a/example/identity/bundle.js +++ b/example/identity/bundle.js @@ -38,7 +38,8 @@ define([ "provides": "identityService", "type": "provider", "depends": [ - "dialogService" + "dialogService", + "$q" ] } ] diff --git a/example/identity/src/ExampleIdentityService.js b/example/identity/src/ExampleIdentityService.js index d685ed0ef8..0d008e591b 100644 --- a/example/identity/src/ExampleIdentityService.js +++ b/example/identity/src/ExampleIdentityService.js @@ -55,21 +55,37 @@ define( * @implements {IdentityService} * @memberof platform/identity */ - function ExampleIdentityProvider(dialogService) { - // Handle rejected dialog messages by treating the - // current user as undefined. - function echo(v) { return v; } - function giveUndefined() { return undefined; } + function ExampleIdentityProvider(dialogService, $q) { + this.dialogService = dialogService; + this.$q = $q; - this.userPromise = - dialogService.getUserInput(DIALOG_STRUCTURE, DEFAULT_IDENTITY) - .then(echo, giveUndefined); + this.returnUser = this.returnUser.bind(this); + this.returnUndefined = this.returnUndefined.bind(this); } ExampleIdentityProvider.prototype.getUser = function () { - return this.userPromise; + if (this.user) { + return this.$q.when(this.user); + } else { + return this.dialogService.getUserInput(DIALOG_STRUCTURE, DEFAULT_IDENTITY) + .then(this.returnUser, this.returnUndefined); + } }; + /** + * @private + */ + ExampleIdentityProvider.prototype.returnUser = function (user) { + return this.user = user; + } + + /** + * @private + */ + ExampleIdentityProvider.prototype.returnUndefined = function () { + return undefined; + } + return ExampleIdentityProvider; } ); diff --git a/example/notifications/res/dialog-launch.html b/example/notifications/res/dialog-launch.html index 42af266e6c..92372f2970 100644 --- a/example/notifications/res/dialog-launch.html +++ b/example/notifications/res/dialog-launch.html @@ -1,9 +1,9 @@ - + - - Known | - Unknown | - Error | +
+ Known + Unknown + Error Info - +
diff --git a/example/notifications/res/notification-launch.html b/example/notifications/res/notification-launch.html index a1e40b4559..25d48ef529 100644 --- a/example/notifications/res/notification-launch.html +++ b/example/notifications/res/notification-launch.html @@ -1,9 +1,9 @@ - + - - Success | - Error | - Alert | +
+ Success + Error + Alert Progress - +
diff --git a/example/styleguide/res/sass/_style-guide-base.scss b/example/styleguide/res/sass/_style-guide-base.scss index a91325af02..f92517e63c 100644 --- a/example/styleguide/res/sass/_style-guide-base.scss +++ b/example/styleguide/res/sass/_style-guide-base.scss @@ -58,7 +58,10 @@ position: relative; } - .w-mct-example > div { margin-bottom: $interiorMarginLg; } + .w-mct-example { + color: #ccc; + > div { margin-bottom: $interiorMarginLg; } + } code, pre { diff --git a/example/styleguide/res/templates/status.html b/example/styleguide/res/templates/status.html index 52ce7e7f5a..3680c3e652 100644 --- a/example/styleguide/res/templates/status.html +++ b/example/styleguide/res/templates/status.html @@ -20,12 +20,12 @@ at runtime from the About dialog for additional information. -->