From 975087c3f6b1b469e721812ad5686d846a77a19f Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Wed, 10 Jun 2020 00:15:40 -0700 Subject: [PATCH] feat: Add navigation API doc page with hardcoded doc data --- src/data/navigationApi.js | 694 +++++++++++++++++++++++++ src/data/sidenav.json | 4 + src/hooks/useApiDoc.js | 7 + src/markdown-pages/apis/navigation.mdx | 7 + 4 files changed, 712 insertions(+) create mode 100644 src/data/navigationApi.js create mode 100644 src/markdown-pages/apis/navigation.mdx diff --git a/src/data/navigationApi.js b/src/data/navigationApi.js new file mode 100644 index 000000000..bc6b96161 --- /dev/null +++ b/src/data/navigationApi.js @@ -0,0 +1,694 @@ +const navigationApi = { + description: '', + usage: "import { navigation } from 'nr1'", + methods: [ + { + name: 'navigation.getOpenEntityLocation', + description: ` +Returns a location object that can be used to redirect to an entity in its corresponding launcher (default: Explorer launcher). + +Location objects can be passed into \`\` component to navigate inside the platform. + `.trim(), + returnValue: { type: 'Location' }, + params: [ + { + name: 'entityGuid', + type: 'string', + description: 'GUID of the entity to open.', + }, + ], + examples: [ + { + label: 'Example', + sourceCode: ` +const entityGuid = 'Mxka102Ak'; + +const location = navigation.getOpenEntityLocation(entityGuid); + `.trim(), + options: { + live: false, + }, + }, + ], + }, + { + name: 'navigation.getOpenLauncherLocation', + description: ` +Returns a location object that can be used to redirect to a given launcher. + +You can also specify nerdlet and stacked nerdlets with given states to be opened in this launcher. + +If nerdlet is not specified, the root nerdlet of the given launcher will be opened. + +Location objects can be passed into \`\` component to navigate inside the platform. + `.trim(), + returnValue: { type: 'Location' }, + params: [ + { + name: 'launcher', + type: 'Launcher', + description: 'Launcher to open.', + }, + ], + examples: [ + { + label: 'Example 1', + sourceCode: ` +const launcher = { + id: 'nr1-core.explorer', +}; + +const location = navigation.getOpenLauncherLocation(launcher); + `.trim(), + options: { + live: false, + }, + }, + { + label: 'Example 2', + sourceCode: ` +// You can also specify a nerdlet and stacked nerdlets to be opened. +// You can combine artifacts from different nerdpacks. +const launcher = { + id: '074e8260-fa9c-4d71-f7a0-51835417a423.my-launcher-id', + nerdlet: { + id: 'nr1-core.listing', + }, + stackedNerdlets: [ + { + id: 'dashboards.list', + }, + ], +}; + +const location = navigation.getOpenLauncherLocation(launcher); + `.trim(), + options: { + live: false, + }, + }, + ], + }, + { + name: 'navigation.getOpenNerdletLocation', + description: ` +Returns a location object that can be used to open a given nerdlet with a given state. + +Location objects can be passed into \`\` component to navigate inside the platform. + `.trim(), + returnValue: { type: 'Location' }, + params: [ + { + name: 'nerdlet', + type: 'Nerdlet', + description: 'Nerdlet to replace current nerdlet with.', + }, + ], + examples: [ + { + label: 'Example 1', + sourceCode: ` +const nerdlet = { + id: 'dashboards.list', +}; + +const location = navigation.getOpenNerdletLocation(nerdlet); + `.trim(), + options: { + live: false, + }, + }, + { + label: 'Example 2', + sourceCode: ` +// You can also specify nerdlet's state. +const nerdlet = { + id: 'dashboards.list', + urlState: { + foo: 'bar', + }, +}; + +const location = navigation.getOpenNerdletLocation(nerdlet); + `.trim(), + options: { + live: false, + }, + }, + ], + }, + { + name: 'navigation.getOpenOverlayLocation', + description: ` +Returns a location object that can be used to trigger opening overlay. + +Location objects can be passed into \`\` component to navigate inside the platform. + `.trim(), + returnValue: { type: 'Location' }, + params: [ + { + name: 'overlay', + type: 'Overlay', + description: 'Overlay you want to open.', + }, + ], + examples: [ + { + label: 'Example', + sourceCode: ` +const overlay = { + id: 'nr1-core.search', +}; + +const location = navigation.getOpenOverlayLocation(overlay); + `.trim(), + options: { + live: false, + }, + }, + ], + }, + { + name: 'navigation.getOpenStackedEntityLocation', + description: ` +Returns a location object that can be used to trigger opening entity in a stacked nerdlet. + +Location objects can be passed into \`\` component to navigate inside the platform. + `.trim(), + returnValue: { type: 'Location' }, + params: [ + { + name: 'entityGuid', + type: 'string', + description: 'GUID of the entity to open.', + }, + ], + examples: [ + { + label: 'Example', + sourceCode: ` +const entityGuid = 'Mxka102Ak'; + +const location = navigation.getOpenStackedEntityLocation(entityGuid); + `.trim(), + options: { + live: false, + }, + }, + ], + }, + { + name: 'navigation.getOpenStackedNerdletLocation', + description: ` +Returns a location object that can be used to trigger opening stacked nerdlet with a given state. + +Location objects can be passed into \`\` component to navigate inside the platform. + `.trim(), + returnValue: { type: 'Location' }, + params: [ + { + name: 'nerdlet', + type: 'Nerdlet', + description: 'Nerdlet to open as stacked nerdlet.', + }, + ], + examples: [ + { + label: 'Example 1', + sourceCode: ` +const nerdlet = { + id: 'dashboards.list', +}; + +const location = navigation.getOpenStackedNerdletLocation(nerdlet); + `.trim(), + options: { + live: false, + }, + }, + { + label: 'Example 2', + sourceCode: ` +// You can also specify nerdlet's state. +const nerdletWithState = { + id: 'dashboards.list', + urlState: { + foo: 'bar', + }, +}; + +const location = navigation.getOpenStackedNerdletLocation(nerdletWithState); + `.trim(), + options: { + live: false, + }, + }, + { + label: 'Example 3', + sourceCode: ` +// If you want to open nerdlet from the current nerdpack then you can omit its nerdpackId. +const nerdletWithState = { + id: 'my-nerdlet-id', + urlState: { + foo: 'bar', + }, +}; + +const location = navigation.getOpenStackedNerdletLocation(nerdletWithState); + `.trim(), + options: { + live: false, + }, + }, + ], + }, + { + name: 'navigation.getReplaceNerdletLocation', + description: ` +Returns a location object that can be used to replace current nerdlet. + +Location objects can be passed into \`\` component to navigate inside the platform. + `.trim(), + returnValue: { type: 'Location' }, + params: [ + { + name: 'nerdlet', + type: 'Nerdlet', + description: 'Nerdlet to replace current nerdlet with.', + }, + ], + examples: [ + { + label: 'Example 1', + sourceCode: ` +const nerdlet = { + id: 'dashboards.list', +}; + +const location = navigation.getReplaceNerdletLocation(nerdlet); + `.trim(), + options: { + live: false, + }, + }, + { + label: 'Example 2', + sourceCode: ` +// If the nerdlet you want to replace with is in the current nerdpack then you can omit its nerdpackId. +const nerdlet = { + id: 'my-nerdlet-id', +}; + +const location = navigation.getReplaceNerdletLocation(nerdlet); + `.trim(), + options: { + live: false, + }, + }, + { + label: 'Example 3', + sourceCode: ` +// You can also specify nerdlet's state. +const nerdlet = { + id: 'my-nerdlet-id', + urlState: { + foo: 'bar', + }, +}; + +const location = navigation.getReplaceNerdletLocation(nerdlet); + `.trim(), + options: { + live: false, + }, + }, + ], + }, + { + name: 'navigation.openEntity', + description: ` +Opens an entity in its corresponding launcher (default: Explorer launcher). + +To navigate without adding an entry to the browser history, set \`urlStateOptions.replaceHistory\` to \`true\`. + `.trim(), + returnValue: { type: 'undefined' }, + params: [ + { + name: 'entityGuid', + type: 'string', + description: 'GUID of the entity to open.', + }, + { + name: 'urlStateOptions', + type: 'UrlStateOptions', + description: 'Options for the URL state.', + }, + ], + examples: [ + { + label: 'Example', + sourceCode: ` +const entityGuid = 'Mxka102Ak'; + +navigation.openEntity(entityGuid); + `.trim(), + options: { + live: false, + }, + }, + ], + }, + { + name: 'navigation.openLauncher', + description: ` +Opens launcher inside the platform. + +You can also specify nerdlet and stacked nerdlets with given states to be opened in this launcher. + +If nerdlet is not specified, the root nerdlet of the given launcher will be opened. + +If you wish to navigate without adding an entry to the browser history, set \`urlStateOptions.replaceHistory\` to \`true\`. + `.trim(), + returnValue: { type: 'void' }, + params: [ + { + name: 'launcher', + type: 'Launcher', + description: 'Launcher to open.', + }, + { + name: 'urlStateOptions', + type: 'UrlStateOptions', + description: 'Options for the URL state.', + }, + ], + examples: [ + { + label: 'Example 1', + sourceCode: ` +const launcher = { + id: 'nr1-core.explorer', +}; + +navigation.openLauncher(launcher); + `.trim(), + options: { + live: false, + }, + }, + { + label: 'Example 2', + sourceCode: ` +// You can also specify a nerdlet and stacked nerdlets to be opened. +// You can combine artifacts from different nerdpacks. +const launcher = { + id: '074e8260-fa9c-4d71-f7a0-51835417a423.my-launcher-id', + nerdlet: { + id: 'nr1-core.listing', + }, + stackedNerdlets: [ + { + id: 'dashboards.list', + }, + ], +}; + +navigation.openLauncher(launcher); + `.trim(), + options: { + live: false, + }, + }, + ], + }, + { + name: 'navigation.openNerdlet', + description: ` +Opens a nerdlet in the current launcher. + +If \`nerdlet.urlState\` is provided, it will be shallow-merged with the initial state of the nerdlet. + +If you wish to navigate without adding an entry to the browser history, set \`urlStateOptions.replaceHistory\` to \`true\`. + `.trim(), + returnValue: { type: 'void' }, + params: [ + { + name: 'nerdlet', + type: 'Nerdlet', + description: 'Nerdlet to open.', + }, + { + name: 'urlStateOptions', + type: 'UrlStateOptions', + description: 'Options for the URL state.', + }, + ], + examples: [ + { + label: 'Example 1', + sourceCode: ` +const nerdlet = { + id: 'dashboards.list', +}; + +navigation.openNerdlet(nerdlet); + `.trim(), + options: { + live: false, + }, + }, + { + label: 'Example 2', + sourceCode: ` +// You can also specify nerdlet's state. +const nerdletWithState = { + id: 'dashboards.list', + urlState: { + foo: 'bar', + } +}; + +const location = navigation.getOpenNerdletLocation(nerdletWithState); + `.trim(), + options: { + live: false, + }, + }, + ], + }, + { + name: 'navigation.openOverlay', + description: ` +Opens an overlay on top of the current launcher. + +If \`overlay.urlState\` is provided, it will be shallow-merged with the initial state of the overlay. + +If you wish to navigate without adding an entry to the browser history, set \`urlStateOptions.replaceHistory\` to \`true\`. + `.trim(), + returnValue: { type: 'void' }, + params: [ + { + name: 'overlay', + type: 'Overlay', + description: 'Overlay you want to open.', + }, + { + name: 'urlStateOptions', + type: 'UrlStateOptions', + description: 'Options for the URL state.', + }, + ], + examples: [ + { + label: 'Example', + sourceCode: ` +const overlay = { + id: 'nr1-core.search', +}; + +navigation.openOverlay(overlay); + `.trim(), + options: { + live: false, + }, + }, + ], + }, + { + name: 'navigation.openStackedEntity', + description: ` +Opens a stacked nerdlet with entity open in it. If triggered from a stacked nerdlet that is not the last one on the stack, the stacked nerdlet aboves it will be replaced. + +To navigate without adding an entry to the browser history, set \`urlStateOptions.replaceHistory\` to \`true\`. + `.trim(), + returnValue: { type: 'undefined' }, + params: [ + { + name: 'entityGuid', + type: 'string', + description: 'GUID of the entity to open.', + }, + { + name: 'urlStateOptions', + type: 'UrlStateOptions', + description: 'Options for the URL state.', + }, + ], + examples: [ + { + label: 'Example', + sourceCode: ` +// Opens stacked entity. +const entityGuid = 'Mxka102Ak'; + +navigation.openStackedEntity(entityGuid); + `.trim(), + options: { + live: false, + }, + }, + ], + }, + { + name: 'navigation.openStackedNerdlet', + description: ` +Opens a stacked nerdlet with given state above current one. + +If triggered from a stacked nerdlet that is not the last one on the stack, the stacked nerdlets above it will be replaced. + +If you wish to navigate without adding an entry to the browser history, set \`urlStateOptions.replaceHistory\` to \`true\`. + `.trim(), + returnValue: { type: 'void' }, + params: [ + { + name: 'nerdlet', + type: 'Nerdlet', + description: 'Nerdlet to open as stacked nerdlet.', + }, + { + name: 'urlStateOptions', + type: 'UrlStateOptions', + description: 'Options for the URL state.', + }, + ], + examples: [ + { + label: 'Example 1', + sourceCode: ` +const nerdlet = { + id: 'dashboards.list', +}; + +navigation.openStackedNerdlet(nerdlet); + `.trim(), + options: { + live: false, + }, + }, + { + label: 'Example 2', + sourceCode: ` +// You can also specify nerdlet's state. +const nerdletWithState = { + id: '074e8260-fa9c-4d71-f7a0-51835417a423.my-nerdlet-id', + urlState: { + foo: 'bar', + } +}; + +navigation.openStackedNerdlet(nerdlet); + `.trim(), + options: { + live: false, + }, + }, + { + label: 'Example 3', + sourceCode: ` +// If you want to open nerdlet from the current nerdpack then you can omit its nerdpackId. +const nerdletWithState = { + id: 'my-nerdlet-id', + urlState: { + foo: 'bar', + } +}; + +navigation.openStackedNerdlet(nerdlet); + `.trim(), + options: { + live: false, + }, + }, + ], + }, + { + name: 'navigation.replaceNerdlet', + description: ` +Replaces the nerdlet that is calling this API method. + +If you wish to navigate without adding an entry to the browser history, set \`urlStateOptions.replaceHistory\` to \`true\`. + `.trim(), + returnValue: { type: 'void' }, + params: [ + { + name: 'nerdlet', + type: 'Nerdlet', + description: 'GUID of the entity to open.', + }, + { + name: 'urlStateOptions', + type: 'UrlStateOptions', + description: 'Options for the URL state.', + }, + ], + examples: [ + { + label: 'Example 1', + sourceCode: ` +const nerdlet = { + id: 'dashboards.list', +}; + +navigation.replaceNerdlet(nerdlet); + `.trim(), + options: { + live: false, + }, + }, + { + label: 'Example 2', + sourceCode: ` +// If the nerdlet you want to replace with is in the current nerdpack then you can omit its nerdpackId. +const nerdlet = { + id: 'my-nerdlet-id', +}; + +navigation.replaceNerdlet(nerdlet); + `.trim(), + options: { + live: false, + }, + }, + { + label: 'Example 3', + sourceCode: ` +// You can also specify nerdlet's state. +const nerdlet = { + id: 'my-nerdlet-id', + urlState: { + foo: 'bar', + }, +}; + +navigation.replaceNerdlet(nerdlet); + `.trim(), + options: { + live: false, + }, + }, + ], + }, + ], +}; + +export default navigationApi; diff --git a/src/data/sidenav.json b/src/data/sidenav.json index 44556fdc5..2ddd77861 100644 --- a/src/data/sidenav.json +++ b/src/data/sidenav.json @@ -353,6 +353,10 @@ "displayName": "logger", "url": "/apis/logger" }, + { + "displayName": "navigation", + "url": "/apis/navigation" + }, { "displayName": "nerdlet", "url": "/apis/nerdlet" diff --git a/src/hooks/useApiDoc.js b/src/hooks/useApiDoc.js index e1a4c731a..c0fc66dbb 100644 --- a/src/hooks/useApiDoc.js +++ b/src/hooks/useApiDoc.js @@ -1,4 +1,5 @@ import { useMemo } from 'react'; +import navigationApi from '../data/navigationApi'; const IGNORED_METHODS = [ 'prototype', @@ -20,6 +21,12 @@ const useApiDoc = (name) => { const sdk = window.__NR1_SDK__?.default ?? {}; const api = sdk[name]; + // The SDK does not include the navigation docs so we need to return the + // hardcoded values + if (name === 'navigation') { + return navigationApi; + } + if (!api) { return null; } diff --git a/src/markdown-pages/apis/navigation.mdx b/src/markdown-pages/apis/navigation.mdx new file mode 100644 index 000000000..2adee905d --- /dev/null +++ b/src/markdown-pages/apis/navigation.mdx @@ -0,0 +1,7 @@ +--- +path: '/apis/navigation' +title: 'navigation' +description: 'The navigation API' +api: 'navigation' +template: 'ApiReferenceTemplate' +---