InputMask: add new MaskPlaceholder parameter (#5577)

* Introduce new MaskPlaceholder parameter * Release notes
Megabit · Jun 20, 2024 · 9359290 · 9359290
1 parent 1b85253
commit 9359290
Show file tree

Hide file tree

Showing 8 changed files with 54 additions and 11 deletions.
diff --git a/Documentation/Blazorise.Docs/Layouts/DocsLayout.razor b/Documentation/Blazorise.Docs/Layouts/DocsLayout.razor
@@ -116,7 +116,7 @@
                                     <BarDropdownItem To="docs/components/layout">Layout</BarDropdownItem>
                                     <BarDropdownItem To="docs/components/link">Link</BarDropdownItem>
                                     <BarDropdownItem To="docs/components/list-group">List Group</BarDropdownItem>
-                                    <BarDropdownItem To="docs/components/input-mask">Mask</BarDropdownItem>
+                                    <BarDropdownItem To="docs/components/input-mask">Input Mask</BarDropdownItem>
                                     <BarDropdownItem To="docs/components/memo">Memo Edit</BarDropdownItem>
                                     <BarDropdownItem To="docs/components/modal">Modal</BarDropdownItem>
                                     <BarDropdownItem To="docs/components/offcanvas" Flex="Flex.JustifyContent.Between">

diff --git a/Documentation/Blazorise.Docs/Models/Snippets.generated.cs b/Documentation/Blazorise.Docs/Models/Snippets.generated.cs
@@ -2744,6 +2744,8 @@ void OnProgressed( FileProgressedEventArgs e )
 
         public const string BasicInputMaskExample = @"<InputMask Mask=""99-9999999"" />";
 
+        public const string InputMaskPlaceholderExample = @"<InputMask Mask=""99-9999999"" MaskPlaceholder=""X"" Placeholder=""Please enter a valid ID"" />";
+
         public const string BasicJumbotronExample = @"<Jumbotron Background=""Background.Light"" Margin=""Margin.Is4.FromBottom"">
     <JumbotronTitle Size=""JumbotronTitleSize.Is4"">Hello, world!</JumbotronTitle>
     <JumbotronSubtitle>

diff --git a/...Blazorise.Docs/Pages/Docs/Components/InputMasks/Code/InputMaskPlaceholderExampleCode.html b/...Blazorise.Docs/Pages/Docs/Components/InputMasks/Code/InputMaskPlaceholderExampleCode.html
@@ -0,0 +1,5 @@
+<div class="blazorise-codeblock">
+<div class="html"><pre>
+<span class="htmlTagDelimiter">&lt;</span><span class="htmlElementName">InputMask</span> <span class="htmlAttributeName">Mask</span><span class="htmlOperator">=</span><span class="quot">&quot;</span><span class="htmlAttributeValue">99-9999999</span><span class="quot">&quot;</span> <span class="htmlAttributeName">MaskPlaceholder</span><span class="htmlOperator">=</span><span class="quot">&quot;</span><span class="htmlAttributeValue">X</span><span class="quot">&quot;</span> <span class="htmlAttributeName">Placeholder</span><span class="htmlOperator">=</span><span class="quot">&quot;</span><span class="htmlAttributeValue">Please enter a valid ID</span><span class="quot">&quot;</span> <span class="htmlTagDelimiter">/&gt;</span>
+</pre></div>
+</div>
diff --git a/...lazorise.Docs/Pages/Docs/Components/InputMasks/Examples/InputMaskPlaceholderExample.razor b/...lazorise.Docs/Pages/Docs/Components/InputMasks/Examples/InputMaskPlaceholderExample.razor
@@ -0,0 +1,3 @@
+@namespace Blazorise.Docs.Docs.Examples
+
+<InputMask Mask="99-9999999" MaskPlaceholder="X" Placeholder="Please enter a valid ID" />
diff --git a/Documentation/Blazorise.Docs/Pages/Docs/Components/InputMasks/InputMaskPage.razor b/Documentation/Blazorise.Docs/Pages/Docs/Components/InputMasks/InputMaskPage.razor
@@ -26,8 +26,12 @@
     </UnorderedListItem>
 </UnorderedList>
 
+<DocsPageSubtitle>
+    Examples
+</DocsPageSubtitle>
+
 <DocsPageSection>
-    <DocsPageSectionHeader Title="Basic Example">
+    <DocsPageSectionHeader Title="Basic Mask">
         To start you only need to define the <Code>Mask</Code> parameter.
     </DocsPageSectionHeader>
     <DocsPageSectionContent Outlined FullWidth>
@@ -36,12 +40,8 @@
     <DocsPageSectionSource Code="BasicInputMaskExample" />
 </DocsPageSection>
 
-<DocsPageSubtitle>
-    Default masking definitions
-</DocsPageSubtitle>
-
 <DocsPageSection>
-    <DocsPageSectionHeader Title="Alias Example">
+    <DocsPageSectionHeader Title="With Alias">
         Instead of masking an input element, it is also possible to use the inputmask for formatting given values.
     </DocsPageSectionHeader>
     <DocsPageSectionContent Outlined FullWidth>
@@ -50,6 +50,20 @@
     <DocsPageSectionSource Code="AliasInputMaskExample" />
 </DocsPageSection>
 
+<DocsPageSubtitle>
+    Other examples
+</DocsPageSubtitle>
+
+<DocsPageSection>
+    <DocsPageSectionHeader Title="With Placeholder">
+        You can control the placeholder that will be used for the mask. The <Code>Placeholder</Code> will be used when the mask is not defined. And the <Code>MaskPlaceholder</Code> will be used when the mask is defined for extra information to the user about the valid input format.
+    </DocsPageSectionHeader>
+    <DocsPageSectionContent Outlined FullWidth>
+        <InputMaskPlaceholderExample />
+    </DocsPageSectionContent>
+    <DocsPageSectionSource Code="InputMaskPlaceholderExample" />
+</DocsPageSection>
+
 <DocsPageSubtitle>
     API
 </DocsPageSubtitle>
@@ -65,6 +79,12 @@
     <DocsAttributesItem Name="ValueChanged" Type="@("EventCallback<string>")">
         Occurs after the value has changed.
     </DocsAttributesItem>
+    <DocsAttributesItem Name="Mask" Type="string" Default="null">
+        The mask to use for the input.
+    </DocsAttributesItem>
+    <DocsAttributesItem Name="MaskPlaceholder" Type="string" Default="null">
+        The placeholder that will be used for the mask.
+    </DocsAttributesItem>
     <DocsAttributesItem Name="Plaintext" Type="bool" Default="false">
         Remove the default form field styling and preserve the correct margin and padding.
     </DocsAttributesItem>

diff --git a/Documentation/Blazorise.Docs/Pages/News/2024-07-15-release-notes-160.razor b/Documentation/Blazorise.Docs/Pages/News/2024-07-15-release-notes-160.razor
@@ -107,6 +107,14 @@
     Added a new <Code>SetLoading</Code> so you're able to control the loading state of the DataGrid.
 </Paragraph>
 
+<Heading Size="HeadingSize.Is4">
+    New MaskPlaceholder on InputMask
+</Heading>
+
+<Paragraph>
+    Introduced a new <Code>MaskPlaceholder</Code> property on the <Code>InputMask</Code> component to provide additional information to the user about the valid input format. While the change is not groundbreaking, it is a small but important step towards improving the user experience.
+</Paragraph>
+
 <Heading Size="HeadingSize.Is4">
     Disable days of week in DatePicker
 </Heading>

diff --git a/Source/Blazorise/Components/InputMask/InputMask.razor.cs b/Source/Blazorise/Components/InputMask/InputMask.razor.cs
@@ -71,7 +71,7 @@ protected override async Task OnFirstAfterRenderAsync()
             Alias,
             InputFormat,
             OutputFormat,
-            Placeholder,
+            MaskPlaceholder,
             ShowMaskOnFocus,
             ShowMaskOnHover,
             NumericInput,
@@ -217,6 +217,11 @@ public Task NotifyCleared()
     /// </summary>
     [Parameter] public string Mask { get; set; }
 
+    /// <summary>
+    /// The placeholder that will be used for the mask.
+    /// </summary>
+    [Parameter] public string MaskPlaceholder { get; set; }
+
     /// <summary>
     /// Use a regular expression as a mask.
     /// </summary>

diff --git a/Source/Blazorise/wwwroot/inputMask.js b/Source/Blazorise/wwwroot/inputMask.js
@@ -26,7 +26,7 @@ export function initialize(dotnetAdapter, element, elementId, options) {
         } : {};
 
     const otherOptions = {
-        placeholder: options.placeholder || "_",
+        placeholder: options.maskPlaceholder || "_",
         showMaskOnFocus: options.showMaskOnFocus,
         showMaskOnHover: options.showMaskOnHover,
         numericInput: options.numericInput || false,
@@ -44,7 +44,7 @@ export function initialize(dotnetAdapter, element, elementId, options) {
         ? Object.assign({}, aliasOptions, eventOptions, otherOptions)
         : Object.assign({}, maskOptions, regexOptions, eventOptions, otherOptions);
 
-    var inputMask = new Inputmask(finalOptions);
+    let inputMask = new Inputmask(finalOptions);
 
     inputMask.mask(element);
 
@@ -59,7 +59,7 @@ export function initialize(dotnetAdapter, element, elementId, options) {
 }
 
 export function destroy(element, elementId) {
-    var instances = _instances || {};
+    let instances = _instances || {};
     delete instances[elementId];
 }