SurveyModel: Rename completeLastPage() to tryComplete() (#9218)

* SurveyModel: renamings
Fixes #9209

* Add fixes for the docs

---------

Co-authored-by: tsv2013 <[email protected]>
Co-authored-by: RomanTsukanov <[email protected]>

docs/design-survey-create-a-multi-page-survey.md

@@ -238,7 +238,7 @@ if (!navigatedBack) {
     alert("Navigation failed!")
 }
 
-const completedSuccessfully = survey.completeLastPage();
+const completedSuccessfully = survey.tryComplete();
 if (!completedSuccessfully) {
     alert("Check the answers for validation errors")
 }

packages/survey-core/src/survey.ts

@@ -424,7 +424,8 @@ export class SurveyModel extends SurveyElementCore
    */
   public onGetQuestionNumber: EventBase<SurveyModel, GetQuestionNumberEvent> = this.addEvent<SurveyModel, GetQuestionNumberEvent>();
   /**
-   * This event is obsolete. Use the [`onGetQuestionNumber`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onGetQuestionNumber) event instead.
+   * Obsolete. Use the [`onGetQuestionNumber`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onGetQuestionNumber) event instead.
+   * @deprecated
    */
   public onGetQuestionNo: EventBase<SurveyModel, GetQuestionNumberEvent> = this.onGetQuestionNumber;
   /**
@@ -664,7 +665,8 @@ export class SurveyModel extends SurveyElementCore
    */
   public onMatrixRowAdding: EventBase<SurveyModel, MatrixBeforeRowAddedEvent> = this.addEvent<SurveyModel, MatrixBeforeRowAddedEvent>();
   /**
-   * This event is obsolete. Use the [`onMatrixRowAdding`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onMatrixRowAdding) event instead.
+   * Obsolete. Use the [`onMatrixRowAdding`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onMatrixRowAdding) event instead.
+   * @deprecated
    */
   public onMatrixBeforeRowAdded: EventBase<SurveyModel, MatrixBeforeRowAddedEvent> = this.onMatrixRowAdding;
 
@@ -687,7 +689,8 @@ export class SurveyModel extends SurveyElementCore
    */
   public onMatrixRenderRemoveButton: EventBase<SurveyModel, MatrixAllowRemoveRowEvent> = this.addEvent<SurveyModel, MatrixAllowRemoveRowEvent>();
   /**
-   * This event is obsolete. Use the [`onMatrixRenderRemoveButton`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onMatrixRenderRemoveButton) event instead.
+   * Obsolete. Use the [`onMatrixRenderRemoveButton`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onMatrixRenderRemoveButton) event instead.
+   * @deprecated
    */
   public onMatrixAllowRemoveRow: EventBase<SurveyModel, MatrixAllowRemoveRowEvent> = this.onMatrixRenderRemoveButton;
   /**
@@ -712,7 +715,8 @@ export class SurveyModel extends SurveyElementCore
    */
   public onAfterRenderMatrixCell: EventBase<SurveyModel, MatrixAfterCellRenderEvent> = this.addEvent<SurveyModel, MatrixAfterCellRenderEvent>();
   /**
-   * This event is obsolete. Use the [`onAfterRenderMatrixCell`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onAfterRenderMatrixCell) event instead.
+   * Obsolete. Use the [`onAfterRenderMatrixCell`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#onAfterRenderMatrixCell) event instead.
+   * @deprecated
    */
   public onMatrixAfterCellRender: EventBase<SurveyModel, MatrixAfterCellRenderEvent> = this.onAfterRenderMatrixCell;
 
@@ -1252,7 +1256,8 @@ export class SurveyModel extends SurveyElementCore
   @property() containerCss: string;
   @property({ onSet: (newValue, target: SurveyModel) => { target.updateCss(); } }) fitToContainer: boolean;
   /**
-   * This property is obsolete. Use the [`headerView`](https://surveyjs.io/form-library/documentation/api-reference/itheme#headerView) property within a theme instead.
+   * Obsolete. Use the [`headerView`](https://surveyjs.io/form-library/documentation/api-reference/itheme#headerView) property within a theme instead.
+   * @deprecated
    */
   @property({
     onSet: (newValue, target: SurveyModel) => {
@@ -3854,7 +3859,8 @@ export class SurveyModel extends SurveyElementCore
     DomDocumentHelper.setCookie(this.cookieName + "=;");
   }
   /**
-   * This property is obsolete. Use the [`validationEnabled`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#validationEnabled) property instead.
+   * Obsolete. Use the [`validationEnabled`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#validationEnabled) property instead.
+   * @deprecated
    */
   public get ignoreValidation(): boolean { return !this.validationEnabled; }
   public set ignoreValidation(val: boolean) { this.validationEnabled = !val; }
@@ -4231,7 +4237,7 @@ export class SurveyModel extends SurveyElementCore
    * @see isCurrentPageValid
    * @see nextPage
    */
-  public completeLastPage(): boolean {
+  public tryComplete(): boolean {
     if (this.isValidateOnComplete) {
       this.cancelPreview();
     }
@@ -4241,6 +4247,13 @@ export class SurveyModel extends SurveyElementCore
     }
     return res;
   }
+  /**
+   * Obsolete. Use the [`tryComplete`](https://surveyjs.io/form-library/documentation/api-reference/survey-data-model#tryComplete) method instead.
+   * @deprecated
+   */
+  public completeLastPage(): boolean {
+    return this.tryComplete();
+  }
   private isNavigationButtonPressed: boolean = false;
   public navigationMouseDown(): boolean {
     this.isNavigationButtonPressed = true;
@@ -6445,7 +6458,7 @@ export class SurveyModel extends SurveyElementCore
         mouseDown: () => this.navigationMouseDown(),
       },
       locTitle: this.locCompleteText,
-      action: () => this.taskManager.waitAndExecute(() => this.completeLastPage()),
+      action: () => this.taskManager.waitAndExecute(() => this.tryComplete()),
       component: defaultComponent
     });
     this.updateNavigationItemCssCallback = () => {
@@ -6810,7 +6823,7 @@ export class SurveyModel extends SurveyElementCore
         if (this.isShowPreviewBeforeComplete) {
           this.showPreview();
         } else {
-          this.completeLastPage();
+          this.tryComplete();
         }
       }
     };
