From ee2779920eed26ad2d67e703c8d70d0409fc404a Mon Sep 17 00:00:00 2001 From: dmitrykurmanov Date: Tue, 20 Aug 2024 13:06:13 +0000 Subject: [PATCH] updated survey-analytics docs [azurepipelines skip] --- docs/get-started-angular.md | 2 +- docs/get-started-html-css-javascript.md | 352 ++++++++++++++++++ docs/get-started-react.md | 2 +- docs/get-started-vue.md | 2 +- docs/get-started.md | 2 +- docs/overview.md | 2 +- docs/set-up-table-view-angular.md | 2 +- docs/set-up-table-view-html-css-javascript.md | 277 ++++++++++++++ docs/set-up-table-view-react.md | 2 +- docs/set-up-table-view-vue.md | 2 +- docs/set-up-table-view.md | 2 +- docs/sidebar.json | 8 +- docs/uri.json | 2 + 13 files changed, 644 insertions(+), 13 deletions(-) create mode 100644 docs/get-started-html-css-javascript.md create mode 100644 docs/set-up-table-view-html-css-javascript.md diff --git a/docs/get-started-angular.md b/docs/get-started-angular.md index 000c3fc24..9b14ee9ea 100644 --- a/docs/get-started-angular.md +++ b/docs/get-started-angular.md @@ -15,7 +15,7 @@ This step-by-step tutorial will help you get started with SurveyJS Dashboard in As a result, you will create the following dashboard: - diff --git a/docs/get-started-html-css-javascript.md b/docs/get-started-html-css-javascript.md new file mode 100644 index 000000000..beffe6333 --- /dev/null +++ b/docs/get-started-html-css-javascript.md @@ -0,0 +1,352 @@ +--- +title: Add SurveyJS Dashboard to Your JavaScript Application | Step-by-Step Tutorial +description: Learn how to add SurveyJS Dashboard to your JavaScript application with this comprehensive step-by-step tutorial. Enhance your self-hosted surveying tool with powerful survey analytics capabilities. +--- + +# Add SurveyJS Dashboard to a JavaScript Application + +This step-by-step tutorial will help you get started with SurveyJS Dashboard in an application built with HTML, CSS, and JavaScript (without frontend frameworks). As a result, you will create a dashboard displayed below: + + + +[View Full Code on GitHub](https://github.com/surveyjs/code-examples/tree/main/get-started-analytics/html-css-js (linkStyle)) + +## Link Resources + +SurveyJS Dashboard depends on other JavaScript libraries. Reference them on your page in the following order: + +1. Survey Core +A platform-independent part of [SurveyJS Form Library](https://surveyjs.io/form-library/documentation/overview) that works with the survey model. SurveyJS Dashboard requires only this part, but if you also display the survey on the page, reference [the rest of the SurveyJS Form Library resources](/form-library/documentation/get-started-html-css-javascript#link-surveyjs-resources) as well. + +1. Plotly.js and Wordcloud +Wordcloud (optional) is used to visualize the Text, Multiple Text, and Comment question types. Plotly.js (required) is used to visualize the rest of the question types. + +1. SurveyJS Dashboard +A library that integrates Survey Core with Plotly.js and Wordcloud. + +The following code shows how to reference these libraries: + +```html + + + + + + + + + + + + + + + + + +``` + +## Load Survey Results + +You can access survey results as a JSON object within the `SurveyModel`'s `onComplete` event handler. Send the results to your server and store them with a specific survey ID. Refer to the [Handle Survey Completion](/form-library/documentation/get-started-html-css-javascript#handle-survey-completion) help topic for more information. + +To load the survey results, send the survey ID to your server and return an array of JSON objects: + +```js +const SURVEY_ID = 1; + +loadSurveyResults("https://your-web-service.com/" + SURVEY_ID) + .then((surveyResults) => { + // ... + // Configure and render the Visualization Panel here + // Refer to the help topics below + // ... + }); + +function loadSurveyResults (url) { + return new Promise((resolve, reject) => { + const request = new XMLHttpRequest(); + request.open('GET', url); + request.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded'); + request.onload = () => { + const response = request.response ? JSON.parse(request.response) : []; + resolve(response); + } + request.onerror = () => { + reject(request.statusText); + } + request.send(); + }); +} +``` + +For demonstration purposes, this tutorial uses predefined survey results. The following code shows a survey model and the structure of the survey results array: + +```js +const surveyJson = { + elements: [{ + name: "satisfaction-score", + title: "How would you describe your experience with our product?", + type: "radiogroup", + choices: [ + { value: 5, text: "Fully satisfying" }, + { value: 4, text: "Generally satisfying" }, + { value: 3, text: "Neutral" }, + { value: 2, text: "Rather unsatisfying" }, + { value: 1, text: "Not satisfying at all" } + ], + isRequired: true + }, { + name: "nps-score", + title: "On a scale of zero to ten, how likely are you to recommend our product to a friend or colleague?", + type: "rating", + rateMin: 0, + rateMax: 10, + }], + showQuestionNumbers: "off", + completedHtml: "Thank you for your feedback!", +}; + +const surveyResults = [{ + "satisfaction-score": 5, + "nps-score": 10 +}, { + "satisfaction-score": 5, + "nps-score": 9 +}, { + "satisfaction-score": 3, + "nps-score": 6 +}, { + "satisfaction-score": 3, + "nps-score": 6 +}, { + "satisfaction-score": 2, + "nps-score": 3 +}]; +``` + +## Configure the Visualization Panel + +Analytics charts are displayed in a Visualization Panel. Specify [its properties](/Documentation/Analytics?id=ivisualizationpaneloptions) in a configuration object. In this tutorial, the object enables the [`allowHideQuestions`](/Documentation/Analytics?id=ivisualizationpaneloptions#allowHideQuestions) property: + +```js +const vizPanelOptions = { + allowHideQuestions: false +} +``` + +Pass the configuration object, survey questions, and results to the `VisualizationPanel` constructor as shown in the code below to instantiate the Visualization Panel. Assign the produced instance to a constant that will be used later to render the component: + +```js +const surveyJson = { /* ... */ }; +const surveyResults = [ /* ... */ ]; +const vizPanelOptions = { /* ... */ }; + +const survey = new Survey.Model(surveyJson); + +const vizPanel = new SurveyAnalytics.VisualizationPanel( + survey.getAllQuestions(), + surveyResults, + vizPanelOptions +); +``` + +
+ View Full Code + +```html + + + + SurveyJS Dashboard + + + + + + + + + + + + + + + + + + + +``` + +```js +const surveyJson = { + elements: [{ + name: "satisfaction-score", + title: "How would you describe your experience with our product?", + type: "radiogroup", + choices: [ + { value: 5, text: "Fully satisfying" }, + { value: 4, text: "Generally satisfying" }, + { value: 3, text: "Neutral" }, + { value: 2, text: "Rather unsatisfying" }, + { value: 1, text: "Not satisfying at all" } + ], + isRequired: true + }, { + name: "nps-score", + title: "On a scale of zero to ten, how likely are you to recommend our product to a friend or colleague?", + type: "rating", + rateMin: 0, + rateMax: 10, + }], + showQuestionNumbers: "off", + completedHtml: "Thank you for your feedback!", +}; + +const survey = new Survey.Model(surveyJson); + +const surveyResults = [{ + "satisfaction-score": 5, + "nps-score": 10 +}, { + "satisfaction-score": 5, + "nps-score": 9 +}, { + "satisfaction-score": 3, + "nps-score": 6 +}, { + "satisfaction-score": 3, + "nps-score": 6 +}, { + "satisfaction-score": 2, + "nps-score": 3 +}]; + +const vizPanelOptions = { + allowHideQuestions: false +} + +const vizPanel = new SurveyAnalytics.VisualizationPanel( + survey.getAllQuestions(), + surveyResults, + vizPanelOptions +); +``` +
+ +## Render the Visualization Panel + +A Visualization Panel should be rendered in a page element. Add this element to the page markup: + +```html + +
+ +``` + +To render the Visualization Panel in the page element, call the `render(container)` method on the Visualization Panel instance you created in the previous step: + +```js +document.addEventListener("DOMContentLoaded", function() { + vizPanel.render(document.getElementById("surveyVizPanel")); +}); +``` + +
+ View Full Code + +```html + + + + SurveyJS Dashboard + + + + + + + + + + + + + + + + +
+ + +``` + +```js +const surveyJson = { + elements: [{ + name: "satisfaction-score", + title: "How would you describe your experience with our product?", + type: "radiogroup", + choices: [ + { value: 5, text: "Fully satisfying" }, + { value: 4, text: "Generally satisfying" }, + { value: 3, text: "Neutral" }, + { value: 2, text: "Rather unsatisfying" }, + { value: 1, text: "Not satisfying at all" } + ], + isRequired: true + }, { + name: "nps-score", + title: "On a scale of zero to ten, how likely are you to recommend our product to a friend or colleague?", + type: "rating", + rateMin: 0, + rateMax: 10, + }], + showQuestionNumbers: "off", + completedHtml: "Thank you for your feedback!", +}; + +const survey = new Survey.Model(surveyJson); + +const surveyResults = [{ + "satisfaction-score": 5, + "nps-score": 10 +}, { + "satisfaction-score": 5, + "nps-score": 9 +}, { + "satisfaction-score": 3, + "nps-score": 6 +}, { + "satisfaction-score": 3, + "nps-score": 6 +}, { + "satisfaction-score": 2, + "nps-score": 3 +}]; + +const vizPanelOptions = { + allowHideQuestions: false +} + +const vizPanel = new SurveyAnalytics.VisualizationPanel( + survey.getAllQuestions(), + surveyResults, + vizPanelOptions +); + +document.addEventListener("DOMContentLoaded", function() { + vizPanel.render(document.getElementById("surveyVizPanel")); +}); +``` +
+ +[View Full Code on GitHub](https://github.com/surveyjs/code-examples/tree/main/get-started-analytics/html-css-js (linkStyle)) + +## See Also + +[Dashboard Demo Examples](/dashboard/examples/ (linkStyle)) \ No newline at end of file diff --git a/docs/get-started-react.md b/docs/get-started-react.md index d5f5a4729..c1ffa99d6 100644 --- a/docs/get-started-react.md +++ b/docs/get-started-react.md @@ -15,7 +15,7 @@ This step-by-step tutorial will help you get started with SurveyJS Dashboard in As a result, you will create the following dashboard: - diff --git a/docs/get-started-vue.md b/docs/get-started-vue.md index c7f74c0fa..d4d4b2741 100644 --- a/docs/get-started-vue.md +++ b/docs/get-started-vue.md @@ -15,7 +15,7 @@ This step-by-step tutorial will help you get started with SurveyJS Dashboard in As a result, you will create the following dashboard: - diff --git a/docs/get-started.md b/docs/get-started.md index 91f9acef6..764ed8a64 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -10,4 +10,4 @@ Refer to one of the following tutorials to get started with SurveyJS Dashboard o - [Angular](/Documentation/Analytics?id=get-started-angular) - [Vue](/Documentation/Analytics?id=get-started-vue) - [React](/Documentation/Analytics?id=get-started-react) -- [Knockout / jQuery](/Documentation/Analytics?id=get-started-knockout-jquery) +- [HTML/CSS/JavaScript](/dashboard/documentation/get-started-html-css-javascript) diff --git a/docs/overview.md b/docs/overview.md index 8455c421a..fd151063a 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -29,7 +29,7 @@ SurveyJS Dashboard visualizes survey results and allows users to analyze them. - [Angular](/Documentation/Analytics?id=get-started-angular) - [Vue](/Documentation/Analytics?id=get-started-vue) - [React](/Documentation/Analytics?id=get-started-react) -- [Knockout / jQuery](/Documentation/Analytics?id=get-started-knockout-jquery) +- [HTML/CSS/JavaScript](/dashboard/documentation/get-started-html-css-javascript) We also include multiple [demo examples](/Examples/Analytics) that allow you to edit and copy code. diff --git a/docs/set-up-table-view-angular.md b/docs/set-up-table-view-angular.md index b3dc7bfdf..6b6aaa0b9 100644 --- a/docs/set-up-table-view-angular.md +++ b/docs/set-up-table-view-angular.md @@ -15,7 +15,7 @@ This step-by-step tutorial will help you set up a Table View for survey results As a result, you will create the following view: - diff --git a/docs/set-up-table-view-html-css-javascript.md b/docs/set-up-table-view-html-css-javascript.md new file mode 100644 index 000000000..73c347af1 --- /dev/null +++ b/docs/set-up-table-view-html-css-javascript.md @@ -0,0 +1,277 @@ +--- +title: Export Survey Results to PDF or Excel | Open-Source JS Form Builder +description: Convert your survey data to manageable table format for easy filtering and analysis. Save survey results as PDF or Excel files to visualize or share with others. View free demo for JavaScript with a step-by-step setup guide. +--- + +# Table View for Survey Results in a JavaScript Application + +This step-by-step tutorial will help you set up a Table View for survey results using SurveyJS Dashboard an application built with HTML, CSS, and JavaScript (without frontend frameworks). As a result, you will create the view displayed below: + + + +[View Full Code on GitHub](https://github.com/surveyjs/code-examples/tree/main/dashboard-table-view/html-css-js (linkStyle)) + +## Link Resources + +SurveyJS Dashboard depends on other JavaScript libraries. Reference them on your page in the following order: + +1. Survey Core +A platform-independent part of [SurveyJS Form Library](https://surveyjs.io/form-library/documentation/overview) that works with the survey model. SurveyJS Dashboard requires only this part, but if you also display the survey on the page, reference [the rest of the SurveyJS Form Library resources](/Documentation/Library?id=get-started--html-css-javascript#link-surveyjs-resources) as well. + +1. *(Optional)* jsPDF, jsPDF-AutoTable, and SheetJS +Third-party libraries that enable users to export survey results to a PDF or XLSX document. Export to CSV is supported out of the box. + +1. Tabulator +A third-party library that renders interactive tables. + +1. SurveyJS Dashboard plugin for Tabulator +A library that integrates Survey Core with Tabulator. + +The following code shows how to reference these libraries: + +```html + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +## Load Survey Results + +When a respondent completes a survey, a JSON object with their answers is passed to the `SurveyModel`'s [`onComplete`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onComplete) event handler. You should send this object to your server and store it with a specific survey ID (see [Handle Survey Completion](/form-library/documentation/get-started-html-css-javascript#handle-survey-completion)). A collection of such JSON objects is a data source for the Table View. This collection can be processed (sorted, filtered, paginated) on the server or on the client. + +### Server-Side Data Processing + +Server-side data processing enables the Table View to load survey results in small batches on demand and delegate sorting and filtering to the server. For this feature to work, the server must support these data operations. Refer to the following demo example on GitHub for information on how to configure the server and the client for this usage scenario: + +[SurveyJS Dashboard: Table View - Server-Side Data Processing Demo Example](https://github.com/surveyjs/surveyjs-dashboard-table-view-nodejs-mongodb (linkStyle)) + +> The Table View allows users to save survey results as CSV, PDF, and XLSX documents. With server-side data processing, these documents contain only currently loaded data records. To export full datasets, you need to generate the documents on the server. + +### Client-Side Data Processing + +When data is processed on the client, the Table View loads the entire dataset at startup and applies sorting and filtering in a user's browser. This demands faster web connection and higher computing power but works smoother with small datasets. + +To load survey results to the client, send the survey ID to your server and return an array of JSON objects with survey results: + +```js +const SURVEY_ID = 1; + +loadSurveyResults("https://your-web-service.com/" + SURVEY_ID) + .then((surveyResults) => { + // ... + // Configure and render the Table View here + // Refer to the help topics below + // ... + }); + +function loadSurveyResults (url) { + return new Promise((resolve, reject) => { + const request = new XMLHttpRequest(); + request.open('GET', url); + request.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded'); + request.onload = () => { + const response = request.response ? JSON.parse(request.response) : []; + resolve(response); + } + request.onerror = () => { + reject(request.statusText); + } + request.send(); + }); +} +``` + +For demonstration purposes, this tutorial uses auto-generated survey results. The following code shows a survey model and a function that generates the survey results array: + +```js +const surveyJson = { + elements: [{ + name: "satisfaction-score", + title: "How would you describe your experience with our product?", + type: "radiogroup", + choices: [ + { value: 5, text: "Fully satisfying" }, + { value: 4, text: "Generally satisfying" }, + { value: 3, text: "Neutral" }, + { value: 2, text: "Rather unsatisfying" }, + { value: 1, text: "Not satisfying at all" } + ], + isRequired: true + }, { + name: "nps-score", + title: "On a scale of zero to ten, how likely are you to recommend our product to a friend or colleague?", + type: "rating", + rateMin: 0, + rateMax: 10, + }], + showQuestionNumbers: "off", + completedHtml: "Thank you for your feedback!", +}; + +function randomIntFromInterval(min: number, max: number): number { + return Math.floor(Math.random() * (max - min + 1) + min); +} +function generateData() { + const data = []; + for (let index = 0; index < 100; index++) { + const satisfactionScore = randomIntFromInterval(1, 5); + const npsScore = satisfactionScore > 3 ? randomIntFromInterval(7, 10) : randomIntFromInterval(1, 6); + data.push({ + "satisfaction-score": satisfactionScore, + "nps-score": npsScore + }); + } + return data; +} +``` + +## Render the Table + +The Table View is rendered by the `Tabulator` component. Pass the survey model and results to its constructor to instantiate it. Assign the produced instance to a constant that will be used later to render the component: + +```js +const surveyJson = { /* ... */ }; +function generateData() { /* ... */ } + +const survey = new Survey.Model(surveyJson); + +const surveyDataTable = new SurveyAnalyticsTabulator.Tabulator( + survey, + generateData() +); +``` + +The Table View should be rendered in a page element. Add this element to the page markup: + +```html + +
+ +``` + +To render the Table View in the page element, call the `render(container)` method on the Tabulator instance you created previously: + +```js +document.addEventListener("DOMContentLoaded", function() { + surveyDataTable.render(document.getElementById("surveyDataTable")); +}); +``` + +
+ View Full Code + +```html + + + + Table View: SurveyJS Dashboard + + + + + + + + + + + + + + + + + + + + + +
+ + +``` + +```js +const surveyJson = { + elements: [{ + name: "satisfaction-score", + title: "How would you describe your experience with our product?", + type: "radiogroup", + choices: [ + { value: 5, text: "Fully satisfying" }, + { value: 4, text: "Generally satisfying" }, + { value: 3, text: "Neutral" }, + { value: 2, text: "Rather unsatisfying" }, + { value: 1, text: "Not satisfying at all" } + ], + isRequired: true + }, { + name: "nps-score", + title: "On a scale of zero to ten, how likely are you to recommend our product to a friend or colleague?", + type: "rating", + rateMin: 0, + rateMax: 10, + }], + showQuestionNumbers: "off", + completedHtml: "Thank you for your feedback!", +}; + +const survey = new Survey.Model(surveyJson); + +function randomIntFromInterval(min, max) { + return Math.floor(Math.random() * (max - min + 1) + min); +} +function generateData() { + const data = []; + for (let index = 0; index < 100; index++) { + const satisfactionScore = randomIntFromInterval(1, 5); + const npsScore = satisfactionScore > 3 ? randomIntFromInterval(7, 10) : randomIntFromInterval(1, 6); + data.push({ + "satisfaction-score": satisfactionScore, + "nps-score": npsScore + }); + } + return data; +} + +const surveyDataTable = new SurveyAnalyticsTabulator.Tabulator( + survey, + generateData() +); + +document.addEventListener("DOMContentLoaded", function() { + surveyDataTable.render(document.getElementById("surveyDataTable")); +}); +``` + +
+ +[View Full Code on GitHub](https://github.com/surveyjs/code-examples/tree/main/dashboard-table-view/html-css-js (linkStyle)) + +## See Also + +[Dashboard Demo Examples](/dashboard/examples/ (linkStyle)) \ No newline at end of file diff --git a/docs/set-up-table-view-react.md b/docs/set-up-table-view-react.md index 26b3f7da3..0b40fc8ff 100644 --- a/docs/set-up-table-view-react.md +++ b/docs/set-up-table-view-react.md @@ -15,7 +15,7 @@ This step-by-step tutorial will help you set up a Table View for survey results As a result, you will create the following view: - diff --git a/docs/set-up-table-view-vue.md b/docs/set-up-table-view-vue.md index 5915f86a2..ff9b2b772 100644 --- a/docs/set-up-table-view-vue.md +++ b/docs/set-up-table-view-vue.md @@ -15,7 +15,7 @@ This step-by-step tutorial will help you set up a Table View for survey results As a result, you will create the following view: - diff --git a/docs/set-up-table-view.md b/docs/set-up-table-view.md index a795ce70f..972ccf4c8 100644 --- a/docs/set-up-table-view.md +++ b/docs/set-up-table-view.md @@ -10,4 +10,4 @@ Refer to one of the following tutorials to set up Table View for SurveyJS Dashbo - [Angular](/dashboard/documentation/set-up-table-view/angular) - [Vue](/dashboard/documentation/set-up-table-view/vue) - [React](/dashboard/documentation/set-up-table-view/react) -- [Knockout / jQuery](/dashboard/documentation/set-up-table-view/knockout-jquery) +- [HTML/CSS/JavaScript](/dashboard/documentation/set-up-table-view/html-css-javascript) diff --git a/docs/sidebar.json b/docs/sidebar.json index 14ceb498a..1050c4ae2 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -21,8 +21,8 @@ "Title": "React" }, { - "Name": "get-started-knockout-jquery", - "Title": "Knockout / jQuery" + "Name": "get-started-html-css-javascript", + "Title": "HTML/CSS/JavaScript" } ] }, @@ -43,8 +43,8 @@ "Title": "React" }, { - "Name": "set-up-table-view-knockout-jquery", - "Title": "Knockout / jQuery" + "Name": "set-up-table-view-html-css-javascript", + "Title": "HTML/CSS/JavaScript" } ] }, diff --git a/docs/uri.json b/docs/uri.json index 0e837ac4c..bb86bf219 100644 --- a/docs/uri.json +++ b/docs/uri.json @@ -3,6 +3,8 @@ "set-up-table-view" ], "rename": { + "get-started-knockout-jquery": "get-started-html-css-javascript", + "set-up-table-view-knockout-jquery": "set-up-table-view-html-css-javascript" }, "classRename": { }