Locator docs (#103129)

* feat: 🎸 add locator_examples plugin * feat: 🎸 add example app in locator_examples * feat: 🎸 add locator_explorer plugin * chore: 🤖 remove url_generaotrs_* example plugins * docs: ✏️ update share plugin readme * docs: ✏️ add locators readme * docs: ✏️ update docs link in example plugin * docs: ✏️ update navigation docs * fix: 🐛 make P extend SerializableState * test: 💍 update test mocks * fix: 🐛 use correct type in ingest pipeline locator * test: 💍 add missing methods in mock * test: 💍 update test mocks * chore: 🤖 update plugin list Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
elastic · Jun 28, 2021 · 82e32fa · 82e32fa
1 parent 64df698
commit 82e32fa
Show file tree

Hide file tree

Showing 28 changed files with 380 additions and 188 deletions.
diff --git a/docs/developer/best-practices/navigation.asciidoc b/docs/developer/best-practices/navigation.asciidoc
@@ -47,24 +47,26 @@ console.log(discoverUrl); // http://localhost:5601/bpr/s/space/app/discover
 const discoverUrlWithSomeState = core.http.basePath.prepend(`/discover#/?_g=(filters:!(),refreshInterval:(pause:!t,value:0),time:(from:'2020-09-10T11:39:50.203Z',to:'2020-09-10T11:40:20.249Z'))&_a=(columns:!(_source),filters:!(),index:'90943e30-9a47-11e8-b64d-95841ca0b247',interval:auto,query:(language:kuery,query:''),sort:!())`);
 ----
 
-Instead, each app should expose {kib-repo}tree/{branch}/src/plugins/share/public/url_generators/README.md[a URL generator].
-Other apps should use those URL generators for creating URLs. 
+Instead, each app should expose {kib-repo}tree/{branch}/src/plugins/share/common/url_service/locators/README.md[a locator].
+Other apps should use those locators for navigation or URL creation. 
 
 [source,typescript jsx]
 ----
-// Properly generated URL to *Discover* app. Generator code is owned by *Discover* app and available on *Discover*'s plugin contract.
-const discoverUrl = discoverUrlGenerator.createUrl({filters, timeRange});
+// Properly generated URL to *Discover* app. Locator code is owned by *Discover* app and available on *Discover*'s plugin contract.
+const discoverUrl = await plugins.discover.locator.getUrl({filters, timeRange});
+// or directly execute navigation
+await plugins.discover.locator.navigate({filters, timeRange});
 ----
 
-To get a better idea, take a look at *Discover* URL generator {kib-repo}tree/{branch}/src/plugins/discover/public/url_generator.ts[implementation].
+To get a better idea, take a look at *Discover* locator {kib-repo}tree/{branch}/src/plugins/discover/public/locator.ts[implementation].
 It allows specifying various **Discover** app state pieces like: index pattern, filters, query, time range and more.
 
-There are two ways to access other's app URL generator in your code:
+There are two ways to access locators of other apps:
 
 1. From a plugin contract of a destination app *(preferred)*. 
-2. Using URL generator service instance on `share` plugin contract (in case an explicit plugin dependency is not possible).
+2. Using locator client in `share` plugin (case an explicit plugin dependency is not possible).
 
-In case you want other apps to link to your app, then you should create a URL generator and expose it on your plugin's contract.
+In case you want other apps to link to your app, then you should create a locator and expose it on your plugin's contract.
 
 
 [[navigating-between-kibana-apps]]

diff --git a/docs/developer/plugin-list.asciidoc b/docs/developer/plugin-list.asciidoc
@@ -191,7 +191,8 @@ so they can properly protect the data within their clusters.
 
 
 |{kib-repo}blob/{branch}/src/plugins/share/README.md[share]
-|Replaces the legacy ui/share module for registering share context menus.
+|The share plugin contains various utilities for displaying sharing context menu,
+generating deep links to other apps, and creating short URLs.
 
 
 |{kib-repo}blob/{branch}/src/plugins/spaces_oss/README.md[spacesOss]

diff --git a/examples/locator_examples/README.md b/examples/locator_examples/README.md
@@ -0,0 +1,8 @@
+# Locator examples
+
+This example plugin shows how to:
+
+ - Register a URL locator.
+ - Return locator from plugin contract.
+
+To run this example, use the command `yarn start --run-examples`. Navigate to the locator app.
diff --git a/examples/url_generators_examples/kibana.json → examples/locator_examples/kibana.json b/examples/url_generators_examples/kibana.json → examples/locator_examples/kibana.json
@@ -1,12 +1,12 @@
 {
-  "id": "urlGeneratorsExamples",
+  "id": "locatorExamples",
   "version": "0.0.1",
   "kibanaVersion": "kibana",
   "server": false,
   "ui": true,
   "requiredPlugins": ["share"],
   "optionalPlugins": [],
   "extraPublicDirs": [
-    "public/url_generator"
+    "public/locator"
   ]
 }
diff --git a/...es/url_generators_examples/public/app.tsx → examples/locator_examples/public/app.tsx b/...es/url_generators_examples/public/app.tsx → examples/locator_examples/public/app.tsx
diff --git a/...s/url_generators_explorer/public/index.ts → examples/locator_examples/public/index.ts b/...s/url_generators_explorer/public/index.ts → examples/locator_examples/public/index.ts
@@ -6,6 +6,14 @@
  * Side Public License, v 1.
  */
 
-import { AccessLinksExplorerPlugin } from './plugin';
+import { LocatorExamplesPlugin } from './plugin';
 
-export const plugin = () => new AccessLinksExplorerPlugin();
+export {
+  HelloLocator,
+  HelloLocatorV1Params,
+  HelloLocatorV2Params,
+  HelloLocatorParams,
+  HELLO_LOCATOR,
+} from './locator';
+
+export const plugin = () => new LocatorExamplesPlugin();
diff --git a/examples/locator_examples/public/locator.ts b/examples/locator_examples/public/locator.ts
@@ -0,0 +1,54 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { SerializableState, MigrateFunction } from 'src/plugins/kibana_utils/common';
+import { LocatorDefinition, LocatorPublic } from '../../../src/plugins/share/public';
+
+export const HELLO_LOCATOR = 'HELLO_LOCATOR';
+
+export interface HelloLocatorV1Params extends SerializableState {
+  name: string;
+}
+
+export interface HelloLocatorV2Params extends SerializableState {
+  firstName: string;
+  lastName: string;
+}
+
+export type HelloLocatorParams = HelloLocatorV2Params;
+
+const migrateV1ToV2: MigrateFunction<HelloLocatorV1Params, HelloLocatorV2Params> = (
+  v1: HelloLocatorV1Params
+) => {
+  const v2: HelloLocatorV2Params = {
+    firstName: v1.name,
+    lastName: '',
+  };
+
+  return v2;
+};
+
+export type HelloLocator = LocatorPublic<HelloLocatorParams>;
+
+export class HelloLocatorDefinition implements LocatorDefinition<HelloLocatorParams> {
+  public readonly id = HELLO_LOCATOR;
+
+  public readonly getLocation = async ({ firstName, lastName }: HelloLocatorParams) => {
+    return {
+      app: 'locatorExamples',
+      path: `/hello?firstName=${encodeURIComponent(firstName)}&lastName=${encodeURIComponent(
+        lastName
+      )}`,
+      state: {},
+    };
+  };
+
+  public readonly migrations = {
+    '0.0.2': (migrateV1ToV2 as unknown) as MigrateFunction,
+  };
+}
diff --git a/...url_generators_examples/public/plugin.tsx → examples/locator_examples/public/plugin.tsx b/...url_generators_examples/public/plugin.tsx → examples/locator_examples/public/plugin.tsx
@@ -8,44 +8,27 @@
 
 import { SharePluginStart, SharePluginSetup } from '../../../src/plugins/share/public';
 import { Plugin, CoreSetup, AppMountParameters, AppNavLinkStatus } from '../../../src/core/public';
-import {
-  HelloLinkGeneratorState,
-  createHelloPageLinkGenerator,
-  LegacyHelloLinkGeneratorState,
-  HELLO_URL_GENERATOR_V1,
-  HELLO_URL_GENERATOR,
-  helloPageLinkGeneratorV1,
-} from './url_generator';
+import { HelloLocator, HelloLocatorDefinition } from './locator';
 
-declare module '../../../src/plugins/share/public' {
-  export interface UrlGeneratorStateMapping {
-    [HELLO_URL_GENERATOR_V1]: LegacyHelloLinkGeneratorState;
-    [HELLO_URL_GENERATOR]: HelloLinkGeneratorState;
-  }
+interface SetupDeps {
+  share: SharePluginSetup;
 }
 
 interface StartDeps {
   share: SharePluginStart;
 }
 
-interface SetupDeps {
-  share: SharePluginSetup;
+export interface LocatorExamplesSetup {
+  locator: HelloLocator;
 }
 
-const APP_ID = 'urlGeneratorsExamples';
-
-export class AccessLinksExamplesPlugin implements Plugin<void, void, SetupDeps, StartDeps> {
-  public setup(core: CoreSetup<StartDeps>, { share: { urlGenerators } }: SetupDeps) {
-    urlGenerators.registerUrlGenerator(
-      createHelloPageLinkGenerator(async () => ({
-        appBasePath: (await core.getStartServices())[0].application.getUrlForApp(APP_ID),
-      }))
-    );
-
-    urlGenerators.registerUrlGenerator(helloPageLinkGeneratorV1);
+export class LocatorExamplesPlugin
+  implements Plugin<LocatorExamplesSetup, void, SetupDeps, StartDeps> {
+  public setup(core: CoreSetup<StartDeps>, plugins: SetupDeps) {
+    const locator = plugins.share.url.locators.create(new HelloLocatorDefinition());
 
     core.application.register({
-      id: APP_ID,
+      id: 'locatorExamples',
       title: 'Access links examples',
       navLinkStatus: AppNavLinkStatus.hidden,
       async mount(params: AppMountParameters) {
@@ -58,6 +41,10 @@ export class AccessLinksExamplesPlugin implements Plugin<void, void, SetupDeps,
         );
       },
     });
+
+    return {
+      locator,
+    };
   }
 
   public start() {}

diff --git a/...les/url_generators_examples/tsconfig.json → examples/locator_examples/tsconfig.json b/...les/url_generators_examples/tsconfig.json → examples/locator_examples/tsconfig.json
diff --git a/examples/url_generators_explorer/README.md → examples/locator_explorer/README.md b/examples/url_generators_explorer/README.md → examples/locator_explorer/README.md
@@ -1,6 +1,7 @@
-## Access links explorer
+# Locator explorer
+
+This example plugin shows how to:
 
-This example app shows how to:
  - Generate links to other applications
  - Generate dynamic links, when the target application is not known
  - Handle backward compatibility of urls

diff --git a/examples/url_generators_explorer/kibana.json → examples/locator_explorer/kibana.json b/examples/url_generators_explorer/kibana.json → examples/locator_explorer/kibana.json
@@ -1,9 +1,9 @@
 {
-  "id": "urlGeneratorsExplorer",
+  "id": "locatorExplorer",
   "version": "0.0.1",
   "kibanaVersion": "kibana",
   "server": false,
   "ui": true,
-  "requiredPlugins": ["share", "urlGeneratorsExamples", "developerExamples"],
+  "requiredPlugins": ["share", "locatorExamples", "developerExamples"],
   "optionalPlugins": []
 }
diff --git a/...es/url_generators_explorer/public/app.tsx → examples/locator_explorer/public/app.tsx b/...es/url_generators_explorer/public/app.tsx → examples/locator_explorer/public/app.tsx
@@ -8,9 +8,7 @@
 
 import React, { useState, useEffect } from 'react';
 import ReactDOM from 'react-dom';
-
 import { EuiPage } from '@elastic/eui';
-
 import { EuiButton } from '@elastic/eui';
 import { EuiPageBody } from '@elastic/eui';
 import { EuiPageContent } from '@elastic/eui';
@@ -21,44 +19,54 @@ import { EuiFieldText } from '@elastic/eui';
 import { EuiPageHeader } from '@elastic/eui';
 import { EuiLink } from '@elastic/eui';
 import { AppMountParameters } from '../../../src/core/public';
-import { UrlGeneratorsService } from '../../../src/plugins/share/public';
+import { SharePluginSetup } from '../../../src/plugins/share/public';
 import {
-  HELLO_URL_GENERATOR,
-  HELLO_URL_GENERATOR_V1,
-} from '../../url_generators_examples/public/url_generator';
+  HelloLocatorV1Params,
+  HelloLocatorV2Params,
+  HELLO_LOCATOR,
+} from '../../locator_examples/public';
 
 interface Props {
-  getLinkGenerator: UrlGeneratorsService['getUrlGenerator'];
+  share: SharePluginSetup;
 }
 
 interface MigratedLink {
-  isDeprecated: boolean;
   linkText: string;
   link: string;
+  version: string;
 }
 
-const ActionsExplorer = ({ getLinkGenerator }: Props) => {
+const ActionsExplorer = ({ share }: Props) => {
   const [migratedLinks, setMigratedLinks] = useState([] as MigratedLink[]);
   const [buildingLinks, setBuildingLinks] = useState(false);
   const [firstName, setFirstName] = useState('');
   const [lastName, setLastName] = useState('');
+
   /**
    * Lets pretend we grabbed these links from a persistent store, like a saved object.
-   * Some of these links were created with older versions of the hello link generator.
-   * They use deprecated generator ids.
+   * Some of these links were created with older versions of the hello locator.
    */
-  const [persistedLinks, setPersistedLinks] = useState([
+  const [persistedLinks, setPersistedLinks] = useState<
+    Array<{
+      id: string;
+      version: string;
+      linkText: string;
+      params: HelloLocatorV1Params | HelloLocatorV2Params;
+    }>
+  >([
     {
-      id: HELLO_URL_GENERATOR_V1,
+      id: HELLO_LOCATOR,
+      version: '0.0.1',
       linkText: 'Say hello to Mary',
-      state: {
+      params: {
         name: 'Mary',
       },
     },
     {
-      id: HELLO_URL_GENERATOR,
+      id: HELLO_LOCATOR,
+      version: '0.0.2',
       linkText: 'Say hello to George',
-      state: {
+      params: {
         firstName: 'George',
         lastName: 'Washington',
       },
@@ -71,30 +79,38 @@ const ActionsExplorer = ({ getLinkGenerator }: Props) => {
     const updateLinks = async () => {
       const updatedLinks = await Promise.all(
         persistedLinks.map(async (savedLink) => {
-          const generator = getLinkGenerator(savedLink.id);
-          const link = await generator.createUrl(savedLink.state);
+          const locator = share.url.locators.get(savedLink.id);
+          if (!locator) return;
+          let params: HelloLocatorV1Params | HelloLocatorV2Params = savedLink.params;
+          if (savedLink.version === '0.0.1') {
+            const migration = locator.migrations['0.0.2'];
+            if (migration) {
+              params = migration(params) as HelloLocatorV2Params;
+            }
+          }
+          const link = await locator.getUrl(params, { absolute: false });
           return {
-            isDeprecated: generator.isDeprecated,
             linkText: savedLink.linkText,
             link,
-          };
+            version: savedLink.version,
+          } as MigratedLink;
         })
       );
-      setMigratedLinks(updatedLinks);
+      setMigratedLinks(updatedLinks as MigratedLink[]);
       setBuildingLinks(false);
     };
 
     updateLinks();
-  }, [getLinkGenerator, persistedLinks]);
+  }, [share, persistedLinks]);
 
   return (
     <EuiPage>
       <EuiPageBody>
-        <EuiPageHeader>Access links explorer</EuiPageHeader>
+        <EuiPageHeader>Locator explorer</EuiPageHeader>
         <EuiPageContent>
           <EuiPageContentBody>
             <EuiText>
-              <p>Create new links using the most recent version of a url generator.</p>
+              <p>Create new links using the most recent version of a locator.</p>
             </EuiText>
             <EuiFieldText
               prepend="First name"
@@ -108,8 +124,9 @@ const ActionsExplorer = ({ getLinkGenerator }: Props) => {
                 setPersistedLinks([
                   ...persistedLinks,
                   {
-                    id: HELLO_URL_GENERATOR,
-                    state: { firstName, lastName },
+                    id: HELLO_LOCATOR,
+                    version: '0.0.2',
+                    params: { firstName, lastName },
                     linkText: `Say hello to ${firstName} ${lastName}`,
                   },
                 ])
@@ -122,10 +139,10 @@ const ActionsExplorer = ({ getLinkGenerator }: Props) => {
             <EuiText>
               <p>
                 Existing links retrieved from storage. The links that were generated from legacy
-                generators are in red. This can be useful for developers to know they will have to
+                locators are in red. This can be useful for developers to know they will have to
                 migrate persisted state or in a future version of Kibana, these links may no longer
-                work. They still work now because legacy url generators must provide a state
-                migration function.
+                work. They still work now because legacy locators must provide state migration
+                functions.
               </p>
             </EuiText>
             {buildingLinks ? (
@@ -134,7 +151,7 @@ const ActionsExplorer = ({ getLinkGenerator }: Props) => {
               migratedLinks.map((link) => (
                 <React.Fragment>
                   <EuiLink
-                    color={link.isDeprecated ? 'danger' : 'primary'}
+                    color={link.version !== '0.0.2' ? 'danger' : 'primary'}
                     data-test-subj="linkToHelloPage"
                     href={link.link}
                     target="_blank"

diff --git a/...s/url_generators_examples/public/index.ts → examples/locator_explorer/public/index.ts b/...s/url_generators_examples/public/index.ts → examples/locator_explorer/public/index.ts
@@ -6,6 +6,6 @@
  * Side Public License, v 1.
  */
 
-import { AccessLinksExamplesPlugin } from './plugin';
+import { LocatorExplorerPlugin } from './plugin';
 
-export const plugin = () => new AccessLinksExamplesPlugin();
+export const plugin = () => new LocatorExplorerPlugin();
diff --git a/...s/url_generators_explorer/public/page.tsx → examples/locator_explorer/public/page.tsx b/...s/url_generators_explorer/public/page.tsx → examples/locator_explorer/public/page.tsx