Deprecation: use locationService in favor of getLocationSrv (#44813)

* deprecated

* updating documentation.

* added deprecation notice.

* Replacing deprecated getLocationSrv.

* Update docs/sources/developers/plugins/migration-guide.md

Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com>

* Update docs/sources/developers/plugins/migration-guide.md

Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com>

* Update docs/sources/developers/plugins/migration-guide.md

Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com>

* Update docs/sources/developers/plugins/migration-guide.md

Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com>

* updating according to feedback.

* Update docs/sources/developers/plugins/migration-guide.md

Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com>

* Update docs/sources/developers/plugins/migration-guide.md

Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com>

Co-authored-by: achatterjee-grafana <70489351+achatterjee-grafana@users.noreply.github.com>

docs/sources/developers/plugins/add-support-for-variables.md

@@ -80,26 +80,19 @@ For more information on the available variable formats, refer to [Advanced varia
 
 ## Set a variable from your plugin
 
-Not only can you read the value of a variable, you can also update the variable from your plugin. Use LocationSrv.update()
+Not only can you read the value of a variable, you can also update the variable from your plugin. Use `locationService.partial(query, replace)`.
 
 The following example shows how to update a variable called `service`.
 
 - `query` contains the query parameters you want to update. Query parameters controlling variables are prefixed with `var-`.
-- `partial: true` makes the update only affect the query parameters listed in `query`, and leaves the other query parameters unchanged.
 - `replace: true` tells Grafana to update the current URL state, rather than creating a new history entry.
 
 ```ts
-import { getLocationSrv } from '@grafana/runtime';
+import { locationService } from '@grafana/runtime';
 ```
 
 ```ts
-getLocationSrv().update({
-  query: {
-    'var-service': 'billing',
-  },
-  partial: true,
-  replace: true,
-});
+locationService.partial({ 'var-service': 'billing' }, true);
 ```
 
 > **Note:** Grafana queries your data source whenever you update a variable. Excessive updates to variables can slow down Grafana and lead to a poor user experience.

docs/sources/developers/plugins/migration-guide.md

@@ -15,6 +15,8 @@ This guide helps you identify the steps you need to take based on the Grafana ve
 - [From version 8.3.x to 8.4.x](#from-version-83x-to-84x)
   - [Value Mapping Editor has been removed from @grafana-ui library](#value-mapping-editor-has-been-removed-from-grafana-ui-library)
   - [Thresholds Editor has been removed from @grafana-ui library](#thresholds-editor-has-been-removed-from-grafana-ui-library)
+  - [8.4 Deprecations](#84-deprecations)
+    - [LocationService replaces getLocationSrv](#locationservice-replaces-getlocationsrv)
 - [From version 7.x.x to 8.x.x](#from-version-7xx-to-8xx)
   - [Backend plugin v1 support has been dropped](#backend-plugin-v1-support-has-been-dropped)
     - [1. Add dependency on grafana-plugin-sdk-go](#1-add-dependency-on-grafana-plugin-sdk-go)
@@ -48,6 +50,81 @@ Removed due to being an internal component.
 
 Removed due to being an internal component.
 
+### 8.4 deprecations
+
+#### LocationService replaces getLocationSrv
+
+In a previous release, we migrated to use a new routing system and introduced a new service for managing locations, navigation, and related information. In this release, we are making that new service the primary service.
+
+**Example:** Import the service.
+
+```ts
+// before
+import { getLocationSrv } from '@grafana/runtime';
+
+// after
+import { locationService } from '@grafana/runtime';
+```
+
+**Example:** Navigate to a path and add a new record in the navigation history so that you can navigate back to the previous one.
+
+```ts
+// before
+getLocationSrv.update({
+  path: '/route-to-navigate-to',
+  replace: false,
+});
+
+// after
+locationService.push('/route-to-navigate-to');
+```
+
+**Example:** Navigate to a path and replace the current record in the navigation history.
+
+```ts
+// before
+getLocationSrv.update({
+  path: '/route-to-navigate-to',
+  replace: true,
+});
+
+// after
+locationService.replace('/route-to-navigate-to');
+```
+
+**Example:** Update the search or query parameter for the current route and add a new record in the navigation history so that you can navigate back to the previous one.
+
+```ts
+// How to navigate to a new path
+// before
+getLocationSrv.update({
+  query: {
+    value: 1,
+  },
+  partial: true,
+  replace: false,
+});
+
+// after
+locationService.partial({ value: 1 });
+```
+
+**Example:** Update the search or query parameter for the current route and add replacing it in the navigation history.
+
+```ts
+// before
+getLocationSrv.update({
+  query: {
+    'var-variable': 1,
+  },
+  partial: true,
+  replace: true,
+});
+
+// after
+locationService.partial({ 'var-variable': 1 }, true);
+```
+
 ## From version 7.x.x to 8.x.x
 
 This section explains how to migrate Grafana v7.x.x plugins to the updated plugin system available in Grafana v8.x.x. Depending on your plugin, you need to perform one or more of the following steps. We have documented the breaking changes in Grafana v8.x.x and the steps you need to take to upgrade your plugin.

packages/grafana-runtime/src/services/LocationService.ts

@@ -5,7 +5,7 @@ import { attachDebugger, createLogger } from '@grafana/ui';
 import { config } from '../config';
 
 /**
- * @alpha
+ * @public
  * A wrapper to help work with browser location and history
  */
 export interface LocationService {
@@ -120,7 +120,7 @@ export class HistoryWrapper implements LocationService {
 }
 
 /**
- * @alpha
+ * @public
  * Parses a location search string to an object
  * */
 export function locationSearchToObject(search: string | number): UrlQueryMap {
@@ -137,12 +137,13 @@ export function locationSearchToObject(search: string | number): UrlQueryMap {
 }
 
 /**
- * @alpha
+ * @public
  */
 export let locationService: LocationService = new HistoryWrapper();
 
-/** @internal
+/**
  * Used for tests only
+ * @internal
  */
 export const setLocationService = (location: LocationService) => {
   if (process.env.NODE_ENV !== 'test') {

packages/grafana-runtime/src/services/LocationSrv.ts

@@ -1,13 +1,8 @@
-/**
- * Passed as options to the {@link LocationSrv} to describe how the automatically navigation
- * should be performed.
- *
- * @public
- */
 import { UrlQueryMap } from '@grafana/data';
 
 /**
  * @public
+ * @deprecated in favor of {@link locationService} and will be removed in Grafana 9
  */
 export interface LocationUpdate {
   /**
@@ -47,6 +42,7 @@ export interface LocationUpdate {
  * be done via the LocationSrv and it will make sure to update the application state accordingly.
  *
  * @public
+ * @deprecated in favor of {@link locationService} and will be removed in Grafana 9
  */
 export interface LocationSrv {
   update(options: LocationUpdate): void;
@@ -69,6 +65,7 @@ export function setLocationSrv(instance: LocationSrv) {
  * the user to a new place in Grafana.
  *
  * @public
+ * @deprecated in favor of {@link locationService} and will be removed in Grafana 9
  */
 export function getLocationSrv(): LocationSrv {
   return singletonInstance;

packages/grafana-runtime/src/services/appEvents.ts

@@ -40,8 +40,8 @@ export class CopyPanelEvent extends BusEventWithPayload<PanelModel> {
 let singletonInstance: EventBus;
 
 /**
- * Used during startup by Grafana to set the LocationSrv so it is available
- * via the {@link getLocationSrv} to the rest of the application.
+ * Used during startup by Grafana to set the setAppEvents so it is available
+ * via the {@link setAppEvents} to the rest of the application.
  *
  * @internal
  */

public/app/features/dashboard/components/PanelEditor/PanelEditorQueries.tsx

@@ -1,7 +1,7 @@
 import React, { PureComponent } from 'react';
 import { QueryGroup } from 'app/features/query/components/QueryGroup';
 import { PanelModel } from '../../state';
-import { getLocationSrv } from '@grafana/runtime';
+import { locationService } from '@grafana/runtime';
 import { QueryGroupDataSource, QueryGroupOptions } from 'app/types';
 import { DataQuery } from '@grafana/data';
 import { getDatasourceSrv } from 'app/features/plugins/datasource_srv';
@@ -47,9 +47,9 @@ export class PanelEditorQueries extends PureComponent<Props> {
   };
 
   onOpenQueryInspector = () => {
-    getLocationSrv().update({
-      query: { inspect: this.props.panel.id, inspectTab: 'query' },
-      partial: true,
+    locationService.partial({
+      inspect: this.props.panel.id,
+      inspectTab: 'query',
     });
   };
 

public/app/features/dashboard/dashgrid/PanelHeader/PanelHeaderCorner.tsx

@@ -2,7 +2,7 @@ import React, { Component } from 'react';
 
 import { renderMarkdown, LinkModelSupplier, ScopedVars } from '@grafana/data';
 import { Tooltip, PopoverContent } from '@grafana/ui';
-import { getLocationSrv, getTemplateSrv } from '@grafana/runtime';
+import { locationService, getTemplateSrv } from '@grafana/runtime';
 
 import { PanelModel } from 'app/features/dashboard/state/PanelModel';
 import { getTimeSrv, TimeSrv } from 'app/features/dashboard/services/TimeSrv';
@@ -74,7 +74,10 @@ export class PanelHeaderCorner extends Component<Props> {
    * Open the Panel Inspector when we click on an error
    */
   onClickError = () => {
-    getLocationSrv().update({ partial: true, query: { inspect: this.props.panel.id, inspectTab: InspectTab.Error } });
+    locationService.partial({
+      inspect: this.props.panel.id,
+      inspectTab: InspectTab.Error,
+    });
   };
 
   renderCornerType(infoMode: InfoMode, content: PopoverContent, onClick?: () => void) {

public/app/features/plugins/admin/hooks/useHistory.tsx

@@ -1,13 +1,9 @@
-import { getLocationSrv } from '@grafana/runtime';
+import { locationService } from '@grafana/runtime';
 
 export const useHistory = () => {
   return {
     push: ({ query }: any) => {
-      getLocationSrv().update({
-        partial: true,
-        replace: false,
-        query,
-      });
+      locationService.partial(query);
     },
   };
 };

public/app/features/search/components/ConfirmDeleteModal.tsx

@@ -2,7 +2,7 @@ import React, { FC } from 'react';
 import { css } from '@emotion/css';
 import { GrafanaTheme } from '@grafana/data';
 import { ConfirmModal, stylesFactory, useTheme } from '@grafana/ui';
-import { getLocationSrv } from '@grafana/runtime';
+import { locationService } from '@grafana/runtime';
 import { DashboardSection, OnDeleteItems } from '../types';
 import { getCheckedUids } from '../utils';
 import { deleteFoldersAndDashboards } from 'app/features/manage-dashboards/state/actions';
@@ -41,7 +41,7 @@ export const ConfirmDeleteModal: FC<Props> = ({ results, onDeleteItems, isOpen,
     deleteFoldersAndDashboards(folders, dashboards).then(() => {
       onDismiss();
       // Redirect to /dashboard in case folder was deleted from f/:folder.uid
-      getLocationSrv().update({ path: '/dashboards' });
+      locationService.push('/dashboards');
       onDeleteItems(folders, dashboards);
     });
   };

public/app/features/search/hooks/useDashboardSearch.ts

@@ -1,5 +1,5 @@
 import { KeyboardEvent, useReducer } from 'react';
-import { getLocationSrv } from '@grafana/runtime';
+import { locationService } from '@grafana/runtime';
 import { DashboardQuery, DashboardSearchItemType, DashboardSection } from '../types';
 import { MOVE_SELECTION_DOWN, MOVE_SELECTION_UP } from '../reducers/actionTypes';
 import { dashboardsSearchState, DashboardsSearchState, searchReducer } from '../reducers/dashboardSearch';
@@ -58,9 +58,7 @@ export const useDashboardSearch = (query: DashboardQuery, onCloseSearch: () => v
           if (selectedItem.type === DashboardSearchItemType.DashFolder) {
             onToggleSection(selectedItem as DashboardSection);
           } else {
-            getLocationSrv().update({
-              path: locationUtil.stripBaseFromUrl(selectedItem.url),
-            });
+            locationService.push(locationUtil.stripBaseFromUrl(selectedItem.url));
             // Delay closing to prevent current page flicker
             setTimeout(onCloseSearch, 0);
           }

public/app/plugins/panel/graph/module.ts

@@ -19,7 +19,7 @@ import { graphPanelMigrationHandler } from './GraphMigrations';
 import { DataWarning, GraphFieldConfig, GraphPanelOptions } from './types';
 
 import { auto } from 'angular';
-import { getLocationSrv } from '@grafana/runtime';
+import { locationService } from '@grafana/runtime';
 import { getDataTimeRange } from './utils';
 import { changePanelPlugin } from 'app/features/panel/state/actions';
 import { dispatch } from 'app/store/store';
@@ -266,12 +266,9 @@ export class GraphCtrl extends MetricsPanelCtrl {
     if (range) {
       dataWarning.actionText = 'Zoom to data';
       dataWarning.action = () => {
-        getLocationSrv().update({
-          partial: true,
-          query: {
-            from: range.from,
-            to: range.to,
-          },
+        locationService.partial({
+          from: range.from,
+          to: range.to,
         });
       };
     }