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. |
Execute(props) | The executor provides a more curated experience to obtain and work with data from backends. |
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. |
isLocale(locale) | Type-guard for language codes that can be used with GoodData. |
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. |
pickCorrectMetricWording(translations, settings) | (BETA) The function to pick correct wording 'measure' or 'metric' |
pickCorrectWording(translations, settings) | (BETA) |
PlaceholdersProvider(props) | Wraps component into a PlaceholdersContext consumer enabling the children of this to access the current placeholders state. |
removeAllWordingTranslationsWithSpecialSuffix(translations) | (BETA) The function to remove all translation keys that contain special suffixes "._measure" or "._metric" |
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. |
useBackend(backend) | Hook to get analytical backend instance provided to BackendProvider. |
useBackendStrict(backend, context) | Hook to get analytical backend instance provided to BackendProvider. |
useBackendWithCorrelation(backend, correlationMetadata) | Hook to get a backend instance with correlation metadata from context, and optionally merge them with additional correlation metadata provided as a parameter. |
useCancelablePromise(options, deps) | This hook provides easy way to work with Promises in React components. |
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". |
useComposedPlaceholder(placeholder, resolutionContext) | React hook to obtain composed placeholder value. |
useCorrelationData() | Hook to get correlation metadata from the nearest correlation provider. |
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. |
useLocalStorage(key, initialValue) | Hook for using local storage. Ideally, you want to keep initial value immutable to avoid unnecessary re-renders. |
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). |
useWorkspace(workspace) | Hook to get workspace instance provided to WorkspaceProvider. |
useWorkspaceStrict(workspace, context) | Hook to get workspace instance provided to WorkspaceProvider. |
withTranslationsCustomization(Component) | (BETA) |
Interfaces
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. |
ExecuteInsight | Gets data for a specific stored insight. |
HeaderPredicates | Set of factory functions to create the most commonly-used HeaderPredicates. |
Kpi | Kpi is a simple component which calculates and renders a single formatted measure value. |
RawExecute | Raw executor is the most basic React component to drive custom executions to obtain data from backends. |
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. |
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. |
ITableColumnDefinition | (ALPHA) |
ITableData | (ALPHA) |
ITableDataHeaderScope | (ALPHA) |
ITableDataValue | (ALPHA) |
ITableRowDefinition | (ALPHA) |
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 |