Skip to content

N
nexpie-grafana-theme
Commit ab8305fc by Marcus Andersson Committed by GitHub
Options

Docs: added code comments for everything in the @grafana/runtime package. (#23456) 

* added comments for the angular loader.

* added code documentation for backendSrv.

* docs for datasource_srv.

* added some more docs.

* added documentation for the locationsrv.

* started to add docs for echo srv.

* added docs for meta srv.2

* added docs for analytics.

* draft documentation of the DataSourceWithBackend.

* added docs for last files.

* fixed all warnigns in api-extractor.

* fixed some typos and captializations.
parent b3df2d00
Showing with 420 additions and 29 deletions
api-extractor.json
......@@ -23,6 +23,10 @@
"extractorMessageReporting": {
"default": {
"logLevel": "warning"
},
"ae-internal-missing-underscore": {
"logLevel": "none",
"addToApiReportFile": false
}
},
"tsdocMessageReporting": {
......
packages/grafana-runtime/src/config.ts
......@@ -2,32 +2,63 @@ import extend from 'lodash/extend';
import { getTheme } from '@grafana/ui';
import { DataSourceInstanceSettings, GrafanaTheme, GrafanaThemeType, PanelPluginMeta } from '@grafana/data';
/**
* Describes the build information that will be available via the Grafana cofiguration.
*
* @public
*/
export interface BuildInfo {
version: string;
commit: string;
isEnterprise: boolean; // deprecated: use licenseInfo.hasLicense instead
/**
* Is set to true when running Grafana Enterprise edition.
*
* @deprecated use `licenseInfo.hasLicense` instead
*/
isEnterprise: boolean;
env: string;
edition: string;
latestVersion: string;
hasUpdate: boolean;
}
interface FeatureToggles {
/**
* Describes available feature toggles in Grafana. These can be configured via the
* `conf/custom.ini` to enable features under development or not yet available in
* stable version.
*
* @public
*/
export interface FeatureToggles {
transformations: boolean;
expressions: boolean;
newEdit: boolean;
meta: boolean; // enterprise
/**
* @remarks
* Available only in Grafana Enterprise
*/
meta: boolean;
newVariables: boolean;
tracingIntegration: boolean;
}
interface LicenseInfo {
/**
* Describes the license information about the current running instance of Grafana.
*
* @public
*/
export interface LicenseInfo {
hasLicense: boolean;
expiry: number;
licenseUrl: string;
stateInfo: string;
}
/**
* Describes all the different Grafana configuration values available for an instance.
*
* @public
*/
export class GrafanaBootConfig {
datasources: { [str: string]: DataSourceInstanceSettings } = {};
panels: { [key: string]: PanelPluginMeta } = {};
......@@ -110,4 +141,9 @@ const bootData = (window as any).grafanaBootData || {
const options = bootData.settings;
options.bootData = bootData;
/**
* Use this to access the {@link GrafanaBootConfig} for the current running Grafana instance.
*
* @public
*/
export const config = new GrafanaBootConfig(options);
packages/grafana-runtime/src/index.ts
......@@ -6,6 +6,6 @@
export * from './services';
export * from './config';
export * from './types';
export { loadPluginCss, SystemJS } from './utils/plugin';
export { loadPluginCss, SystemJS, PluginCssOptions } from './utils/plugin';
export { reportMetaAnalytics } from './utils/analytics';
export { DataSourceWithBackend } from './utils/DataSourceWithBackend';
export { DataSourceWithBackend, HealthCheckResult, HealthStatus } from './utils/DataSourceWithBackend';
packages/grafana-runtime/src/services/AngularLoader.ts
/**
* Used to enable rendering of Angular components within a
* React component without loosing proper typings.
*
* @example
* ```typescript
* class Component extends PureComponent<Props> {
* element: HTMLElement;
* angularComponent: AngularComponent;
*
* componentDidMount() {
* const template = '<angular-component />' // angular template here;
* const scopeProps = { ctrl: angularController }; // angular scope properties here
* const loader = getAngularLoader();
* this.angularComponent = loader.load(this.element, scopeProps, template);
* }
*
* componentWillUnmount() {
* if (this.angularComponent) {
* this.angularComponent.destroy();
* }
* }
*
* render() {
* return (
* <div ref={element => (this.element = element)} />
* );
* }
* }
* ```
*
* @public
*/
export interface AngularComponent {
/**
* Should be called when the React component will unmount.
*/
destroy(): void;
/**
* Can be used to trigger a re-render of the Angular component.
*/
digest(): void;
/**
* Used to access the Angular scope from the React component.
*/
getScope(): any;
}
/**
* Used to load an Angular component from the context of a React component.
* Please see the {@link AngularComponent} for a proper example.
*
* @public
*/
export interface AngularLoader {
/**
*
* @param elem - the element that the Angular component will be loaded into.
* @param scopeProps - values that will be accessed via the Angular scope.
* @param template - template used by the Angular component.
*/
load(elem: any, scopeProps: any, template: string): AngularComponent;
}
let instance: AngularLoader;
/**
* Used during startup by Grafana to set the AngularLoader so it is available
* via the the {@link getAngularLoader} to the rest of the application.
*
* @internal
*/
export function setAngularLoader(v: AngularLoader) {
instance = v;
}
/**
* Used to retrieve the {@link AngularLoader} that enables the use of Angular
* components within a React component.
*
* Please see the {@link AngularComponent} for a proper example.
*
* @public
*/
export function getAngularLoader(): AngularLoader {
return instance;
}
packages/grafana-runtime/src/services/EchoSrv.ts
interface SizeMeta {
/**
* Describes a size with width/height
*
* @public
*/
export interface SizeMeta {
width: number;
height: number;
}
/**
* Describes the meta information that are sent together with each event.
*
* @public
*/
export interface EchoMeta {
screenSize: SizeMeta;
windowSize: SizeMeta;
......@@ -12,8 +22,17 @@ export interface EchoMeta {
* A unique browser session
*/
sessionId: string;
/**
* The current users username used to login into Grafana e.g. email.
*/
userLogin: string;
/**
* The current users uniqe identifier.
*/
userId: number;
/**
* True when user is logged in into Grafana.
*/
userSignedIn: boolean;
/**
* A millisecond epoch
......@@ -25,6 +44,11 @@ export interface EchoMeta {
timeSinceNavigationStart: number;
}
/**
* Describes echo backends that can be registered to receive of events.
*
* @public
*/
export interface EchoBackend<T extends EchoEvent = any, O = any> {
options: O;
supportedEvents: EchoEventType[];
......@@ -32,33 +56,84 @@ export interface EchoBackend<T extends EchoEvent = any, O = any> {
addEvent: (event: T) => void;
}
/**
* Describes an echo event.
*
* @public
*/
export interface EchoEvent<T extends EchoEventType = any, P = any> {
type: EchoEventType;
/**
* Event payload containing event specific data.
*/
payload: P;
meta: EchoMeta;
}
/**
* Supported echo event types that can be sent via the {@link EchoSrv}.
*
* @public
*/
export enum EchoEventType {
Performance = 'performance',
MetaAnalytics = 'meta-analytics',
}
/**
* Used to send events to all the registered backends. This should be accessed via the
* {@link getEchoSrv} function. Will, by default, flush events to the backends every
* 10s or when the flush function is triggered.
*
* @public
*/
export interface EchoSrv {
/**
* Call this to flush current events to the echo backends.
*/
flush(): void;
/**
* Add a new echo backend to the list of backends that will receive events.
*/
addBackend(backend: EchoBackend): void;
/**
* Call this to add event that will be sent to the echo backends upon next
* flush.
*
* @param event - Object containing event information.
* @param meta - Object that will extend/override the default meta object.
*/
addEvent<T extends EchoEvent>(event: Omit<T, 'meta'>, meta?: {}): void;
}
let singletonInstance: EchoSrv;
/**
* Used during startup by Grafana to set the EchoSrv so it is available
* via the the {@link getEchoSrv} to the rest of the application.
*
* @internal
*/
export function setEchoSrv(instance: EchoSrv) {
singletonInstance = instance;
}
/**
* Used to retrieve the {@link EchoSrv} that can be used to report events to registered
* echo backends.
*
* @public
*/
export function getEchoSrv(): EchoSrv {
return singletonInstance;
}
/**
* Used to register echo backends that will receive Grafana echo events during application
* runtime.
*
* @public
*/
export const registerEchoBackend = (backend: EchoBackend) => {
getEchoSrv().addBackend(backend);
};
packages/grafana-runtime/src/services/LocationSrv.ts
/**
* Passed as options to the {@link LocationSrv} to describe how the automatically navigation
* should be performed.
*
* @public
*/
export interface LocationUpdate {
/**
* Target path where you automatically wants to navigate the user.
*/
path?: string;
/**
* Specify this value if you want to add values to the query string of the URL.
*/
query?: UrlQueryMap;
/**
* Add the query argument to the existing URL
* If set to true, the query argument will be added to the existing URL.
*/
partial?: boolean;
/**
* Do not change this unless you are the angular router
* Used internally to sync the Redux state from Angular to make sure that the Redux location
* state is in sync when navigating using the Angular router.
*
* @remarks
* Do not change this unless you are the Angular router.
*
* @internal
*/
routeParams?: UrlQueryMap;
/*
* If true this will replace url state (ie cause no new browser history)
* If set to true, this will replace URL state (ie. cause no new browser history).
*/
replace?: boolean;
}
/**
* Type to represent the value of a single query variable.
*
* @public
*/
export type UrlQueryValue = string | number | boolean | string[] | number[] | boolean[] | undefined | null;
/**
* Type to represent the values parsed from the query string.
*
* @public
*/
export type UrlQueryMap = Record<string, UrlQueryValue>;
/**
* If you need to automatically navigate the user to a new place in the application this should
* be done via the LocationSrv and it will make sure to update the application state accordingly.
*
* @public
*/
export interface LocationSrv {
update(options: LocationUpdate): void;
}
let singletonInstance: LocationSrv;
/**
* Used during startup by Grafana to set the LocationSrv so it is available
* via the the {@link getLocationSrv} to the rest of the application.
*
* @internal
*/
export function setLocationSrv(instance: LocationSrv) {
singletonInstance = instance;
}
/**
* Used to retrieve the {@link LocationSrv} that can be used to automatically navigate
* the user to a new place in Grafana.
*
* @public
*/
export function getLocationSrv(): LocationSrv {
return singletonInstance;
}
packages/grafana-runtime/src/services/backendSrv.ts
/**
* Currently implemented with:
* https://docs.angularjs.org/api/ng/service/$http#usage
* but that will likely change in the future
* Used to initiate a remote call via the {@link BackendSrv}
*
* @public
*/
export type BackendSrvRequest = {
url: string;
/**
* Number of times to retry the remote call if it fails.
*/
retry?: number;
/**
* HTTP headers that should be passed along with the remote call.
* Please have a look at {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API | Fetch API}
* for supported headers.
*/
headers?: any;
/**
* HTTP verb to perform in the remote call GET, POST, PUT etc.
*/
method?: string;
// Show a message with the result
/**
* If set to true an alert with the response message will be displayed
* upon successful remote call
*/
showSuccessAlert?: boolean;
// A requestID is provided by the datasource as a unique identifier for a
// particular query. If the requestID exists, the promise it is keyed to
// is canceled, canceling the previous datasource request if it is still
// in-flight.
/**
* Provided by the initiator to identify a particular remote call. An example
* of this is when a datasource plugin triggers a query. If the request id already
* exist the backendSrv will try to cancel and replace the previous call with the
* new one.
*/
requestId?: string;
// Allow any other parameters
[key: string]: any;
};
/**
* Used to communicate via http(s) to a remote backend such as the Grafana backend,
* a datasource etc. The BackendSrv is using the {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API | Fetch API}
* under the hood to handle all the communication.
*
* The request function can be used to perform a remote call by specifing a {@link BackendSrvRequest}.
* To make the BackendSrv a bit easier to use we have added a couple of shorthand functions that will
* use default values executing the request.
*
* @remarks
* By default Grafana will display an error message alert if the remote call fails. If you want
* to prevent this from happending you need to catch the error thrown by the BackendSrv and
* set the `isHandled = true` on the incoming error.
*
* @public
*/
export interface BackendSrv {
get(url: string, params?: any, requestId?: string): Promise<any>;
delete(url: string): Promise<any>;
post(url: string, data?: any): Promise<any>;
patch(url: string, data?: any): Promise<any>;
put(url: string, data?: any): Promise<any>;
// If there is an error, set: err.isHandled = true
// otherwise the backend will show a message for you
request(options: BackendSrvRequest): Promise<any>;
// DataSource requests add hooks into the query inspector
/**
* Special function used to communicate with datasources that will emit core
* events that the Grafana QueryInspector and QueryEditor is listening for to be able
* to display datasource query information. Can be skipped by adding `option.silent`
* when initializing the request.
*/
datasourceRequest(options: BackendSrvRequest): Promise<any>;
}
let singletonInstance: BackendSrv;
/**
* Used during startup by Grafana to set the BackendSrv so it is available
* via the the {@link getBackendSrv} to the rest of the application.
*
* @internal
*/
export const setBackendSrv = (instance: BackendSrv) => {
singletonInstance = instance;
};
/**
* Used to retrieve the {@link BackendSrv} that can be used to communicate
* via http(s) to a remote backend such as the Grafana backend, a datasource etc.
*
* @public
*/
export const getBackendSrv = (): BackendSrv => singletonInstance;
packages/grafana-runtime/src/services/dataSourceSrv.ts
import { ScopedVars, DataSourceApi } from '@grafana/data';
/**
* This is the entry point for communicating with a datasource that is added as
* a plugin (both external and internal). Via this service you will get access
* to the {@link @grafana/data#DataSourceApi | DataSourceApi} that have a rich API for
* communicating with the datasource.
*
* @public
*/
export interface DataSourceSrv {
/**
* @param name - name of the datasource plugin you want to use.
* @param scopedVars - variables used to interpolate a templated passed as name.
*/
get(name?: string, scopedVars?: ScopedVars): Promise<DataSourceApi>;
}
let singletonInstance: DataSourceSrv;
/**
* Used during startup by Grafana to set the DataSourceSrv so it is available
* via the the {@link getDataSourceSrv} to the rest of the application.
*
* @internal
*/
export function setDataSourceSrv(instance: DataSourceSrv) {
singletonInstance = instance;
}
/**
* Used to retrieve the {@link DataSourceSrv} that is the entry point for communicating with
* a datasource that is added as a plugin (both external and internal).
*
* @public
*/
export function getDataSourceSrv(): DataSourceSrv {
return singletonInstance;
}
packages/grafana-runtime/src/services/templateSrv.ts
import { VariableModel } from '@grafana/data';
/**
* Via the TemplateSrv consumers get access to all the available template variables
* that can be used within the current active dashboard.
*
* For a mor in-depth description visit: https://grafana.com/docs/grafana/latest/reference/templating
* @public
*/
export interface TemplateSrv {
getVariables(): VariableModel[];
}
let singletonInstance: TemplateSrv;
/**
* Used during startup by Grafana to set the TemplateSrv so it is available
* via the the {@link getTemplateSrv} to the rest of the application.
*
* @internal
*/
export const setTemplateSrv = (instance: TemplateSrv) => {
singletonInstance = instance;
};
/**
* Used to retrieve the {@link TemplateSrv} that can be used to fetch available
* template variables.
*
* @public
*/
export const getTemplateSrv = (): TemplateSrv => singletonInstance;
packages/grafana-runtime/src/types/analytics.ts
import { EchoEvent, EchoEventType } from '../services/EchoSrv';
/**
* Describes the basic dashboard information that can be passed as the meta
* analytics payload.
*
* @public
*/
export interface DashboardInfo {
dashboardId: number;
dashboardUid: string;
......@@ -7,6 +13,11 @@ export interface DashboardInfo {
folderName?: string;
}
/**
* Describes the data request information passed as the meta analytics payload.
*
* @public
*/
export interface DataRequestInfo extends Partial<DashboardInfo> {
datasourceName: string;
datasourceId?: number;
......@@ -17,19 +28,44 @@ export interface DataRequestInfo extends Partial<DashboardInfo> {
dataSize?: number;
}
/**
* The meta analytics events that can be added to the echo service.
*
* @public
*/
export enum MetaAnalyticsEventName {
DashboardView = 'dashboard-view',
DataRequest = 'data-request',
}
/**
* Describes the payload of a dashboard view event.
*
* @public
*/
export interface DashboardViewEventPayload extends DashboardInfo {
eventName: MetaAnalyticsEventName.DashboardView;
}
/**
* Describes the payload of a data request event.
*
* @public
*/
export interface DataRequestEventPayload extends DataRequestInfo {
eventName: MetaAnalyticsEventName.DataRequest;
}
/**
* Describes the meta analytics payload passed with the {@link MetaAnalyticsEvent}
*
* @public
*/
export type MetaAnalyticsEventPayload = DashboardViewEventPayload | DataRequestEventPayload;
/**
* Describes meta analytics event with predefined {@link EchoEventType.MetaAnalytics} type.
*
* @public
*/
export interface MetaAnalyticsEvent extends EchoEvent<EchoEventType.MetaAnalytics, MetaAnalyticsEventPayload> {}
packages/grafana-runtime/src/utils/DataSourceWithBackend.ts
......@@ -10,21 +10,37 @@ import { Observable, from } from 'rxjs';
import { config } from '..';
import { getBackendSrv } from '../services';
// Ideally internal (exported for consistency)
const ExpressionDatasourceID = '__expr__';
/**
* Describes the current healt status of a data source plugin.
*
* @public
*/
export enum HealthStatus {
Unknown = 'UNKNOWN',
OK = 'OK',
Error = 'ERROR',
}
/**
* Describes the payload returned when checking the health of a data source
* plugin.
*
* @public
*/
export interface HealthCheckResult {
status: HealthStatus;
message: string;
details?: Record<string, any>;
}
/**
* Extend this class to implement a data source plugin that is depending on the Grafana
* backend API.
*
* @public
*/
export class DataSourceWithBackend<
TQuery extends DataQuery = DataQuery,
TOptions extends DataSourceJsonData = DataSourceJsonData
......@@ -86,6 +102,8 @@ export class DataSourceWithBackend<
/**
* Override to apply template variables
*
* @virtual
*/
applyTemplateVariables(query: DataQuery) {
return query;
......
packages/grafana-runtime/src/utils/analytics.ts
import { getEchoSrv, EchoEventType } from '../services/EchoSrv';
import { MetaAnalyticsEvent, MetaAnalyticsEventPayload } from '../types/analytics';
/**
* Helper function to report meta analytics to the {@link EchoSrv}.
*
* @public
*/
export const reportMetaAnalytics = (payload: MetaAnalyticsEventPayload) => {
getEchoSrv().addEvent<MetaAnalyticsEvent>({
type: EchoEventType.MetaAnalytics,
......
packages/grafana-runtime/src/utils/plugin.ts
......@@ -3,13 +3,29 @@ import { config } from '../config';
// @ts-ignore
import System from 'systemjs/dist/system.js';
/**
* Option to specify a plugin css that should be applied for the dark
* and the light theme.
*
* @public
*/
export interface PluginCssOptions {
light: string;
dark: string;
}
/**
* @internal
*/
export const SystemJS = System;
/**
* Use this to load css for a Grafana plugin by specifying a {@link PluginCssOptions}
* containing styling for the dark and the light theme.
*
* @param options - plugin styling for light and dark theme.
* @public
*/
export function loadPluginCss(options: PluginCssOptions): Promise<any> {
const theme = config.bootData.user.lightTheme ? options.light : options.dark;
return SystemJS.import(`${theme}!css`);
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment