diff --git a/docs/DataPortals/05.Control-Details/Percent.md b/docs/DataPortals/05.Control-Details/Percent.md new file mode 100644 index 0000000..463dfbf --- /dev/null +++ b/docs/DataPortals/05.Control-Details/Percent.md @@ -0,0 +1,61 @@ +--- +title: Composable Docs +summary: Technical Documentation for the Composable DataOps Platform +authors: + - Composable Analytics, Inc. +date: 2014-08-12 +some_url: https://docs.composable.ai +--- + +# Percent + +## Overview + +The **Percent** control supports entering a number as a percentage while still storing the number internally as it's mathematical value. For example: + +- Enter 50 to represent 50% (stored as 0.5 in the DataPortal) +- Enter 72.6 to represent 72.6% (stored as 0.726 in the DataPortal) + +After entering a number it is then displayed formatted using Intl.NumberFormat. + +![Post-Populated Field](../img/Percent_3.PNG) + +## Required Fields + +- **Name**: The name of the field saved to the database. See [here](../06.Setting-Details/Name.md) for details and restrictions. + +- **Type**: Can be any of the following types: + - `System.Double` + - `System.Single` + - `System.Decimal` + +- **ControlType**: Must be set to `Percent`. + + +## Optional Fields + +- [**FormattingLocale**](../06.Setting-Details/FormattingLocale.md): The "locale" describing what cultural norms to use when formatting the number. If not provided or blank, defaults to United States English (`en-us`). +- [**FormattingOptions**](../06.Setting-Details/FormattingOptions.md): Options describing what formatting to apply to the number. The style property will be overwritten if provided and be set to percent. +- [**Min**](../06.Setting-Details/Min.md): This defines the minimum possible numeric input into the Percent field. All input values below will display an error box to the user. +- [**Max**](../06.Setting-Details/Max.md): This defines the maximum possible numeric input into the Percent field. All input values above will display an error box to the user. +- [**DefaultValue**](../06.Setting-Details/DefaultValue.md): This defines the default value that is displayed to the user and stored in number representation on the database upon initialization. + +**Note:** Min, Max, and DefaultValue should be the numeric representation of the number. For example for a max of 50%, Max should be set ot 0.5. + +# User Experience +The user experience for Percent consists of three stages. 1) Pre-populated fields, 2) fields during numeric inputting, 3) post-populated field. + +### Pre-Populated Fields +Prior to populating the Percent field, the input display is set to a default display formatted value of the locale and options applied to a value of 0, as seen in the figure below. Please note that there has been no value representation set on the database at this stage. + +![Pre-Populated Field](../img/Percent_1.PNG) + +### Field During Numeric Inputting +While the user is inputting a value into the Percent field, the field will display the un-formatted number in the same scale as a percentage. This display format will remain until the user clicks away and the field enters the post-population stage. + +![Field During Numeric Inputting](../img/Percent_2.PNG) + +### Post-Population Fields +Once the numerical input has been made, and the user has clicked away from the field, the Percent field will display the formatted value of the input value. This value will only be displayed on the front-end, while the numeric value of the percent will be the value represented on the server (in this example 0.5). + +![Post-Populated Field](../img/Percent_3.PNG) diff --git a/docs/DataPortals/img/Percent_1.png b/docs/DataPortals/img/Percent_1.png new file mode 100644 index 0000000..6e4c8bd Binary files /dev/null and b/docs/DataPortals/img/Percent_1.png differ diff --git a/docs/DataPortals/img/Percent_2.png b/docs/DataPortals/img/Percent_2.png new file mode 100644 index 0000000..bac5333 Binary files /dev/null and b/docs/DataPortals/img/Percent_2.png differ diff --git a/docs/DataPortals/img/Percent_3.png b/docs/DataPortals/img/Percent_3.png new file mode 100644 index 0000000..2042529 Binary files /dev/null and b/docs/DataPortals/img/Percent_3.png differ diff --git a/docs/home-data/update-data.json b/docs/home-data/update-data.json index f09d93a..922f19e 100644 --- a/docs/home-data/update-data.json +++ b/docs/home-data/update-data.json @@ -1,5 +1,11 @@ { "updates": [ + { + "content": "Added control type for Percents to DataPortals", + "date": "1/8/2026", + "type": "major", + "changesetNum": "22614" + }, { "content": "Fixed an issue with templated keys in queryviews interfering with other inputs", "date": "1/5/2026", @@ -18,7 +24,9 @@ { "content": "Account operations history on User Management page", "date": "12/15/2025", - "productAreas": ["Admin"], + "productAreas": [ + "Admin" + ], "type": "minor", "changesetNum": "22598" }, @@ -1062,4 +1070,4 @@ "changesetNum": "19584" } ] -} +} \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index a4c1562..4a67547 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -77,6 +77,7 @@ nav: - 'Link': 'DataPortals/05.Control-Details/Link.md' - 'NumberFormatting': 'DataPortals/05.Control-Details/NumberFormatting.md' - 'Page': 'DataPortals/05.Control-Details/Page.md' + - 'Percent': 'DataPortals/05.Control-Details/Percent.md' - 'Phone': 'DataPortals/05.Control-Details/Phone.md' - 'Pill': 'DataPortals/05.Control-Details/Pill.md' - 'QueryView': 'DataPortals/05.Control-Details/QueryView.md'