From 69dc7da844672249a86b9b0584a0e5932f5da9b8 Mon Sep 17 00:00:00 2001 From: RomanTsukanov <RomanTsukanov@users.noreply.github.com> Date: Fri, 30 Jun 2023 15:19:24 +0400 Subject: [PATCH] Update triggers, actions, and Service-related API descriptions (#6453) * Update triggers, actions, and Service-related API descriptions * Revert some changes * Update src/survey-events-api.ts Co-authored-by: annnke <anna.bakulina@devexpress.com> --------- Co-authored-by: annnke <anna.bakulina@devexpress.com> --- src/survey-events-api.ts | 30 ++++++++---- src/survey.ts | 98 ++++++++++++++++++++++------------------ 2 files changed, 76 insertions(+), 52 deletions(-) diff --git a/src/survey-events-api.ts b/src/survey-events-api.ts index f1d94b29ea..c35070e524 100644 --- a/src/survey-events-api.ts +++ b/src/survey-events-api.ts @@ -439,32 +439,46 @@ export interface TextRenderAsEvent extends TextProcessingEvent { export interface SendResultEvent { /** - * a response from the service + * A server [response](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/response). */ response: any; request: any; /** - * it is `true` if the results has been sent to the service successfully + * A Boolean value that indicates whether survey results have been saved successfully. */ success: boolean; } export interface GetResultEvent { /** - * the server response + * A server [response](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/response). */ response: any; /** - * an array of objects `{name, value}`, where `name` is a unique value/answer to the question and `value` is a number/count of such answers + * A Boolean value that indicates whether survey results have been retrieved successfully. */ - dataList: Array<any>; + success: boolean; /** - * the object `{AnswersCount, QuestionResult : {} }`. `AnswersCount` is the number of posted survey results. `QuestionResult` is an object with all possible unique answers to the question and number of these answers + * An object with the following structure: + * + * ```js + * { + * AnswersCount: Number, // A total number of posted answers to the question + * QuestionResult: Object // All unique answers to the question and their number + * } + * ``` */ data: any; /** - * it is `true` if the results were got from the service successfully + * An array of objects with the following structure: + * + * ```js + * { + * name: String, // A unique answer to the question + * value: Number // The number of user responses with this answer + * } + * ``` */ - success: boolean; + dataList: Array<any>; } export interface LoadFilesEvent extends FileQuestionEventMixin { diff --git a/src/survey.ts b/src/survey.ts index a752795c8b..ca570d1131 100644 --- a/src/survey.ts +++ b/src/survey.ts @@ -121,11 +121,11 @@ export class SurveyModel extends SurveyElementCore //#region Event declarations /** - * An event that is raised after a trigger is executed. + * An event that is raised after a [trigger](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#triggers) is executed. * * For information on event handler parameters, refer to descriptions within the interface. * - * For more information about triggers, refer to the following help topic: [Conditional Survey Logic (Triggers)](https://surveyjs.io/form-library/documentation/design-survey/conditional-logic#conditional-survey-logic-triggers). + * [Conditional Survey Logic (Triggers)](https://surveyjs.io/form-library/documentation/design-survey/conditional-logic#conditional-survey-logic-triggers (linkStyle)). * @see triggers * @see runTriggers */ @@ -170,11 +170,11 @@ export class SurveyModel extends SurveyElementCore */ public onStarted: EventBase<SurveyModel, {}> = this.addEvent<SurveyModel, {}>(); /** - * Use this event to save incomplete survey results. Enable the [`sendResultOnPageNext`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#sendResultOnPageNext) property for this event to occur. + * An event that is raised to save incomplete survey results. Enable the [`sendResultOnPageNext`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#sendResultOnPageNext) property for this event to occur. * * For information on event handler parameters, refer to descriptions within the interface. * - * Refer to the following help topic for more information on the use case: [Continue an Incomplete Survey](https://surveyjs.io/form-library/documentation/handle-survey-results-continue-incomplete). + * [Continue an Incomplete Survey](https://surveyjs.io/form-library/documentation/handle-survey-results-continue-incomplete (linkStyle)). */ public onPartialSend: EventBase<SurveyModel, {}> = this.addEvent<SurveyModel, {}>(); /** @@ -400,11 +400,11 @@ export class SurveyModel extends SurveyElementCore */ public onTextRenderAs: EventBase<SurveyModel, TextRenderAsEvent> = this.addEvent<SurveyModel, TextRenderAsEvent>(); /** - * The event fires when it gets response from the [api.surveyjs.io](https://api.surveyjs.io) service on saving survey results. Use it to find out if the results have been saved successfully. + * An event that is raised after a request to save survey results on [SurveyJS Service](https://api.surveyjs.io/) has been completed. Use this event to find out if the results have been saved successfully. */ public onSendResult: EventBase<SurveyModel, SendResultEvent> = this.addEvent<SurveyModel, SendResultEvent>(); /** - * Use it to get results after calling the `getResult` method. It returns a simple analytics from [api.surveyjs.io](https://api.surveyjs.io) service. + * An event that is raised when the [`getResult(resultId, questionName)`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#getResult) method is called. Use this event to obtain answers to an individual question from [SurveyJS Service](https://api.surveyjs.io/). * @see getResult */ public onGetResult: EventBase<SurveyModel, GetResultEvent> = this.addEvent<SurveyModel, GetResultEvent>(); @@ -728,27 +728,25 @@ export class SurveyModel extends SurveyElementCore public onLocaleChangedEvent: EventBase<SurveyModel, {}> = this.addEvent<SurveyModel, {}>(); /** - * Use this event to create/customize actions to be displayed in a question's title. + * An event that allows you to add, delete, or modify actions in a question title. * * For information on event handler parameters, refer to descriptions within the interface. * * [View Demo](https://surveyjs.io/form-library/examples/survey-titleactions/ (linkStyle)) - * @see IAction - * @see Question */ public onGetQuestionTitleActions: EventBase<SurveyModel, GetQuestionTitleActionsEvent> = this.addEvent<SurveyModel, GetQuestionTitleActionsEvent>(); /** - * Use this event to create/customize actions to be displayed in a panel's title. - * @see IAction - * @see PanelModel + * An event that allows you to add, delete, or modify actions in a panel title. */ public onGetPanelTitleActions: EventBase<SurveyModel, GetPanelTitleActionsEvent> = this.addEvent<SurveyModel, GetPanelTitleActionsEvent>(); /** - * Use this event to create/customize actions to be displayed in a page's title. - * @see IAction - * @see PageModel + * An event that allows you to add, delete, or modify actions in a page title. + * + * For information on event handler parameters, refer to descriptions within the interface. + * + * [View Demo](https://surveyjs.io/form-library/examples/modify-titles-of-survey-elements/ (linkStyle)) */ public onGetPageTitleActions: EventBase<SurveyModel, GetPageTitleActionsEvent> = this.addEvent<SurveyModel, GetPageTitleActionsEvent>(); @@ -1147,8 +1145,11 @@ export class SurveyModel extends SurveyElementCore } } /** - * Gets or sets a list of triggers in the survey. - * @see SurveyTrigger + * A list of triggers in the survey. + * + * [Conditional Survey Logic (Triggers)](https://surveyjs.io/form-library/documentation/design-survey/conditional-logic#conditional-survey-logic-triggers (linkStyle)) + * @see runTriggers + * @see onTriggerExecuted */ public get triggers(): Array<SurveyTrigger> { return this.getPropertyValue("triggers"); @@ -1166,7 +1167,7 @@ export class SurveyModel extends SurveyElementCore this.setPropertyValue("calculatedValues", val); } /** - * The identifier of a survey JSON schema to load from the [SurveyJS Service](https://api.surveyjs.io). + * The identifier of a survey JSON schema to load from [SurveyJS Service](https://api.surveyjs.io). * * Refer to the following help topic for more information: [Store Survey Results in the SurveyJS Service](https://surveyjs.io/form-library/documentation/handle-survey-results-store#store-survey-results-in-the-surveyjs-service). * @see loadSurveyFromService @@ -1179,7 +1180,7 @@ export class SurveyModel extends SurveyElementCore this.setPropertyValue("surveyId", val); } /** - * An identifier used to save survey results to the [SurveyJS Service](https://api.surveyjs.io). + * An identifier used to save survey results to [SurveyJS Service](https://api.surveyjs.io). * * Refer to the following help topic for more information: [Store Survey Results in the SurveyJS Service](https://surveyjs.io/form-library/documentation/handle-survey-results-store#store-survey-results-in-the-surveyjs-service). * @see onComplete @@ -1194,7 +1195,7 @@ export class SurveyModel extends SurveyElementCore /** * A user identifier (e-mail or other unique ID). * - * If your application works with the [SurveyJS Service](https://api.surveyjs.io), the ID ensures that users do not pass the same survey twice. On the second run, they will see the [Completed Before page](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#completedBeforeHtml). + * If your application works with [SurveyJS Service](https://api.surveyjs.io), the ID ensures that users do not pass the same survey twice. On the second run, they will see the [Completed Before page](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#completedBeforeHtml). * @see cookieName */ public get clientId(): string { @@ -1216,9 +1217,9 @@ export class SurveyModel extends SurveyElementCore this.setPropertyValue("cookieName", val); } /** - * Specifies whether to save survey results when respondents swtich between pages. Handle the [`onPartialSend`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onPartialSend) event to implement the save operation. + * Specifies whether to save survey results when respondents switch between pages. Handle the [`onPartialSend`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onPartialSend) event to implement the save operation. * - * Refer to the following help topic for more information on the use case: [Continue an Incomplete Survey](https://surveyjs.io/form-library/documentation/handle-survey-results-continue-incomplete). + * [Continue an Incomplete Survey](https://surveyjs.io/form-library/documentation/handle-survey-results-continue-incomplete (linkStyle)). */ public get sendResultOnPageNext(): boolean { return this.getPropertyValue("sendResultOnPageNext"); @@ -1660,8 +1661,13 @@ export class SurveyModel extends SurveyElementCore this.setPropertyValue("keepIncorrectValues", val); } /** - * Gets or sets the survey locale. The default value it is empty, this means the 'en' locale is used. - * You can set it to 'de' - German, 'fr' - French and so on. The library has built-in localization for several languages. The library has a multi-language support as well. + * Specifies the survey's locale. + * + * Default value: `""` (a default locale is used) + * + * [Localization & Globalization help topic](https://surveyjs.io/form-library/documentation/survey-localization (linkStyle)) + * + * [Survey Localization demo](https://surveyjs.io/form-library/examples/survey-localization/ (linkStyle)) */ public get locale(): string { return this.getPropertyValue("locale", surveyLocalization.currentLocale); @@ -1678,7 +1684,11 @@ export class SurveyModel extends SurveyElementCore this.onLocaleChangedEvent.fire(this, this.locale); } /** - * Returns an array of locales that are used in the survey's translation. + * Returns an array of locales whose translations are used in the survey. + * + * [Localization & Globalization help topic](https://surveyjs.io/form-library/documentation/survey-localization (linkStyle)) + * + * [Survey Localization demo](https://surveyjs.io/form-library/examples/survey-localization/ (linkStyle)) */ public getUsedLocales(): Array<string> { var locs = new Array<string>(); @@ -2067,7 +2077,10 @@ export class SurveyModel extends SurveyElementCore return new ConditionRunner(expression).run(values, properties); } /** - * Run all triggers that performs on value changed and not on moving to the next page. + * Executes [all triggers](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#triggers), except ["complete"](https://surveyjs.io/form-library/documentation/design-survey/conditional-logic#complete). + * + * [Conditional Survey Logic (Triggers)](https://surveyjs.io/form-library/documentation/design-survey/conditional-logic#conditional-survey-logic-triggers (linkStyle)) + * @see onTriggerExecuted */ public runTriggers(): void { this.checkTriggers(this.getFilteredValues(), false); @@ -2108,7 +2121,7 @@ export class SurveyModel extends SurveyElementCore return this.getLocalizableString("completedBeforeHtml"); } /** - * HTML content displayed while a survey JSON schema is being loaded from the [SurveyJS Service](https://api.surveyjs.io). + * HTML content displayed while a survey JSON schema is being loaded from [SurveyJS Service](https://api.surveyjs.io). * @see surveyId * @see processedLoadingHtml */ @@ -4094,7 +4107,7 @@ export class SurveyModel extends SurveyElementCore * 1. Switches the survey [`state`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#state) to `"completed"`. * 1. Raises the [`onComplete`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onComplete) event. * 1. Navigates the user to a URL specified by the [`navigateToUrl`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#navigateToUrl) or [`navigateToUrlOnCondition`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#navigateToUrlOnCondition) property. - * 1. Calls the [`sendResult()`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#sendResult) method if Form Library works with the [SurveyJS Service](https://api.surveyjs.io/). + * 1. Calls the [`sendResult()`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#sendResult) method if Form Library works with [SurveyJS Service](https://api.surveyjs.io/). * * The `doComplete()` method completes the survey regardless of validation errors and the current page. If you need to ensure that survey results are valid and full, call the [`completeLastPage()`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#completeLastPage) method instead. * @@ -5437,20 +5450,18 @@ export class SurveyModel extends SurveyElementCore } } /** - * Sends a survey result to the [api.surveyjs.io](https://api.surveyjs.io) service. - * @param postId [api.surveyjs.io](https://api.surveyjs.io) service postId - * @param clientId Typically a customer e-mail or an identifier - * @param isPartialCompleted Set it to `true` if the survey is not completed yet and the results are intermediate - * @see surveyPostId - * @see clientId + * Posts a survey result to [SurveyJS Service](https://api.surveyjs.io/). + * @param postId An identifier used to save survey results. You can find it on the [My Surveys](https://surveyjs.io/service/mysurveys) page. If you do not specify this parameter, the survey uses the [`surveyPostId`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#surveyPostId) property value. + * @param clientId A respondent identifier (e-mail or other unique ID). This ID ensures that the respondent does not pass the same survey twice. + * @param isPartial Pass `true` to save partial survey results (see [Continue an Incomplete Survey](https://surveyjs.io/form-library/documentation/handle-survey-results-continue-incomplete)). */ public sendResult( postId: string = null, clientId: string = null, - isPartialCompleted: boolean = false + isPartial: boolean = false ) { if (!this.isEditMode) return; - if (isPartialCompleted && this.onPartialSend) { + if (isPartial && this.onPartialSend) { this.onPartialSend.fire(this, null); } @@ -5461,7 +5472,7 @@ export class SurveyModel extends SurveyElementCore if (clientId) { this.clientId = clientId; } - if (isPartialCompleted && !this.clientId) return; + if (isPartial && !this.clientId) return; var self = this; if (this.surveyShowDataSaving) { this.setCompletedState("saving", ""); @@ -5484,18 +5495,17 @@ export class SurveyModel extends SurveyElementCore }); }, this.clientId, - isPartialCompleted + isPartial ); } /** - * Calls the [api.surveyjs.io](https://api.surveyjs.io) service and, on callback, fires the `onGetResult` event with all answers that your users made for a question. - * @param resultId [api.surveyjs.io](https://api.surveyjs.io) service resultId - * @param name The question name - * @see onGetResult + * Requests [SurveyJS Service](https://api.surveyjs.io/) to retrieve all answers to a specified question. Handle the [`onGetResult`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onGetResult) event to access the answers. + * @param resultId A result ID that identifies the required survey. You can find it on the [My Surveys](https://surveyjs.io/service/mysurveys) page. + * @param questionName A question name. */ - public getResult(resultId: string, name: string) { + public getResult(resultId: string, questionName: string) { var self = this; - this.createSurveyService().getResult(resultId, name, function ( + this.createSurveyService().getResult(resultId, questionName, function ( success: boolean, data: any, dataList: any[],