survey-analytics
Version:
SurveyJS Dashboard is a UI component for visualizing and analyzing survey data. It interprets the form JSON schema to identify question types and renders collected responses using interactive charts and tables.
368 lines (367 loc) • 15.1 kB
TypeScript
import { Question, Event } from "survey-core";
import { DataProvider, GetDataFn } from "./dataProvider";
import "./visualizerBase.scss";
export interface IChartAdapter {
getChartTypes(): string[];
create(chartNode: HTMLElement): Promise<any>;
update(chartNode: HTMLElement): Promise<any>;
destroy(node: HTMLElement): void;
}
export interface IDataInfo {
name: string;
dataPath?: string;
dataNames: Array<string>;
getValues(): Array<any>;
getLabels(): Array<string>;
getSeriesValues(): Array<string>;
getSeriesLabels(): Array<string>;
}
type ToolbarItemCreators = {
[name: string]: {
creator: (toolbar?: HTMLDivElement) => HTMLElement;
order: number;
};
};
export declare class PostponeHelper {
static postponeFunction: (fn: () => void, timeout?: number) => any;
static postpone(fn: () => void, timeout?: number): any;
}
/**
* A base object for all visualizers. Use it to implement a custom visualizer.
*
* Constructor parameters:
*
* - `question`: [`Question`](https://surveyjs.io/form-library/documentation/api-reference/question)\
* A survey question to visualize.
* - `data`: `Array<any>`\
* Survey results.
* - `options`\
* An object with the following properties:
* - `dataProvider`: `DataProvider`\
* A data provider for this visualizer.
* - `renderContent`: `(contentContainer: HTMLElement, visualizer: VisualizerBase) => void`\
* A function that renders the visualizer's HTML markup. Append the markup to `contentContainer`.
* - `survey`: [`SurveyModel`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model)\
* Pass a `SurveyModel` instance if you want to use locales from the survey JSON schema.
* - `seriesValues`: `Array<string>`\
* Series values used to group data.
* - `seriesLabels`: `Array<string>`\
* Series labels to display. If this property is not set, `seriesValues` are used as labels.
* - `type`: `string`\
* *(Optional)* The visualizer's type.
*
* [View Demo](https://surveyjs.io/dashboard/examples/how-to-plot-survey-data-in-custom-bar-chart/ (linkStyle))
*/
export declare class VisualizerBase implements IDataInfo {
question: Question;
options: {
[index: string]: any;
};
private _type?;
static haveCommercialLicense: boolean;
static suppressVisualizerStubRendering: boolean;
static chartAdapterType: any;
private _showToolbar;
private _footerVisualizer;
private _dataProvider;
private _getDataCore;
labelTruncateLength: number;
protected haveCommercialLicense: boolean;
protected renderResult: HTMLElement;
protected toolbarContainer: HTMLElement;
protected headerContainer: HTMLElement;
protected contentContainer: HTMLElement;
protected footerContainer: HTMLElement;
protected _supportSelection: boolean;
protected _chartAdapter: IChartAdapter;
static otherCommentCollapsed: boolean;
protected _footerIsCollapsed: boolean;
/**
* An event that is raised after the visualizer's content is rendered.
*
* Parameters:
*
* - `sender`: `VisualizerBase`\
* A `VisualizerBase` instance that raised the event.
*
* - `options.htmlElement`: `HTMLElement`\
* A page element with the visualizer's content.
* @see render
* @see refresh
**/
onAfterRender: Event<(sender: VisualizerBase, options: any) => any, VisualizerBase, any>;
protected afterRender(contentContainer: HTMLElement): void;
/**
* An event that is raised after a new locale is set.
*
* Parameters:
*
* - `sender`: `VisualizerBase`\
* A `VisualizerBase` instance that raised the event.
*
* - `options.locale`: `string`\
* The indentifier of a new locale (for example, "en").
* @see locale
*/
onLocaleChanged: Event<(sender: VisualizerBase, options: {
locale: string;
}) => any, VisualizerBase, any>;
/**
* An event that is raised when the visualizer's state has changed.
*
* The state includes selected chart types, chart layout, sorting, filtering, and other customizations that a user has made while using the dashboard. Handle the `onStateChanged` event to save these customizations, for example, in `localStorage` and restore them when the user reloads the page.
*
* Parameters:
*
* - `sender`: `VisualizerBase`\
* A `VisualizerBase` instance that raised the event.
*
* - `state`: `any`\
* A new state of the visualizer. Includes information about the visualized elements and current locale.
*
* [View Demo](https://surveyjs.io/dashboard/examples/save-dashboard-state-to-local-storage/ (linkStyle))
* @see getState
* @see setState
*/
onStateChanged: Event<(sender: VisualizerBase, options: any) => any, VisualizerBase, any>;
protected stateChanged(name: string, value: any): void;
protected toolbarItemCreators: ToolbarItemCreators;
onGetToolbarItemCreators: () => ToolbarItemCreators;
protected getToolbarItemCreators(): ToolbarItemCreators;
constructor(question: Question, data: Array<{
[index: string]: any;
}> | GetDataFn, options?: {
[index: string]: any;
}, _type?: string);
protected get questionOptions(): any;
protected onDataChanged(): void;
/**
* Returns the identifier of a visualized question.
*/
get name(): string;
get dataNames(): Array<string>;
get dataPath(): string;
/**
* Indicates whether the visualizer displays a header. This property is `true` when a visualized question has a correct answer.
* @see hasFooter
*/
get hasHeader(): boolean;
/**
* Indicates whether the visualizer displays a footer. This property is `true` when a visualized question has a comment.
* @see hasHeader
*/
get hasFooter(): boolean;
protected createVisualizer<T = VisualizerBase>(question: Question, options?: {
[index: string]: any;
}, data?: any[]): T;
/**
* Allows you to access the footer visualizer. Returns `undefined` if the footer is absent.
* @see hasFooter
*/
get footerVisualizer(): VisualizerBase;
/**
* Indicates whether users can select series points to cross-filter charts. To allow or disallow selection, set the [`allowSelection`](https://surveyjs.io/dashboard/documentation/api-reference/ivisualizationpaneloptions#allowSelection) property of the `IVisualizationPanelOptions` object in the [`VisualizationPanel`](https://surveyjs.io/dashboard/documentation/api-reference/visualizationpanel) constructor.
*/
get supportSelection(): boolean;
getSeriesValues(): Array<string>;
getSeriesLabels(): Array<string>;
getValues(): Array<any>;
getLabels(): Array<string>;
/**
* Registers a function used to create a toolbar item for this visualizer.
*
* The following code shows how to add a custom button and drop-down menu to the toolbar:
*
* ```js
* import { VisualizationPanel, DocumentHelper } from "survey-analytics";
*
* const vizPanel = new VisualizationPanel( ... );
*
* // Add a custom button to the toolbar
* vizPanel.visualizers[0].registerToolbarItem("my-toolbar-button", () => {
* return DocumentHelper.createButton(
* // A button click event handler
* () => {
* alert("Custom toolbar button is clicked");
* },
* // Button caption
* "Button"
* );
* });
*
* // Add a custom drop-down menu to the toolbar
* vizPanel.visualizers[0].registerToolbarItem("my-toolbar-dropdown", () => {
* return DocumentHelper.createSelector(
* // Menu items
* [
* { value: 1, text: "One" },
* { value: 2, text: "Two" },
* { value: 3, text: "Three" }
* ],
* // A function that specifies initial selection
* (option) => false,
* // An event handler that is executed when selection is changed
* (e) => {
* alert(e.target.value);
* }
* );
* });
* ```
* @param name A custom name for the toolbar item.
* @param creator A function that accepts the toolbar and should return an `HTMLElement` with the toolbar item.
* @see unregisterToolbarItem
*/
registerToolbarItem(name: string, creator: (toolbar?: HTMLDivElement) => HTMLElement, order?: number): void;
/**
*
* Unregisters a function used to create a toolbar item. Allows you to remove a toolbar item.
* @param name A toolbar item name.
* @returns A function previously used to [register](#registerToolbarItem) the removed toolbar item.
* @see registerToolbarItem
*/
unregisterToolbarItem(name: string): (toolbar?: HTMLDivElement) => HTMLElement;
/**
* Returns the visualizer's title.
*/
get title(): string;
protected getTitle(question: Question): string;
/**
* Returns the visualizer's type.
*/
get type(): string;
/**
* @deprecated Use [`surveyData`](https://surveyjs.io/dashboard/documentation/api-reference/visualizationpanel#surveyData) instead.
*/
protected get data(): any[];
/**
* Returns an array of survey results used to calculate values for visualization. If a user applies a filter, the array is also filtered.
*
* To get an array of calculated and visualized values, call the [`getCalculatedValues()`](https://surveyjs.io/dashboard/documentation/api-reference/visualizerbase#getCalculatedValues) method.
*/
protected get surveyData(): any[];
protected get dataProvider(): DataProvider;
/**
* Updates visualized data.
* @param data A data array with survey results to be visualized.
*/
updateData(data: Array<{
[index: string]: any;
}> | GetDataFn): void;
onUpdate: () => void;
invokeOnUpdate(): void;
/**
* Deletes the visualizer and all its elements from the DOM.
* @see clear
*/
destroy(): void;
/**
* Empties the toolbar, header, footer, and content containers.
*
* If you want to empty and delete the visualizer and all its elements from the DOM, call the [`destroy()`](https://surveyjs.io/dashboard/documentation/api-reference/visualizerbase#destroy) method instead.
*/
clear(): void;
protected createToolbarItems(toolbar: HTMLDivElement): void;
protected getCorrectAnswerText(): string;
protected destroyToolbar(container: HTMLElement): void;
protected renderToolbar(container: HTMLElement): void;
protected destroyHeader(container: HTMLElement): void;
protected destroyContent(container: HTMLElement): void;
protected renderHeader(container: HTMLElement): void;
protected renderContentAsync(container: HTMLElement): Promise<HTMLElement>;
protected ensureQuestionIsReady(): Promise<void>;
protected renderContent(container: HTMLElement): void;
protected destroyFooter(container: HTMLElement): void;
get isFooterCollapsed(): boolean;
set isFooterCollapsed(newVal: boolean);
protected renderFooter(container: HTMLElement): void;
/**
* Renders the visualizer in a specified container.
* @param targetElement An `HTMLElement` or an `id` of a page element in which you want to render the visualizer.
*/
render(targetElement: HTMLElement | string): void;
updateToolbar(): void;
protected isSupportSoftUpdateContent(): boolean;
protected softUpdateContent(): void;
protected hardUpdateContent(): void;
updateContent(): void;
/**
* Re-renders the visualizer and its content.
*/
refresh(): void;
protected processText(text: string): string;
getRandomColor(): any;
private _backgroundColor;
get backgroundColor(): string;
set backgroundColor(value: string);
protected getBackgroundColorCore(): string;
protected setBackgroundColorCore(color: string): void;
static customColors: string[];
private static colors;
getColors(count?: number): any;
/**
* Gets or sets the visibility of the visualizer's toolbar.
*
* Default value: `true`
*/
get showToolbar(): boolean;
set showToolbar(newValue: boolean);
/**
* @deprecated Use [`getCalculatedValues()`](https://surveyjs.io/dashboard/documentation/api-reference/visualizationpanel#getCalculatedValues) instead.
*/
getData(): any;
private _calculationsCache;
protected getCalculatedValuesCore(): Array<any>;
protected loadingData: boolean;
renderLoadingIndicator(contentContainer: HTMLElement): void;
convertFromExternalData(externalCalculatedData: any): any[];
/**
* Returns an array of calculated and visualized values. If a user applies a filter, the array is also filtered.
*
* To get an array of source survey results, use the [`surveyData`](https://surveyjs.io/dashboard/documentation/api-reference/visualizerbase#surveyData) property.
*/
getCalculatedValues(): Promise<Array<Object>>;
protected _settingState: boolean;
/**
* Returns an object with properties that describe a current visualizer state. The properties are different for each individual visualizer.
*
* > This method is overriden in classes descendant from `VisualizerBase`.
* @see setState
* @see resetState
* @see onStateChanged
*/
getState(): any;
/**
* Sets the visualizer's state.
*
* [View Demo](https://surveyjs.io/dashboard/examples/save-dashboard-state-to-local-storage/ (linkStyle))
*
* > This method is overriden in classes descendant from `VisualizerBase`.
* @see getState
* @see resetState
* @see onStateChanged
*/
setState(state: any): void;
/**
* Resets the visualizer's state.
*
* > This method is overriden in classes descendant from `VisualizerBase`.
* @see getState
* @see setState
* @see onStateChanged
*/
resetState(): void;
/**
* Gets or sets the current locale.
*
* If you want to inherit the locale from a visualized survey, assign a [`SurveyModel`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model) instance to the [`survey`](https://surveyjs.io/dashboard/documentation/api-reference/ivisualizationpaneloptions#survey) property of the `IVisualizationPanelOptions` object in the [`VisualizationPanel`](https://surveyjs.io/dashboard/documentation/api-reference/visualizationpanel) constructor.
*
* If the survey is [translated into more than one language](https://surveyjs.io/form-library/examples/survey-localization/), the toolbar displays a language selection drop-down menu.
*
* [View Demo](https://surveyjs.io/dashboard/examples/localize-survey-data-dashboard-ui/ (linkStyle))
* @see onLocaleChanged
*/
get locale(): string;
set locale(newLocale: string);
protected setLocale(newLocale: string): void;
}
export {};