From 964d3ae801430d844c23ff4df45af7e9b4cd529b Mon Sep 17 00:00:00 2001 From: Aaron Plave Date: Thu, 18 Jul 2024 14:00:18 -0700 Subject: [PATCH 1/4] Time plugin docs --- docs/planning/plugins/introduction.mdx | 21 ++++++++ docs/planning/plugins/time.mdx | 66 ++++++++++++++++++++++++++ sidebars.js | 9 ++++ 3 files changed, 96 insertions(+) create mode 100644 docs/planning/plugins/introduction.mdx create mode 100644 docs/planning/plugins/time.mdx diff --git a/docs/planning/plugins/introduction.mdx b/docs/planning/plugins/introduction.mdx new file mode 100644 index 0000000..a599bb6 --- /dev/null +++ b/docs/planning/plugins/introduction.mdx @@ -0,0 +1,21 @@ +# Advanced - UI Plugins + +The Aerie UI provides an client-side API for customizing various aspects of the UI. This customization is accomplished by supplying the UI with specifically named javascript files in the `static/resources` directory of the application and enabling the plugins using runtime environment variables. These plugins are run in the Aerie UI browser context. The relevant portions of the API specification can be found on specific plugin pages below or for the entire specification please reference the Aerie UI [plugins.ts](https://github.com/NASA-AMMOS/aerie-ui/) type file (TODO make a link once merged). Plugins may also load additional supporting files from the `static/resources` directory or from external sources. Please note that additional resource requests to `static/resources/*` should be referenced as `/resources/*` given the client side routing setup. + +Plugins must export an asynchronous function named `getPlugin` that returns a subset of the Plugin API. + +```javascript +// Empty plugin example (.js) +export async function getPlugin() { + console.log('Plugin loaded'); + return { + /* Plugin contents */ + }; +} +``` + +## Supported Plugins + +| Plugin | Description | +| ------------------------------ | --------------------------------------------------- | +| [Time](/planning/plugins/time) | Customize how time is presented and input in the UI | diff --git a/docs/planning/plugins/time.mdx b/docs/planning/plugins/time.mdx new file mode 100644 index 0000000..e7c0b2c --- /dev/null +++ b/docs/planning/plugins/time.mdx @@ -0,0 +1,66 @@ +# Time Plugin + +Time input and presentation in the Aerie UI can be customized by implementing a time plugin. Currently the time plugin is only used on the plans and individual plan page. This time plugin does not affect how time is stored in the database and instead converts times from the database format to the plugin format on the fly in the UI. + +Example use cases for the Time Plugin: + +- Displaying times in a particular timezone +- Displaying and inputting times in a custom time such as LMST, SCLK, etc + +## Configuration + +- The Time Plugin must be named `time-plugin.js` and must be placed inside of the `static/resources` directory of the Aerie UI. +- Set `PUBLIC_TIME_PLUGIN_ENABLED=true` in your runtime environment. + +## Time Plugin API + +The Time Plugin must return a `time` object from a `getPlugin` function with the following optional properties: + +| Property | Type | Description | +| ----------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `primary` | PluginTime | See below for a definition of the `PluginTime` type.
Default: UTC DOY parsing and input | +| `additional` | Optional[] | Additional time formats that must supply at least the `format` and a `parse` functions. These additional time formats are used in the plan timeline secondary time displays as well as other secondary time displays in the plan page.
Default: User's local timezone | +| `enableDatePicker` | boolean | If true, show a UTC date picker. Disable this when the plugin does not use a primary time of UTC.
Default: `true` | +| `getDefaultPlanEndDate` | (start: Date) => Date \| null | Compute a plan end date given a plan start date
Default: Add one Earth day to the start date | +| `ticks` | Object | See below for the properties of `ticks` | +| `ticks.getTicks` | (start: Date, stop: Date, count: number) => Date[] | Return an array of `Date` objects given a start `Date`, a stop `Date`, and a target count of ticks. This function allows for cleanly lining up ticks with the plugin's primary time system.
Default: UTC based time ticks | +| `ticks.maxLabelWidth` | number | The maximum width in pixels of any tick label. Used internally by the Aerie UI timeline to compute the number of ticks that should be displayed in the timeline.
Default: 130 | + +
+ +The `PluginTime` type is defined by the following optional properties: + +| Property | Type | Description | +| -------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| `format` | (date: Date) => string \| null | Convert a `Date` to a human readable `string`.
Default: UTC DOY `YYYY-DDDThh:mm:ss.SSS` | +| `formatShort` | (date: Date) => string \| null | Convert a `Date` to a short human readable `string`.
Default: UTC DOY `YYYY-DDD` | +| `formatString` | string | Format that users should adhere to for string date entry.
Default: `YYYY-DDDThh:mm:ss` | +| `formatTick` | (date: Date, durationMs: number, tickCount: number) => string \| null | Format a timeline tick given a `Date`, tick window duration, and number of ticks.
Default: Dynamic UTC date formatting | +| `label` | string | Label for the time format.
Default: UTC | +| `parse` | (dateString: string) => Date \| null | Convert a string representation of a date to a `Date` object.
Default: Native Javascript `Date` parsing | +| `validate` | (dateString: string) => string \| null | Return an error string if the given date string is invalid, otherwise return null.
Default: UTC date string validation | + +## Error handling + +The Time Plugin is responsible for gracefully failing when exceptions are encountered within the plugin. When an operation such as `parse` or `format` fails, the plugin should return `null` to indicate to the Aerie UI that an error occurred and that the date is invalid. + +## Example Plugins + +Below is a basic example that sets the additional time formats to a single format that displays the current UTC year. For additional plugin examples, please refer to the [aerie-ui-plugins](https://github.com/NASA-AMMOS/aerie-ui-plugin-examples) repository. + +```javascript +// Time plugin example (time-plugin.js) +export async function getPlugin() { + console.log('Plugin loaded'); + return { + time: { + additional: [ + { + format: (date: Date) => date.getUTCFullYear().toString(), + parse: (dateString: string) => new Date(string), + }, + ], + }, + }; +} +``` diff --git a/sidebars.js b/sidebars.js index ad11f18..9a1d5ac 100644 --- a/sidebars.js +++ b/sidebars.js @@ -158,6 +158,15 @@ const sidebars = { 'planning/timeline-controls', 'planning/advanced-incons', 'planning/advanced-extensions', + { + type: 'category', + label: 'Advanced - UI Plugins', + link: { + id: 'planning/plugins/introduction', + type: 'doc', + }, + items: ['planning/plugins/time'], + }, ], }, { From 7d2cdf0c41bfc747f63493d91c588e19f70aae24 Mon Sep 17 00:00:00 2001 From: Aaron Plave Date: Thu, 18 Jul 2024 16:01:46 -0700 Subject: [PATCH 2/4] Add keyboard shortcut for holding shift to see additional time formats in the timeline tooltip --- docs/keyboard-shortcuts.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/keyboard-shortcuts.mdx b/docs/keyboard-shortcuts.mdx index 34e2b8c..e7652f2 100644 --- a/docs/keyboard-shortcuts.mdx +++ b/docs/keyboard-shortcuts.mdx @@ -30,6 +30,7 @@ The easiest way to navigate the timeline is by holding ⌘ - ctrl + T toggles the cursor visibility - 0 resets the timeline zoom - delete or backspace deletes selected activity directive +- shift when held shows additional time formats within the timeline tooltip
From f86d6e7fc01553ae24a1a5fefacb825fdccbf117 Mon Sep 17 00:00:00 2001 From: Aaron Plave Date: Mon, 22 Jul 2024 12:54:59 -0700 Subject: [PATCH 3/4] Update link --- docs/planning/plugins/introduction.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/planning/plugins/introduction.mdx b/docs/planning/plugins/introduction.mdx index a599bb6..c168448 100644 --- a/docs/planning/plugins/introduction.mdx +++ b/docs/planning/plugins/introduction.mdx @@ -1,6 +1,6 @@ # Advanced - UI Plugins -The Aerie UI provides an client-side API for customizing various aspects of the UI. This customization is accomplished by supplying the UI with specifically named javascript files in the `static/resources` directory of the application and enabling the plugins using runtime environment variables. These plugins are run in the Aerie UI browser context. The relevant portions of the API specification can be found on specific plugin pages below or for the entire specification please reference the Aerie UI [plugins.ts](https://github.com/NASA-AMMOS/aerie-ui/) type file (TODO make a link once merged). Plugins may also load additional supporting files from the `static/resources` directory or from external sources. Please note that additional resource requests to `static/resources/*` should be referenced as `/resources/*` given the client side routing setup. +The Aerie UI provides an client-side API for customizing various aspects of the UI. This customization is accomplished by supplying the UI with specifically named javascript files in the `static/resources` directory of the application and enabling the plugins using runtime environment variables. These plugins are run in the Aerie UI browser context. The relevant portions of the API specification can be found on specific plugin pages below or for the entire specification please reference the Aerie UI [plugin.ts](https://github.com/NASA-AMMOS/aerie-ui/blob/develop/src/types/plugin.ts) type file. Plugins may also load additional supporting files from the `static/resources` directory or from external sources. Please note that additional resource requests to `static/resources/*` should be referenced as `/resources/*` given the client side routing setup. Plugins must export an asynchronous function named `getPlugin` that returns a subset of the Plugin API. From 27b821d35d1086b428259e028a46eb11c4b940eb Mon Sep 17 00:00:00 2001 From: dandelany Date: Wed, 24 Jul 2024 13:47:33 -0700 Subject: [PATCH 4/4] fix typo in time plugin docs --- docs/planning/plugins/time.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/planning/plugins/time.mdx b/docs/planning/plugins/time.mdx index e7c0b2c..91e2466 100644 --- a/docs/planning/plugins/time.mdx +++ b/docs/planning/plugins/time.mdx @@ -46,7 +46,7 @@ The Time Plugin is responsible for gracefully failing when exceptions are encoun ## Example Plugins -Below is a basic example that sets the additional time formats to a single format that displays the current UTC year. For additional plugin examples, please refer to the [aerie-ui-plugins](https://github.com/NASA-AMMOS/aerie-ui-plugin-examples) repository. +Below is a basic example that sets the additional time formats to a single format that displays the current UTC year. For additional plugin examples, please refer to the [aerie-ui-plugin-examples](https://github.com/NASA-AMMOS/aerie-ui-plugin-examples) repository. ```javascript // Time plugin example (time-plugin.js)