Describe Variables vs Calculated values + How to add user ID to surve…

…y results (fix #8020) (#8060)

docs/customize-question-types-third-party-component-integration-vue.md

@@ -70,7 +70,7 @@ export class QuestionColorPickerModel extends Question {
   get colorPickerType(): string {
     return this.getPropertyValue("colorPickerType");
   }
-  set colorPickerType(val): string {
+  set colorPickerType(val) {
     this.setPropertyValue("colorPickerType", val);
   }
   get isSlider(): boolean {
@@ -86,7 +86,7 @@ export class QuestionColorPickerModel extends Question {
   get disableAlpha(): boolean {
     return this.getPropertyValue("disableAlpha");
   }
-  set disableAlpha(val): boolean {
+  set disableAlpha(val) {
     this.setPropertyValue("disableAlpha", val);
   }
 }

docs/design-survey-conditional-logic.md

@@ -181,6 +181,39 @@ const surveyJson = {
 
 [View Demo](https://surveyjs.io/Examples/Library?id=survey-calculatedvalues (linkStyle))
 
+### Variables vs Question Values
+
+Variables and question values are both used to perform custom calculations within a survey. However, they also have a number of important differences. The following table compares variables with question values across multiple criteria:
+
+| Criteria | Variables | Calculated values |
+|--------- | --------- | ----------------- |
+| Configuration | Configured using JavaScript code | Configured using an expression in the survey JSON schema |
+| Evaluation / Re-evaluation | Evaluated only once—when set | Evaluated when the survey model is instantiated and re-evaluated each time dynamic values within the expression are changed |
+| Inclusion in survey results | Aren't saved in survey results, but can be (see below) | Saved in survey results if the `includeIntoResult` property is enabled |
+
+If you need to save a variable in survey results, create an intermediary calculated value that references the variable. Enable the calculated value's `includeIntoResult` property to save the value in survey results. The following code shows how to save a `currentyear-var` variable value in survey results via a `currentyear` calculated value:
+
+```js
+import { Model } from "survey-core";
+
+const surveyJson = {
+  "elements": [{
+    "name": "footer",
+    "type": "html",
+    "html": "© 2015-{currentyear} Devsoft Baltic OÜ"
+  }],
+  "calculatedValues": [{
+    "name": "currentyear",
+    "expression": "{currentyear-var}",
+    "includeIntoResult": true
+  }]
+};
+
+const survey = new Model(surveyJson);
+
+survey.setVariable("currentyear-var", new Date().getFullYear());
+```
+
 ## Expressions
 
 Expressions allow you to add logic to your survey and perform calculations right in the survey JSON schema. Expressions are evaluated and re-evaluated at runtime.

docs/get-started-angular.md

@@ -255,7 +255,7 @@ export class AppModule { }
 
 ## Handle Form Completion
 
-After a respondent completes a survey, the results are available within the [onComplete](https://surveyjs.io/Documentation/Library?id=surveymodel#onComplete) event handler. In real-world applications, you should send the results to a server where they will be stored in a database and processed:
+After a respondent completes a survey, the results are available within the [`onComplete`](https://surveyjs.io/Documentation/Library?id=surveymodel#onComplete) event handler. In real-world applications, you should send the results to a server where they will be stored in a database and processed. If your application has a user identification system, you can add the user ID to the survey results before sending them to the server:
 
 ```js
 import { Component, OnInit } from '@angular/core';
@@ -267,10 +267,13 @@ const SURVEY_ID = 1;
   // ...
 })
 export class AppComponent implements OnInit {
-  surveyComplete (sender) {
+  surveyComplete (survey) {
+    const userId = /* ... Getting the user ID ... */
+    survey.setValue("userId", userId);
+
     saveSurveyResults(
       "https://your-web-service.com/" + SURVEY_ID,
-      sender.data
+      survey.data
     )
   }
   ngOnInit() {    

docs/get-started-jquery.md

@@ -181,15 +181,18 @@ $(function() {
 
 ## Handle Survey Completion
 
-After a respondent completes a survey, the results are available within the [onComplete](https://surveyjs.io/Documentation/Library?id=surveymodel#onComplete) event handler. In real-world applications, you should send the results to a server where they will be stored in a database and processed:
+After a respondent completes a survey, the results are available within the [`onComplete`](https://surveyjs.io/Documentation/Library?id=surveymodel#onComplete) event handler. In real-world applications, you should send the results to a server where they will be stored in a database and processed. If your application has a user identification system, you can add the user ID to the survey results before sending them to the server:
 
 ```js
 const SURVEY_ID = 1;
 
-function surveyComplete (sender) {
+function surveyComplete (survey) {
+    const userId = /* ... Getting the user ID ... */
+    survey.setValue("userId", userId);
+
     saveSurveyResults(
         "https://your-web-service.com/" + SURVEY_ID,
-        sender.data
+        survey.data
     )
 }
 

docs/get-started-knockout.md

@@ -190,15 +190,18 @@ document.addEventListener("DOMContentLoaded", function() {
 
 ## Handle Survey Completion
 
-After a respondent completes a survey, the results are available within the [onComplete](https://surveyjs.io/Documentation/Library?id=surveymodel#onComplete) event handler. In real-world applications, you should send the results to a server where they will be stored in a database and processed:
+After a respondent completes a survey, the results are available within the [`onComplete`](https://surveyjs.io/Documentation/Library?id=surveymodel#onComplete) event handler. In real-world applications, you should send the results to a server where they will be stored in a database and processed. If your application has a user identification system, you can add the user ID to the survey results before sending them to the server:
 
 ```js
 const SURVEY_ID = 1;
 
-function surveyComplete (sender) {
+function surveyComplete (survey) {
+    const userId = /* ... Getting the user ID ... */
+    survey.setValue("userId", userId);
+
     saveSurveyResults(
         "https://your-web-service.com/" + SURVEY_ID,
-        sender.data
+        survey.data
     )
 }
 

docs/get-started-react.md

@@ -177,7 +177,7 @@ export default App;
 
 ## Handle Form Completion
 
-After a respondent submits a form, the results are available within the [onComplete](https://surveyjs.io/Documentation/Library?id=surveymodel#onComplete) event handler. In real-world applications, you should send the results to a server where they will be stored in a database and processed:
+After a respondent submits a form, the results are available within the [`onComplete`](https://surveyjs.io/Documentation/Library?id=surveymodel#onComplete) event handler. In real-world applications, you should send the results to a server where they will be stored in a database and processed. If your application has a user identification system, you can add the user ID to the survey results before sending them to the server:
 
 ```js
 import { useCallback } from 'react';
@@ -186,10 +186,13 @@ const SURVEY_ID = 1;
 
 function App() {
   const survey = new Model(surveyJson);
-  const surveyComplete = useCallback((sender) => {
+  const surveyComplete = useCallback((survey) => {
+    const userId = /* ... Getting the user ID ... */
+    survey.setValue("userId", userId);
+
     saveSurveyResults(
       "https://your-web-service.com/" + SURVEY_ID,
-      sender.data
+      survey.data
     )
   }, []);
 

docs/get-started-vue.md

@@ -183,7 +183,7 @@ const survey = new Model(surveyJson);
 
 ### Handle Form Completion
 
-After a respondent completes a survey, the results are available within the [onComplete](https://surveyjs.io/Documentation/Library?id=surveymodel#onComplete) event handler. In real-world applications, you should send the results to a server where they will be stored in a database and processed:
+After a respondent completes a survey, the results are available within the [`onComplete`](https://surveyjs.io/Documentation/Library?id=surveymodel#onComplete) event handler. In real-world applications, you should send the results to a server where they will be stored in a database and processed. If your application has a user identification system, you can add the user ID to the survey results before sending them to the server:
 
 ```html
 <script setup lang="ts">
@@ -193,32 +193,35 @@ const SURVEY_ID = 1;
 const survey = new Model(surveyJson);
 survey.onComplete.add(surveyComplete);
 
-const surveyComplete = (sender: any) => {
+const surveyComplete = (survey: any) => {
+  const userId = /* ... Getting the user ID ... */
+  survey.setValue("userId", userId);
+
   saveSurveyResults(
     "https://your-web-service.com/" + SURVEY_ID,
-    sender.data
+    survey.data
   )
 }
 
-// function saveSurveyResults(url: string | URL, json: object) {
-//   fetch(url, {
-//     method: 'POST',
-//     headers: {
-//       'Content-Type': 'application/json;charset=UTF-8'
-//     },
-//     body: JSON.stringify(json)
-//   })
-//   .then(response => {
-//     if (response.ok) {
-//       // Handle success
-//     } else {
-//       // Handle error
-//     }
-//   })
-//   .catch(error => {
-//     // Handle error
-//   });
-// }
+function saveSurveyResults(url: string | URL, json: object) {
+  fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json;charset=UTF-8'
+    },
+    body: JSON.stringify(json)
+  })
+  .then(response => {
+    if (response.ok) {
+      // Handle success
+    } else {
+      // Handle error
+    }
+  })
+  .catch(error => {
+    // Handle error
+  });
+}
 </script>
 
 <template>
@@ -482,7 +485,7 @@ export default {
 
 ### Handle Form Completion
 
-After a respondent completes a survey, the results are available within the [onComplete](https://surveyjs.io/Documentation/Library?id=surveymodel#onComplete) event handler. In real-world applications, you should send the results to a server where they will be stored in a database and processed:
+After a respondent completes a survey, the results are available within the [`onComplete`](https://surveyjs.io/Documentation/Library?id=surveymodel#onComplete) event handler. In real-world applications, you should send the results to a server where they will be stored in a database and processed. If your application has a user identification system, you can add the user ID to the survey results before sending them to the server:
 
 ```html
 <template>
@@ -504,10 +507,13 @@ export default {
     }
   },
   methods: {
-    surveyComplete (sender) {
+    surveyComplete (survey) {
+      const userId = /* ... Getting the user ID ... */
+      survey.setValue("userId", userId);
+
       saveSurveyResults(
         "https://your-web-service.com/" + SURVEY_ID,
-        sender.data
+        survey.data
       )
     }
   },