Overview of sdk-ui
sdk-ui package
This package provides base functionality useful for building React visualizations on top of GoodData.
Remarks
The functionality includes functions for getting data from the Analytical Backend, components and React hooks that serve as building blocks for custom visualizations, visualization definition placeholders, support for drilling, and so on.
See the other @gooddata/sdk-ui-* packages (for example, @gooddata/sdk-ui-charts) for pre-built visualizations that you can use instead of building your own.
Classes
| Class | Description |
|---|---|
| BadRequestSdkError | This error means that server could not understand the request due to invalid syntax. |
| CancelledSdkError | This error means that request has been cancelled usually after component has been unmounted. |
| ClusteringNotReceivedSdkError | This error means that execution of forecast ended with error. |
| DataTooLargeToComputeSdkError | This error means that processed request would generate a result too large to be processed by the backend. |
| DataTooLargeToDisplaySdkError | This error means that executed data were too large to be displayed by GoodData.UI. |
| DataViewFacade | Wrapper for IDataView. |
| DataViewLoader | (ALPHA) DataViewLoader allows you to speficy, load and access data results with convenient series and slices API. |
| DynamicScriptLoadSdkError | This error means that loading of dynamic script/plugin failed. |
| ErrorComponent | Component that renders a default error message. |
| ForecastNotReceivedSdkError | This error means that execution of forecast ended with error. |
| GeoLocationMissingSdkError | This error means that location bucket is missing |
| GeoTokenMissingSdkError | This error means that mapbox token of GeoChart is missing |
| LoadingComponent | Component that renders a default loading indicator. |
| NegativeValuesSdkError | This error means that processed result contains negative values which does not make sense within the given visualization (e.g. pie chart with negative values). |
| NoDataSdkError | This error means that the processed result does not contain any data. |
| NotFoundSdkError | This error means that requested entity (e.g. a visualization) was not found on the server. |
| ProtectedReportSdkError | This error means that requested visualization is restricted by access rules. Please contact your administrator. |
| UnauthorizedSdkError | This error means that you are not authorized. |
| UnexpectedSdkError | This error means that GoodData.UI does not know how to handle such error. |
Abstract Classes
| Abstract Class | Description |
|---|---|
| GoodDataSdkError | Base class for all anticipated GoodData.UI SDK errors. |
Functions
| Function | Description |
|---|---|
| attributeItemNameMatch(name) | Creates a predicate that return true for any attribute result header with the provided name. |
| composedFromIdentifier(identifier) | Creates a new predicate that returns true of any arithmetic measure where measure with the provided identifier is used as an operand. |
| composedFromUri(uri) | Creates a new predicate that returns true of any arithmetic measure where measure with the provided URI is used as an operand. |
| compressForUrl(data) | Compresses data to a URL-safe string |
| convertDrillableItemsToPredicates(drillableItems) | |
| convertError(error) | Converts any error into an instance of GoodDataSdkError. |
| createNumberJsFormatter(separators) | Creates value formatter that uses @gooddata/number-formatter to format raw measure values according to the format string. |
| decompressFromUrl(compressedData) | Decompresses data from a URL-safe string |
| defaultErrorHandler(error) | Default error handler - logs error to console as error. |
| identifierMatch(identifier) | Creates a new predicate that returns true for any header that belongs to either attribute or measure with the provided identifier. |
| isAnyPlaceholder(obj) | Type-guard testing whether the provided object is an instance of AnyPlaceholder. |
| isBadRequest(obj) | Typeguard checking whether input is an instance of BadRequestSdkError; |
| isCancelledSdkError(obj) | Typeguard checking whether input is an instance of CancelledSdkError; |
| isClusteringNotReceived(obj) | Typeguard checking whether input is an instance of ClusteringNotReceivedSdkError |
| isComposedPlaceholder(obj) | Type-guard testing whether the provided object is an instance of IComposedPlaceholder. |
| isDataTooLargeToCompute(obj) | Typeguard checking whether input is an instance of DataTooLargeToComputeSdkError; |
| isDataTooLargeToDisplay(obj) | Typeguard checking whether input is an instance of DataTooLargeToDisplaySdkError; |
| isDrillableItem(item) | |
| isDrillableItemIdentifier(item) | |
| isDrillableItemUri(item) | |
| isDrillIntersectionAttributeItem(header) | |
| isDynamicScriptLoadSdkError(obj) | Typeguard checking whether input is an instance of DynamicScriptLoadSdkError; |
| isExplicitDrill(obj) | |
| isForecastNotReceived(obj) | Typeguard checking whether input is an instance of ForecastNotReceivedSdkError |
| isGeoLocationMissing(obj) | Typeguard checking whether input is an instance of GeoLocationMissingSdkError; |
| isGeoTokenMissing(obj) | Typeguard checking whether input is an instance of GeoTokenMissingSdkError; |
| isGoodDataSdkError(obj) | Typeguard checking whether input is an instance of GoodDataSdkError; |
| isHeaderPredicate(obj) | Typeguard checking whether the object is an IHeaderPredicate instance. |
| isNegativeValues(obj) | Typeguard checking whether input is an instance of NegativeValuesSdkError; |
| isNoDataSdkError(obj) | Typeguard checking whether input is an instance of NoDataSdkError; |
| isNotFound(obj) | Typeguard checking whether input is an instance of NotFoundSdkError; |
| isPlaceholder(obj) | Type-guard testing whether the provided object is an instance of IPlaceholder. |
| isProtectedReport(obj) | Typeguard checking whether input is an instance of ProtectedReportSdkError; |
| isUnauthorized(obj) | Typeguard checking whether input is an instance of UnauthorizedSdkError; |
| isUnknownSdkError(obj) | Typeguard checking whether input is an instance of UnexpectedSdkError; |
| localIdentifierMatch(localIdOrMeasure) | Creates a new predicate that returns true for any header that belongs to either attribute or measure with the provided local identifier. |
| newComposedPlaceholder(placeholders, computeValue) | Create a new composed placeholder. See IComposedPlaceholder. |
| newErrorMapping(intl) | Returns a new, localized error code descriptors. |
| newPlaceholder(defaultValue, options) | Create a new placeholder. See IPlaceholder. |
| objMatch(obj) | Creates a new predicate that returns true for any header that belongs to either attribute or measure matching the provided object. |
| objRefMatch(objRef) | Creates a new predicate that returns true for any header that belongs to either attribute or measure with the provided object reference. |
| PlaceholdersProvider(props) | Wraps component into a PlaceholdersContext consumer enabling the children of this to access the current placeholders state. |
| resolveLCMWorkspaceIdentifiers(backend, { client, dataProduct, workspace }) | (ALPHA) Resolves LCM workspace identifiers. This function will use the data product and client information and consult the backend in order to obtain identifier of workspace contains analytics for that data product & client combination. Note that at the moment only the bear Analytical Backend supports the workspace identification using LCM workspace identifiers. Attempting to use this function for other backends will yield empty result. |
| resolveUseCancelablePromisesError(states) | Resolve error of multiple useCancelablePromise() hooks - gets first error in the sequence of cancelable promise states. |
| resolveUseCancelablePromisesStatus(cancelablePromisesStates, options) | Resolve status of multiple useCancelablePromise() hooks. |
| uriMatch(uri) | Creates a new predicate that returns true for any header that belongs to either attribute or measure with the provided URI. |
| useCancelablePromise(options, deps) | This hook provides easy way to work with Promises in React components. |
| useComposedPlaceholder(placeholder, resolutionContext) | React hook to obtain composed placeholder value. |
| useDataExport({ execution, exportConfig, onCancel, onError, onLoading, onPending, onSuccess, }, deps) | This hook provides easy way to export data in your preferred format (csv/xlsx/raw) for the provided IPreparedExecution. |
| useExecutionDataView(config, deps) | React hook to get data for a specific execution. |
| useInsightDataView(config, deps) | React hook to get data for a specific insight. |
| usePagedResource(resourceFactory, fetchParams, fetchDeps, resetDeps, getCacheKey, initialState, preventResetPromises) | Hook for getting data from paged resource |
| usePlaceholder(placeholder) | React hook to obtain/set placeholder value. |
| usePlaceholders(placeholders) | React hook to obtain/set multiple placeholder values at once. |
| useResolveValuesWithPlaceholders(values, resolutionContext) | React hook that resolves multiple value(s) that can possibly contain also placeholder(s) to actual value(s). |
| useResolveValueWithPlaceholders(value, resolutionContext) | React hook that resolves any value(s) that can possibly contain also placeholder(s) to actual value(s). |
| withTranslationsCustomization(Component) | (BETA) |
Interfaces
| Interface | Description |
|---|---|
| IBackendProviderProps | Props of the BackendProvider component. |
| IBackendProviderWithCorrelationProps | Combined provider for both backend and correlation metadata. |
| IClientWorkspaceIdentifiers | (ALPHA) Resolved LCM identifiers of the workspace. |
| IClientWorkspaceProviderCoreProps | (ALPHA) Common props of the ClientWorkspaceProvider. |
| IClientWorkspaceProviderWithClientAndDataProductProps | (ALPHA) |
| IClientWorkspaceProviderWithWorkspaceProps | (ALPHA) |
| IComposedPlaceholder | Represents placeholder composed from other placeholders. |
| ICorrelationProviderProps | Props of the CorrelationProvider component. |
| IDataAccessMethods | Defines methods to access data in the data view. |
| IDataSeries | Data series is a sequence of data points that are all computed from a single measure, scoped for particular attribute elements. |
| IDataSeriesCollection | An iterable collection of data series. |
| IDataSlice | Data slice is a sequence of data points that are all computed for a particular attribute elements and/or totals but different data series. |
| IDataSliceCollection | An iterable collection of data slices. |
| IDataVisualizationProps | Common props for visualization of data computed by the analytical backend. |
| IDrillableItemIdentifier | |
| IDrillableItemUri | |
| IDrillConfig | |
| IDrillEvent | |
| IDrillEventContext | Drill context for all visualization type. |
| IDrillEventContextGroup | Drill context for chart element group (multiple series + click on axis value) where every point has own intersection. |
| IDrillEventContextHeadline | Drill context for headline |
| IDrillEventContextPoint | Drill context for pointy-charts |
| IDrillEventContextTable | Drill context for table |
| IDrillEventContextXirr | Drill context for XIRR |
| IDrillEventIntersectionElement | |
| IDrillIntersectionAttributeItem | |
| IDrillPoint | Drill context for headline |
| IErrorDescriptors | Mapping between error code and human readable description of the error. Key is error code as defined in ErrorCodes. |
| IErrorProps | Props of the ErrorComponent. |
| IExecuteErrorComponentProps | Properties of the error component provided to Execute or RawExecute components |
| IExecuteInsightProps | Props of the ExecuteInsight component. |
| IExecuteProps | Props of the Execute component. |
| IExecutionConfiguration | Convenient interface to define execution by series and slices. |
| IExtendedExportConfig | |
| IHeaderPredicateContext | Additional data that describes the context in which the IHeaderPredicate match is being tested. |
| IHighchartsCategoriesTree | |
| IHighchartsParentTick | |
| IKpiProps | Props of the Kpi component. |
| ILoadingProps | Props of the LoadingComponent. |
| ILoadingState | |
| IPlaceholderOptions | Common placeholder options. |
| IPlaceholdersProviderProps | Props of the PlaceholdersProvider() component. |
| IRawExecuteProps | Props of the RawExecute component. |
| ITranslationsCustomizationContextProviderProps | (BETA) |
| ITranslationsCustomizationProviderProps | (BETA) |
| IUseExecutionDataViewConfig | Configuration for useExecutionDataView() hook. See also UseExecutionDataViewCallbacks. |
| IUseInsightDataViewConfig | Configuration for useInsightDataView() hook. |
| IUsePagedResourceResult | |
| IUsePagedResourceState | |
| IVisualizationCallbacks | Super-interface for all visualization callbacks. |
| IVisualizationProps | Super-interface for all visualization props. |
| IWithLoadingEvents | |
| IWorkspaceProviderProps | Props of the WorkspaceProvider component. |
Variables
| Variable | Description |
|---|---|
| BackendProvider | BackendProvider can be used to inject analytical backend instance to all ui-sdk components in your app. |
| BackendProviderWithCorrelation | Combined provider for both backend and correlation metadata. This is a convenience component that wraps BackendProvider and CorrelationProvider to provide both a backend instance and correlation metadata to components. |
| ClientWorkspaceProvider | (ALPHA) ClientWorkspaceProvider can be used as a replacement of the WorkspaceProvider, if you want to work with the workspace in LCM context. It allows you to: - Use dataProduct and client identifier as a replacement of the workspace identifier. Workspace identifier is resolved and provided to the WorkspaceProvider automatically. - Use workspace identifier to obtain dataProduct, client and segment identifiers by the useClientWorkspaceIdentifiers hooks. If the backend does not support clientId / dataProduct LCM provisioning, or the workspace is not provisioned via LCM, segment / client / dataProduct values will be undefined. To read more details about LCM, see: https://help.gooddata.com/pages/viewpage.action?pageId=86796865 |
| CorrelationProvider | CorrelationProvider provides request correlation metadata to components. When nested, correlation metadata from ancestor providers is merged with the current provider. |
| DefaultColorPalette | Default value for IColorPalette. |
| DefaultDataAccessConfig | Default configuration for the data access methods. Uses default @gooddata/number-formatter formatter and no result formatting. |
| DefaultLocale | Default value for ILocale. |
| ErrorCodes | Error codes recognized by the SDK. |
| Execute | The executor provides a more curated experience to obtain and work with data from backends. |
| ExecuteInsight | Gets data for a specific stored insight. |
| HeaderPredicates | Set of factory functions to create the most commonly-used HeaderPredicates. |
| isLocale | Type-guard for language codes that can be used with GoodData. |
| Kpi | Kpi is a simple component which calculates and renders a single formatted measure value. |
| pickCorrectInsightWording | (BETA) |
| pickCorrectMetricWording | (BETA) The function to pick correct wording 'measure' or 'metric' |
| pickCorrectWording | (BETA) |
| RawExecute | Raw executor is the most basic React component to drive custom executions to obtain data from backends. |
| removeAllInsightToReportTranslations | (BETA) |
| removeAllWordingTranslationsWithSpecialSuffix | (BETA) The function to remove all translation keys that contain special suffixes "|report", "|insight", "._measure" or "._metric" |
| ResolvedClientWorkspaceProvider | (ALPHA) ResolvedClientWorkspaceProvider can be used as a replacement of the WorkspaceProvider, if you are accessing workspace in LCM context. This provider expects that the client workspace is already resolved on input to the provider. The provider will then establish a client workspace and workspace contexts so that the resolved information can be accessed by the children. Note: check out the ClientWorkspaceProvider for version of provider that performs the resolution of client workspace identifiers to workspace. |
| TranslationsCustomizationContextProvider | (BETA) |
| TranslationsCustomizationProvider | (BETA) This provider is here because of the need for customization of translations. |
| useBackend | Hook to get analytical backend instance provided to BackendProvider. |
| useBackendStrict | Hook to get analytical backend instance provided to BackendProvider. |
| useBackendWithCorrelation | Hook to get a backend instance with correlation metadata from context, and optionally merge them with additional correlation metadata provided as a parameter. |
| useClientWorkspaceError | (ALPHA) Hook to obtain loading error of the ClientWorkspaceProvider. |
| useClientWorkspaceIdentifiers | (ALPHA) Hook to obtain all resolved identifiers from the ClientWorkspaceProvider - workspace, segment, dataProduct and client. |
| useClientWorkspaceInitialized | (ALPHA) Hook to check if client workspace is initialized. |
| useClientWorkspaceStatus | (ALPHA) Hook to obtain loading status of the ClientWorkspaceProvider - "success", "error", "loading" or "pending". |
| useCorrelationData | Hook to get correlation metadata from the nearest correlation provider. |
| useLocalStorage | Hook for using local storage. Ideally, you want to keep initial value immutable to avoid unnecessary re-renders. |
| useWorkspace | Hook to get workspace instance provided to WorkspaceProvider. |
| useWorkspaceStrict | Hook to get workspace instance provided to WorkspaceProvider. |
| WorkspaceProvider | WorkspaceProvider can be used to inject analytical workspace instance to all ui-sdk components in your app. |
Type Aliases
| Type Alias | Description |
|---|---|
| AnyArrayOf | Generate all possible combinations of arrays signatures for the union type. |
| AnyMeasure | Represents all possible measure signatures. |
| AnyPlaceholder | Any placeholder type - placeholder or composed placeholder. |
| AnyPlaceholderOf | Generate all possible combinations of placeholder signatures for the union type. |
| ArrayOf | Wrap each member of union type in the array. |
| AttributeFilterOrPlaceholder | Alias for all possible attribute filter or placeholder signatures. |
| AttributeFiltersOrPlaceholders | Alias for all possible attribute filters or their placeholder signatures. |
| AttributeMeasureOrPlaceholder | Alias for all possible attribute, measure or placeholder signatures. |
| AttributeOrPlaceholder | Alias for all possible attribute or placeholder signatures. |
| AttributesMeasuresOrPlaceholders | Alias for all possible attributes, measures or their placeholders signatures. |
| AttributesOrPlaceholders | Alias for all possible attributes or their placeholder signatures. |
| ChartElementType | |
| ChartType | |
| ComposedPlaceholderResolutionContext | Get composed placeholder resolution context type. |
| DataAccessConfig | |
| DataPoint | Data Point represents a value computed for particular data series, possibly sliced for additional set of attribute elements OR possibly being a total. |
| DataPointCoordinates | |
| DataSeriesDescriptor | Full descriptive information about the data series. |
| DataSeriesDescriptorMethods | |
| DataSeriesHeaders | |
| DataSeriesId | |
| DataSliceDescriptor | Full descriptive information of a data slice includes all attribute element and total headers for the slice and next to them descriptors of attribute objects whose elements figure in the headers. |
| DataSliceDescriptorMethods | |
| DataSliceHeaders | Data slice name is specified using the result headers. |
| DataSliceId | |
| DataViewWindow | Structure specifying a particular portion of data. |
| DrillEventIntersectionElementHeader | |
| ExplicitDrill | Drillable item reference or predicate that enables insight / kpi drilling if it matches some attribute or measure of the insight / kpi. |
| FilterOrMultiValuePlaceholder | |
| FilterOrPlaceholder | Alias for all possible filter or placeholder signatures. |
| FiltersOrPlaceholders | Alias for all possible filters or their placeholder signatures. |
| Flatten | Flatten array type. |
| HeaderTranslator | |
| HeadlineElementType | |
| HeadlineType | |
| IClientWorkspaceProviderProps | (ALPHA) Props of the ClientWorkspaceProvider component. |
| IDrillableItem | |
| IDrillEventCallback | |
| IExecuteErrorComponent | Represents an error component provided to Execute or RawExecute components |
| IExecuteLoadingComponent | Represents a loading component provided to Execute or RawExecute components |
| IExportFunction | |
| IHeaderPredicate | A function called for IMappingHeader instances. |
| ILocale | Language codes that can be used with GoodData. |
| IMappingHeader | |
| IPlaceholder | Placeholder represents a reference to a specific part of the execution - attribute(s), measure(s), filter(s), sort(s) or total(s), that may change the value at runtime. |
| IUseComposedPlaceholderHook | React hook to obtain IComposedPlaceholder value. |
| IUsePlaceholderHook | React hook to obtain and set IPlaceholder value. |
| MeasureOf | Generate union of measures from union of measure definitions. |
| MeasureOrPlaceholder | Alias for all possible measure or placeholder signatures. |
| MeasuresOrPlaceholders | Alias for all possible measures or their placeholder signatures. |
| NullableFilterOrPlaceholder | Alias for all possible nullable filter or placeholder signatures. |
| NullableFiltersOrPlaceholders | Alias for all possible nullable filters or their placeholder signatures. |
| OnDataView | (ALPHA) |
| OnError | |
| OnExportReady | |
| OnFiredDrillEvent | |
| OnLoadingChanged | |
| PlaceholderOf | Wrap each member of the union type in AnyPlaceholder. |
| PlaceholderResolvedValue | Convert any value that may contain placeholders to its resolved value type. |
| PlaceholdersResolvedValues | Convert tuple of values that may contain placeholders to tuple of their respective resolved value types. |
| PlaceholdersValues | Convert tuple of placeholders to tuple of their respective value types. |
| PlaceholderValue | Get placeholder value type. |
| SdkErrorType | |
| SortsOrPlaceholders | Alias for all possible sorts or their placeholders signatures. |
| TableElementType | |
| TableType | |
| TotalsOrPlaceholders | Alias for all possible totals or their placeholders signatures. |
| UnionToIntersection | Convert union type to intersection type. |
| UseCancelablePromiseCallbacks | Callbacks for useCancelablePromise() hook |
| UseCancelablePromiseErrorState | Indicates error state for useCancelablePromise() hook |
| UseCancelablePromiseLoadingState | Indicates loading state for useCancelablePromise() hook |
| UseCancelablePromiseOptions | Options for the useCancelablePromise() hook. |
| UseCancelablePromisePendingState | Indicates pending state for useCancelablePromise() hook |
| UseCancelablePromiseState | Indicates the current state of useCancelablePromise() hook |
| UseCancelablePromiseStatus | Indicates the current state of the promise inside useCancelablePromise() hook |
| UseCancelablePromiseSuccessState | Indicates success state for useCancelablePromise() hook |
| UseDataExportCallbacks | Callbacks for useDataExport hook |
| UseDataExportState | Indicates current state of useDataExport hook |
| UseExecutionDataViewCallbacks | Callbacks for useExecutionDataView() hook. |
| UseInsightDataViewCallbacks | Callbacks for useInsightDataView() hook. |
| ValueFormatter | |
| ValueOrMultiValuePlaceholder | |
| ValueOrPlaceholder | Represents value of type T or any placeholder that may hold value T. |
| ValuesOrPlaceholders | Represents array of values T or placeholders that may hold value T. |
| VisElementType | |
| VisType | |
| WithLoadingResult | |
| XirrType |