Skip to content

Commit

Permalink
Update triggers, actions, and Service-related API descriptions (#6453)
Browse files Browse the repository at this point in the history 
* 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>
  • Loading branch information
@RomanTsukanov @annnke
RomanTsukanov and annnke authored Jun 30, 2023
1 parent 71823fc commit 69dc7da
Show file tree
Hide file tree
Showing 2 changed files with 76 additions and 52 deletions.
30 changes: 22 additions & 8 deletions src/survey-events-api.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
98 changes: 54 additions & 44 deletions src/survey.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/
Expand Down Expand Up @@ -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, {}>();
/**
Expand Down Expand Up @@ -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>();
Expand Down Expand Up @@ -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>();

Expand Down Expand Up @@ -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");
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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 {
Expand All @@ -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");
Expand Down Expand Up @@ -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);
Expand All @@ -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>();
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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
*/
Expand Down Expand Up @@ -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.
*
Expand Down Expand Up @@ -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);
}

Expand All @@ -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", "");
Expand All @@ -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[],
Expand Down

0 comments on commit 69dc7da

Please sign in to comment.