@@ -7615,13 +7628,13 @@ export class SurveyModel extends SurveyElementCore
     this.onTimerTick.fire(this, {});
     if (this.timeLimit > 0 && this.timeLimit <= this.timeSpent) {
       this.timeSpent = this.timeLimit;
-      this.completeLastPage();
+      this.tryComplete();
     }
     if (page) {
       var pageLimit = page.getMaxTimeToFinish();
       if (pageLimit > 0 && pageLimit == page.timeSpent) {
         if (this.isLastPage) {
-          this.completeLastPage();
+          this.tryComplete();
         } else {
           this.nextPage();
         }

packages/survey-core/tests/paneltests.ts

@@ -1827,7 +1827,7 @@ QUnit.test("Expand panel on error in multiple text question", function(assert) {
   });
   const panel = <PanelModel>survey.getPanelByName("panel");
   assert.equal(panel.state, "collapsed", "the panel is collapsed by default");
-  survey.completeLastPage();
+  survey.tryComplete();
   assert.equal(panel.state, "expanded", "the panel is expanded");
 });
 
@@ -2836,7 +2836,7 @@ QUnit.test("Check if errors disappered in the closest questions on changing the
   q2.value = 6;
   assert.equal(q1.errors.length, 0, "q1.errors #1");
   assert.equal(q2.errors.length, 0, "q2.errors #1");
-  assert.equal(survey.completeLastPage(), false, "Could not complete");
+  assert.equal(survey.tryComplete(), false, "Could not complete");
   assert.equal(q1.errors.length, 1, "q1.errors #2");
   assert.equal(q2.errors.length, 1, "q2.errors #2");
   q1.value = 1;

packages/survey-core/tests/question_baseselecttests.ts

@@ -1206,7 +1206,7 @@ QUnit.test("selectbase, showOtherItem & checkErrorsMode: 'onValueChanged'", (ass
   const q1 = <QuestionSelectBase>survey.getQuestionByName("q1");
   q1.renderedValue = "other";
   assert.equal(q1.errors.length, 0, "We do not have errors yet");
-  survey.completeLastPage();
+  survey.tryComplete();
   assert.equal(q1.errors.length, 1, "There is an error");
   assert.equal(survey.state, "running", "Still running");
 });

packages/survey-core/tests/question_customtests.ts

@@ -849,7 +849,7 @@ QUnit.test("Composite: remove invisible values", function (assert) {
   lastName.value = "last";
   assert.equal(lastName.value, "last", "value set correctly");
   firstName.value = "Jon";
-  survey.completeLastPage();
+  survey.tryComplete();
   assert.deepEqual(
     survey.data,
     { q1: { firstName: "Jon" } },
@@ -3079,7 +3079,7 @@ QUnit.test("Single: showPreviewBeforeComplete Bug#8005", function (assert) {
   survey.getQuestionByName("question1").value = 1;
   survey.showPreview();
   assert.deepEqual(survey.data, { question1: 1 }, "survey.data #2");
-  survey.completeLastPage();
+  survey.tryComplete();
   assert.deepEqual(survey.data, { question1: 1 }, "survey.data #2");
   ComponentCollection.Instance.clear();
 });

packages/survey-core/tests/question_matrix_tests.ts

@@ -369,7 +369,7 @@ QUnit.test("matrix isAllRowRequired  & getItemClass", function (assert) {
   let row = question.visibleRows[1];
   assert.equal(question.getItemClass(row, column1).indexOf(itemError) > -1, false, "itemError doesn't exist in column 1, #1");
   assert.equal(question.getItemClass(row, column2).indexOf(itemError) > -1, false, "itemError doesn't exist in column 2, #1");
-  survey.completeLastPage();
+  survey.tryComplete();
   assert.equal(survey.state, "running", "There is an error");
   row = question.visibleRows[1];
   assert.equal(question.getItemClass(row, column1).indexOf(itemError) > -1, true, "itemError exists in column 1, #2");

packages/survey-core/tests/question_matrixdynamictests.ts

@@ -5743,7 +5743,7 @@ QUnit.test(
       0,
       "There is no errors yet in the cell, second row, first column"
     );
-    survey.completeLastPage();
+    survey.tryComplete();
     assert.equal(
       rows[0].cells[1].question.errors.length,
       1,
@@ -9072,7 +9072,7 @@ QUnit.test("Errors: matrixdropdown", function (assert) {
   assert.equal(table.rows[0].cells[2].isErrorsCell, true);
   assert.strictEqual(table.rows[0].cells[2].question, table.rows[1].cells[2].question);
 
-  survey.completeLastPage();
+  survey.tryComplete();
   assert.equal(table.rows[0].visible, true);
   assert.equal(table.rows[2].visible, true);
   table.rows[1].cells[1].question.value = "Item1";
@@ -10310,7 +10310,7 @@ QUnit.test("Validation doesn't work if a user doensn't visit the page, Bug#8937"
     checkErrorsMode: "onComplete"
   });
   survey.currentPageNo = 2;
-  survey.completeLastPage();
+  survey.tryComplete();
   assert.equal(survey.state, "running", "Still running");
   assert.equal(survey.currentPageNo, 1, "move to page with panel");
   const matrix = <QuestionMatrixDynamicModel>survey.getQuestionByName("matrix");

packages/survey-core/tests/question_multipletexttests.ts

@@ -166,7 +166,7 @@ QUnit.test("Check error row visibility", (assert) => {
   });
   const question = <QuestionMultipleTextModel>survey.getAllQuestions()[0];
   assert.notOk(question.getRows()[0].isVisible);
-  survey.completeLastPage();
+  survey.tryComplete();
   assert.ok(question.getRows()[0].isVisible);
   question.items[0].editor.value = "test";
   assert.ok(question.getRows()[0].isVisible);

packages/survey-core/tests/question_paneldynamic_tests.ts

@@ -3484,7 +3484,7 @@ QUnit.test(
     assert.equal(q2.errors.length, 0, "and there is no error in the second question");
     q1.value = "";
     assert.equal(q1.errors.length, 1, "We have the error in q1 now");
-    survey.completeLastPage();
+    survey.tryComplete();
     assert.equal(q1.errors.length, 1, "There is error in the first question");
     assert.equal(q2.errors.length, 1, "There is error in the second question");
   }
@@ -5421,7 +5421,7 @@ QUnit.test("Two nested invisible dynamic panels do not clear itself correctly, B
   });
   const rootPanel = <QuestionPanelDynamicModel>survey.getQuestionByName("rootPanel");
   rootPanel.panels[0].getQuestionByName("q1").value = 2;
-  survey.completeLastPage();
+  survey.tryComplete();
   assert.deepEqual(survey.data, { "rootPanel": [{ "q1": 2 }] }, "There is no empty data for any nested panels");
 });
 
@@ -5499,7 +5499,7 @@ QUnit.test("Error in nested dynamic collapsed panel", (assert) => {
   const rootPanel = <QuestionPanelDynamicModel>survey.getQuestionByName("rootPanel");
   const childPanel = <QuestionPanelDynamicModel>rootPanel.panels[0].getQuestionByName("childPanel");
   assert.equal(childPanel.state, "collapsed", "child panel State is collapsed by default");
-  survey.completeLastPage();
+  survey.tryComplete();
   assert.equal(childPanel.state, "expanded", "child panel state is expanded now");
 });
 QUnit.test("Error in nested dynamic collapsed panel && renderMode - progressTop", (assert) => {
@@ -7641,7 +7641,7 @@ QUnit.test("Validation doesn't work if a user doensn't visit the page, Bug#8937"
     checkErrorsMode: "onComplete"
   });
   survey.currentPageNo = 2;
-  survey.completeLastPage();
+  survey.tryComplete();
   assert.equal(survey.state, "running", "Still running");
   assert.equal(survey.currentPageNo, 1, "move to page with panel");
   const panel = <QuestionPanelDynamicModel>survey.getQuestionByName("panel");

packages/survey-core/tests/question_texttests.ts

@@ -493,7 +493,7 @@ QUnit.test("inputType='date' invalid value, #8617", function(assert) {
   q1.onKeyUp(event);
   q1.value = undefined;
   assert.equal(q1.errors.length, 0, "errors #2");
-  survey.completeLastPage();
+  survey.tryComplete();
   assert.equal(q1.errors.length, 1, "errors #3");
   assert.equal(q1.errors[0].text, "Invalid date", "errors #4");
   assert.equal(survey.state, "running", "survey.state #1");

packages/survey-core/tests/surveyShowPreviewTests.ts

@@ -173,7 +173,7 @@ QUnit.test(
     survey.showPreviewBeforeComplete = "showAllQuestions";
     survey.currentPageNo = 1;
     survey.showPreview();
-    survey.completeLastPage();
+    survey.tryComplete();
     assert.equal(survey.visiblePages.length, 2, "We have two pages again");
     assert.equal(survey.currentPageNo, 1, "Current page is the last one");
   }
@@ -195,10 +195,10 @@ QUnit.test(
     survey.currentPageNo = 1;
     survey.showPreview();
     assert.equal(survey.state, "preview");
-    survey.completeLastPage();
+    survey.tryComplete();
     assert.equal(survey.state, "preview", "Keep showing preview");
     allowComplete = true;
-    survey.completeLastPage();
+    survey.tryComplete();
     assert.equal(survey.state, "completed");
   }
 );
@@ -756,10 +756,10 @@ QUnit.test("showPreviewBeforeComplete = 'showAnsweredQuestions' and all question
     assert.equal(survey.state, "preview", "We do not check for errors");
     survey.cancelPreview();
     assert.equal(survey.state, "running", "running again");
-    survey.completeLastPage();
+    survey.tryComplete();
     assert.equal(survey.state, "running", "We have errors, we can't fix errors");
     survey.setValue("q1", "a");
-    survey.completeLastPage();
+    survey.tryComplete();
     assert.equal(survey.state, "completed", "No errors");
   }
 );
@@ -775,10 +775,10 @@ QUnit.test("showPreviewBeforeComplete = 'showAnsweredQuestions' & checkErrorsMod
     });
     survey.nextPage();
     survey.showPreview();
-    survey.completeLastPage();
+    survey.tryComplete();
     assert.equal(survey.state, "running", "We have errors, we can't fix errors");
     survey.setValue("q1", "a");
-    survey.completeLastPage();
+    survey.tryComplete();
     assert.equal(survey.state, "completed", "No errors");
   }
 );

packages/survey-core/tests/surveyquestiontests.ts

@@ -7000,7 +7000,7 @@ QUnit.test("survey.onMultipleTextItemAdded", function (assert) {
   const q2 = survey.getQuestionByName("q2");
   q1.value = "yes";
   assert.equal(q2.isRequired, true, "q2 is required");
-  survey.completeLastPage();
+  survey.tryComplete();
   assert.equal(q2.errors.length, 1, "One error is shown");
   q1.value = "no";
   assert.equal(q2.isRequired, false, "q2 is not required");