Describe settings.specialChoicesOrder (#7349)

surveyjs · Nov 14, 2023 · ca93a6a · ca93a6a
1 parent 6a87064
commit ca93a6a
Show file tree

Hide file tree

Showing 3 changed files with 27 additions and 0 deletions.
diff --git a/src/question.ts b/src/question.ts
@@ -1318,6 +1318,7 @@ export class Question extends SurveyElement<Question>
    * @see otherItem
    * @see otherErrorText
    * @see showCommentArea
+   * @see [settings.specialChoicesOrder](https://surveyjs.io/form-library/documentation/api-reference/settings#specialChoicesOrder)
    */
   public get showOtherItem(): boolean {
     return this.getPropertyValue("showOtherItem", false);

diff --git a/src/question_baseselect.ts b/src/question_baseselect.ts
@@ -184,6 +184,7 @@ export class QuestionSelectBase extends Question {
    * When users select the "None" item in multi-select questions, all other items become unselected.
    * @see noneItem
    * @see noneText
+   * @see [settings.specialChoicesOrder](https://surveyjs.io/form-library/documentation/api-reference/settings#specialChoicesOrder)
    */
   public get showNoneItem(): boolean {
     return this.getPropertyValue("showNoneItem");
@@ -641,6 +642,7 @@ export class QuestionSelectBase extends Question {
    *
    * [View Demo](https://surveyjs.io/form-library/examples/questiontype-dropdownrestfull/ (linkStyle))
    * @see choices
+   * @see [settings.specialChoicesOrder](https://surveyjs.io/form-library/documentation/api-reference/settings#specialChoicesOrder)
    */
   public get choicesByUrl(): ChoicesRestful {
     return this.getPropertyValue("choicesByUrl");
@@ -669,6 +671,7 @@ export class QuestionSelectBase extends Question {
    * If you need to specify only the `value` property, you can set the `choices` property to an array of primitive values, for example, `[ "item1", "item2", "item3" ]`. These values are both saved in survey results and used as display text.
    * @see choicesByUrl
    * @see choicesFromQuestion
+   * @see [settings.specialChoicesOrder](https://surveyjs.io/form-library/documentation/api-reference/settings#specialChoicesOrder)
    */
   public get choices(): Array<any> {
     return this.getPropertyValue("choices");
@@ -781,6 +784,7 @@ export class QuestionSelectBase extends Question {
    * - `"asc"`- Sorts choice items in ascending order.
    * - `"desc"`- Sorts choice items in ascending order.
    * - `"random"` - Displays choice items in random order.
+   * @see [settings.specialChoicesOrder](https://surveyjs.io/form-library/documentation/api-reference/settings#specialChoicesOrder)
    */
   public get choicesOrder(): string {
     return this.getPropertyValue("choicesOrder");
@@ -809,6 +813,7 @@ export class QuestionSelectBase extends Question {
    * Displays the "Select All", "None", and "Other" choices on individual rows.
    * @see showNoneItem
    * @see showOtherItem
+   * @see [settings.specialChoicesOrder](https://surveyjs.io/form-library/documentation/api-reference/settings#specialChoicesOrder)
    */
   @property() separateSpecialChoices: boolean;
   /**

diff --git a/src/settings.ts b/src/settings.ts
@@ -567,6 +567,27 @@ export var settings = {
    * Default value: `"none"`
    */
   noneItemValue: "none",
+  /**
+   * An object whose properties specify the order of the special choice items (None, Other, Select All) in select-based questions.
+   *
+   * Default value: `{ selectAllItem: [-1], noneItem: [1], otherItem: [2] }`
+   *
+   * Use this object to reorder special choices. Each property accepts an array of integer numbers. Negative numbers place a special choice item above regular choice items, positive numbers place it below them. For instance, the following code specify the following order of choices: None, Select All, regular choices, Other:
+   *
+   * ```js
+   * import { settings } from "survey-core";
+   *
+   * settings.specialChoicesOrder.noneItem = [-2];
+   * settings.specialChoicesOrder.selectAllItem = [-1];
+   * settings.specialChoicesOrder.otherItem = [1];
+   * ```
+   *
+   * If you want to duplicate a special choice item above and below other choices, add two numbers to the corresponding array:
+   *
+   * ```js
+   * settings.specialChoicesOrder.selectAllItem = [-1, 3] // Displays Select All above and below other choices
+   * ```
+   */
   specialChoicesOrder: {
     selectAllItem: [-1],
     noneItem: [1],