From 1edd3ab2c6eb3e5ce793c6876c9b288d4c30c4b1 Mon Sep 17 00:00:00 2001 From: RomanTsukanov Date: Wed, 13 Mar 2024 18:50:20 +0400 Subject: [PATCH 1/2] Describe the Masks API --- docs/sidebar.json | 18 ++++++++++++- src/mask/mask_base.ts | 5 ++++ src/mask/mask_currency.ts | 26 +++++++++++++++++++ src/mask/mask_datetime.ts | 27 +++++++++++++++++++- src/mask/mask_numeric.ts | 54 +++++++++++++++++++++++++++++++++++++++ src/mask/mask_pattern.ts | 43 +++++++++++++++++++++++++++++++ src/question_text.ts | 24 +++++++++++++++++ src/settings.ts | 16 +++++++++++- src/survey.ts | 2 +- 9 files changed, 211 insertions(+), 4 deletions(-) diff --git a/docs/sidebar.json b/docs/sidebar.json index 4428d1e960..539b878b36 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -134,7 +134,7 @@ }, { "Name": "api", - "Title": "API", + "Title": "Form Library API", "Items": [ { "Name": "surveymodel", @@ -256,6 +256,22 @@ "Name": "ICustomQuestionTypeConfiguration", "Title": "ICustomQuestionTypeConfiguration" }, + { + "Name": "inputmasknumeric", + "Title": "InputMaskNumeric" + }, + { + "Name": "inputmaskcurrency", + "Title": "InputMaskCurrency" + }, + { + "Name": "inputmaskdatetime", + "Title": "InputMaskDateTime" + }, + { + "Name": "inputmaskpattern", + "Title": "InputMaskPattern" + }, { "Name": "settings", "Title": "Global Settings" diff --git a/src/mask/mask_base.ts b/src/mask/mask_base.ts index 31cafa74f4..901fb60019 100644 --- a/src/mask/mask_base.ts +++ b/src/mask/mask_base.ts @@ -3,6 +3,11 @@ import { JsonObject, Serializer, property } from "../jsonobject"; import { IInputMask, IMaskedInputResult, ITextInputParams } from "./mask_utils"; export class InputMaskBase extends Base implements IInputMask { + /** + * Specifies whether to store the question value with an applied mask in survey results. + * + * Default value: `false` + */ @property() saveMaskedValue: boolean; public getType(): string { diff --git a/src/mask/mask_currency.ts b/src/mask/mask_currency.ts index c2f9082c3d..f765d7fbf2 100644 --- a/src/mask/mask_currency.ts +++ b/src/mask/mask_currency.ts @@ -2,8 +2,34 @@ import { Serializer, property } from "../jsonobject"; import { InputMaskNumeric } from "./mask_numeric"; import { IMaskedInputResult, ITextInputParams } from "./mask_utils"; +/** + * A class that describes an input mask of the `"currency"` [`maskType`](https://surveyjs.io/form-library/documentation/api-reference/text-entry-question-model#maskType). + * + * The following code shows how to specify the properties of this class within a survey JSON schema: + * + * ``` + * const surveyJson = { + * "elements": [{ + * "name": "textquestion1" + * "type": "text", + * "maskType": "currency", + * "maskSettings": { + * // Specify the properties of a currency input mask here + * } + * }] + * } + * ``` + */ export class InputMaskCurrency extends InputMaskNumeric { + /** + * One or several symbols to be displayed before the currency value. + * @see suffix + */ @property() prefix: string; + /** + * One or several symbols to be displayed after the currency value. + * @see prefix + */ @property() suffix: string; public getType(): string { diff --git a/src/mask/mask_datetime.ts b/src/mask/mask_datetime.ts index 2f7b9f649a..46a5d92e4d 100644 --- a/src/mask/mask_datetime.ts +++ b/src/mask/mask_datetime.ts @@ -101,12 +101,37 @@ export function getDateTimeLexems(pattern: string): Array { return result; } +/** + * A class that describes an input mask of the `"datetime"` [`maskType`](https://surveyjs.io/form-library/documentation/api-reference/text-entry-question-model#maskType). + * + * The following code shows how to specify the properties of this class within a survey JSON schema: + * + * ``` + * const surveyJson = { + * "elements": [{ + * "name": "textquestion1" + * "type": "text", + * "maskType": "datetime", + * "maskSettings": { + * // Specify the properties of a date-time input mask here + * } + * }] + * } + * ``` + */ export class InputMaskDateTime extends InputMaskPattern { private turnOfTheCentury = 68; private lexems: Array = []; private inputDateTimeData: Array = []; - + /** + * A minimum date and time value that respondents can enter. + * @see max + */ @property() min: string; + /** + * A maximum date and time value that respondents can enter. + * @see min + */ @property() max: string; public getType(): string { diff --git a/src/mask/mask_numeric.ts b/src/mask/mask_numeric.ts index a231293ab8..05e151dd2f 100644 --- a/src/mask/mask_numeric.ts +++ b/src/mask/mask_numeric.ts @@ -26,12 +26,66 @@ export function splitString(str: string, reverse = true, n = 3): Array { return arr; } +/** + * A class that describes an input mask of the `"numeric"` [`maskType`](https://surveyjs.io/form-library/documentation/api-reference/text-entry-question-model#maskType). + * + * The following code shows how to specify the properties of this class within a survey JSON schema: + * + * ``` + * const surveyJson = { + * "elements": [{ + * "name": "textquestion1" + * "type": "text", + * "maskType": "numeric", + * "maskSettings": { + * // Specify the properties of a numeric input mask here + * } + * }] + * } + * ``` + */ export class InputMaskNumeric extends InputMaskBase { + /** + * Specifies whether respondents can enter negative values. + * + * Default value: `true` + * @see min + * @see max + */ @property() allowNegativeValues: boolean; + /** + * A symbol used to separate the fractional part from the integer part of a displayed number. + * + * Default value: `"."` + * @see precision + * @see thousandsSeparator + */ @property() decimalSeparator: string; + /** + * Limits how many digits to retain after the decimal point for a displayed number. + * + * Default value: 2 + * @see decimalSeparator + */ @property() precision: number; + /** + * A symbol used to separate the digits of a large number into groups of three. + * + * Default value: `","` + * @see decimalSeparator + */ @property() thousandsSeparator: string; + /** + * A minimum value that respondents can enter. + * @see max + * @see allowNegativeValues + */ @property() min: number; + /** + * A maximum value that respondents can enter. + * @see min + * @see allowNegativeValues + */ @property() max: number; private calccaretPosition(leftPart: string, args: ITextInputParams, maskedValue: string) { diff --git a/src/mask/mask_pattern.ts b/src/mask/mask_pattern.ts index ec63f48afa..b1df48651c 100644 --- a/src/mask/mask_pattern.ts +++ b/src/mask/mask_pattern.ts @@ -98,9 +98,52 @@ export function getUnmaskedValueByPattern(str: string, pattern: string | Array = []; + /** + * A pattern for the input value. + * + * If you set the [`maskType`](https://surveyjs.io/form-library/documentation/api-reference/text-entry-question-model#maskType) to `"pattern"`, the mask can contain string literals and the following placeholders: + * + * - `9` - A digit. + * - `a` - An upper- or lower-case letter. + * - `#` - A digit or an upper- or lower-case letter. + * + * Use backslash `\` to escape a character. + * + * Example: `+1(999)-999-99-99` + * + * If you set the [`maskType`](https://surveyjs.io/form-library/documentation/api-reference/text-entry-question-model#maskType) to `"datetime"`, the mask can contain separator characters and the following placeholders: + * + * - `m` - Month number. + * - `mm` - Month number, with leading zero for single-digit values. + * - `d` - Day of the month. + * - `dd` - Day of the month, with leading zero for single-digit values. + * - `yy` - Last two digits of the year. + * - `yyyy` - A four-digit year. + * + * Example: `mm/dd/yyyy` + * @see [settings.maskSettings](https://surveyjs.io/form-library/documentation/api-reference/settings#maskSettings) + */ @property() pattern: string; protected updateLiterals(): void { diff --git a/src/question_text.ts b/src/question_text.ts index c1c86ba55a..a8661a9c49 100644 --- a/src/question_text.ts +++ b/src/question_text.ts @@ -45,6 +45,18 @@ export class QuestionTextModel extends QuestionTextBase { this.updateMaskAdapter(); } + /** + * Specifies the type of a mask applied to the input. + * + * Possible values: + * + * - `"none"` (default) + * - `"numeric"` + * - `"currency"` + * - `"datetime"` + * - `"pattern"` + * @see maskSettings + */ @property({ onSet: (newValue: string, target: QuestionTextModel) => { target.onSetMaskType(newValue); } }) maskType: string; @@ -53,6 +65,18 @@ export class QuestionTextModel extends QuestionTextBase { return this.maskType === "none"; } + /** + * An object with properties that configure the mask applied to the input. + * + * Available properties depend on the specified [`maskType`](https://surveyjs.io/form-library/documentation/api-reference/text-entry-question-model#maskType) and belong to corresponding classes. Refer to the class APIs for a full list of properties: + * + * | `maskType` | Class | + * | ---------- | ----- | + * | `"numeric"` | [`InputMaskNumeric`](https://surveyjs.io/form-library/documentation/api-reference/inputmasknumeric) | + * | `"currency"` | [`InputMaskCurrency`](https://surveyjs.io/form-library/documentation/api-reference/inputmaskcurrency) | + * | `"datetime"` | [``](https://surveyjs.io/form-library/documentation/api-reference/inputmaskdatetime) | + * | `"pattern"` | [`InputMaskPattern`](https://surveyjs.io/form-library/documentation/api-reference/inputmaskpattern) | + */ public get maskSettings(): InputMaskBase { return this.getPropertyValue("maskSettings"); } diff --git a/src/settings.ts b/src/settings.ts index b8f923ba9b..edc7f5822e 100644 --- a/src/settings.ts +++ b/src/settings.ts @@ -77,7 +77,7 @@ export var settings = { * Nested properties: * * - `useLocalTimeZone`: `boolean`\ - * Disable this property if you want internal SurveyJS functions to use methods that work with UTC date and time (`setUTCDate()` `setUTCHours()`, etc.) instead of methods that work with local date and time (`setYear`, `setHours()`, etc.). Default value: `true`. + * Disable this property if you want internal SurveyJS functions to use methods that work with UTC date and time (`setUTCDate()` `setUTCHours()`, etc.) instead of methods that work with local date and time (`setYear()`, `setHours()`, etc.). Default value: `true`. * * - `defaultLocaleName`: `string`\ * A property key that stores a translation for the default locale. Default value: `"default"`. @@ -730,6 +730,20 @@ export var settings = { ] }, legacyProgressBarView: false, + /** + * An object with properties that configure input masks. + * + * Nested properties: + * + * - `patternPlaceholderChar`: `string`\ + * A symbol used as a placeholder for characters to be entered in [pattern masks](https://surveyjs.io/form-library/documentation/api-reference/inputmaskpattern). Default value: `"_"`. + * + * - `patternEscapeChar`: `string`\ + * A symbol used to insert literal representations of special characters in [pattern masks](https://surveyjs.io/form-library/documentation/api-reference/inputmaskpattern). Default value: `"\\"`. + * + * - `patternDefinitions`: `<{ [key: string]: RegExp }>`\ + * An object that maps placeholder symbols to regular expressions in [pattern masks](https://surveyjs.io/form-library/documentation/api-reference/inputmaskpattern). Default value: `{ "9": /[0-9]/, "a": /[a-zA-Z]/, "#": /[a-zA-Z0-9]/ }`. + */ maskSettings: { patternPlaceholderChar: "_", patternEscapeChar: "\\", diff --git a/src/survey.ts b/src/survey.ts index c6c6e65870..9d01654aa7 100644 --- a/src/survey.ts +++ b/src/survey.ts @@ -2615,7 +2615,7 @@ export class SurveyModel extends SurveyElementCore * - `"belowHeader"` - Displays the progress bar below the survey header. * - `"bottom"` - Displays the progress bar below survey content. * - `"topBottom"` - Displays the progress bar above and below survey content. - * - `"auto"` - Automatically selects between `"aboveHeader"` and `"belowHeader"`. + * - `"auto"` - Displays the progress bar below the survey header if the header has a [background image](https://surveyjs.io/form-library/documentation/api-reference/iheader#backgroundImage) or color. Otherwise, the progress bar is displayed above the header. * - `"top"` - *(Obsolete)* Use the `"aboveHeader"` or `"belowHeader"` property value instead. * - `"both"` - *(Obsolete)* Use the `"topBottom"` property value instead. * From 1e6803abe5dc9f97d6fdd21d501220c990b5a4ec Mon Sep 17 00:00:00 2001 From: RomanTsukanov Date: Thu, 14 Mar 2024 12:56:03 +0400 Subject: [PATCH 2/2] Fix a typo --- src/question_text.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/question_text.ts b/src/question_text.ts index a8661a9c49..6d1b5f6ca4 100644 --- a/src/question_text.ts +++ b/src/question_text.ts @@ -74,7 +74,7 @@ export class QuestionTextModel extends QuestionTextBase { * | ---------- | ----- | * | `"numeric"` | [`InputMaskNumeric`](https://surveyjs.io/form-library/documentation/api-reference/inputmasknumeric) | * | `"currency"` | [`InputMaskCurrency`](https://surveyjs.io/form-library/documentation/api-reference/inputmaskcurrency) | - * | `"datetime"` | [``](https://surveyjs.io/form-library/documentation/api-reference/inputmaskdatetime) | + * | `"datetime"` | [`InputMaskDateTime`](https://surveyjs.io/form-library/documentation/api-reference/inputmaskdatetime) | * | `"pattern"` | [`InputMaskPattern`](https://surveyjs.io/form-library/documentation/api-reference/inputmaskpattern) | */ public get maskSettings(): InputMaskBase {