Add isRequired to inputs

[andrewleader]

Release	Renderer status	Tasks status
1.3	🔄 .NET (#2410) 🔄 Android (#2411) 🔄 iOS (#2412) ✔️ TS (#2413) 🔄 UWP (#2414)	🔄 Shared (#2409) ✔️ Designer (#2526)

Solves requests

• Basic IsRequired validation on inputs Request: IsRequired validation on inputs #1936

Summary

Add a validation property on Input elements, which currently only has necessity (so you can mark it as required)

Schema

New property on Input elements.

Property	Type	Required	Description
validation	InputValidationOptions	false	Specifies the validation options for the input.

New InputValidationOptions type

Property	Type	Required	Description
necessity	InputValidationOptions	false	Specifies the necessity of the input (whether it's required or optional)
errorMessage	string	false	Specifies the text that will be displayed if validation failed. This is optional but strongly recommended. If not provided, there will be NO error message displayed (the field will simply be visually highlighted as invalid).

In the future, you can imagine we'll add regex to the options.

New InputValidationNecessity enum

Value	Description
optional	Default. The input is optional.
required	The input is required. Actions that require inputs will be blocked until valid input is provided.
requiredWithVisualCue	Same as required, except this adds a visual cue to indicate the field is required before the user has even interacted with the card.

New property on Action elements.

Property	Type	Required	Description
ignoreInputValidation	bool	false	Defaults to false. If this is set to true, any input validation will be ignored when the user clicks the button. Useful for cases where you have a "Save" button (that requires inputs) and a "View" button (that doesn't require inputs).

OPEN QUESTION: Should we also allow authors to provide custom text for the validation error? Maybe that's a vNext feature? Or maybe we do it now? It probably shouldn't be required for authors to provide that text though, there's something nice about not needing to provide that text.

Example

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "text": "Please confirm your username"
    },
    {
      "type": "Input.Text",
      "id": "username",
      "placeholder": "Username",
      "validation": {
        "necessity": "required",
        "errorMessage": "Username is required"
      }
    }
  ],
  "actions": [
    {
      "type": "Action.Submit",
      "title": "Confirm",
      "data": "action=confirm"
    },
    {
      "type": "Action.Submit",
      "title": "Cancel",
      "data": "action=cancel",
      "ignoreInputValidation": true
    }
  ]
}

Initial state

User clicks Confirm, we show validation errors (and trigger event to host telling host where it needs to scroll to, in case some of the invalid fields were off-screen)

User changes the input value, we remove the validation error. We'll re-validate upon button press again. So even if they type "a" and then delete it, the validation error should remain removed.

Note that we do NOT place the validation above the input, since it breaks the flow of the header text related to the input. And we can't place the validation above the header text, since inputs don't have a header property.

Other inputs

Host Config

No changes. We'll use the attention color for the error text.

Host APIs

Hosts need to have APIs similar to below (in the corresponding native style)

// Disable default drawing of errors since we'll draw our own
renderer.DisplayInputValidationErrors = false; // True by default

// Returns invalid inputs
List<Input> invalidInputs = renderedCard.ValidateInputs();

// Intercept action executing and show different input errors
override void onExecuteAction(Action action)
{
    List<AdaptiveInput> invalidInputs = action.validateInputs();

    foreach (var input in invalidInputs)
    {
        showPopup(input.domElement);
    }
}

// Listen to input value changes so can re-run input validation
override void onInputValueChanged(Input input)
{
    // Clear error popups on inputs that were fixed
}

Down-level impact

Medium. Authors need to expect that users running down-level can still submit the card with empty inputs (most concerning for new authors who might assume that required property works, existing authors should already have that logic).

Host burden

None. Hosts could choose to native style, but they don't have to.

Renderer Requirements

1. A renderer must respect the required inputs and not allow action execution until the required inputs are fulfilled.
2. A renderer must visually indicate required fields if necessity is set to requiredWithVisualCue
3. A renderer should display the validation errors as described in this spec.
4. If displaying validation errors, a renderer must use the text provided in the errorMessage. If none is specified, that's a parse error (since it's required).

Research on best practices

https://blog.prototypr.io/ux-best-practices-of-form-validation-ddb8a0df14fd

• Poor validation systems
  • Users dislike when they fill out the entire form and have to wait for clicking submit to understand what went wrong.
• Better strategies
  • Provide information just in time
    • Users find it comforting to be informed at the time they commit a mistake so they verify immediately before proceeding, builds confidence that they'll have a successful form completion
  • Select the most appropriate place for displaying errors
    • Errors should be contextually next to the input
  • Use plain and simple language
    • No 404 errors

https://designmodo.com/ux-form-validation/

• Show at the right time
  • The right time is right after the user has submitted the information - immediately inform the user about their correctness of their data
    • They actually did tests and found increased success rates
  • Twitter is an excellent example, has confirmations and is conversational and informs you immediately

https://uxplanet.org/designing-more-efficient-forms-assistance-and-validation-f26a5241199d

• Validate right after they finish typing, but avoid validating on each keystroke because in most cases you simply cannot validate until someone has finished typing their answer

https://medium.theuxblog.com/10-best-practices-for-designing-user-friendly-forms-fa0ba7c3e01f

• Validate erros as the user goes
• Mark fields as mandatory, it saves a click and inconvenience to the user, prevention is better than cure

https://uxmovement.com/forms/why-users-make-more-errors-with-instant-inline-validation/

• Claims users make MORE errors with instant inline validation
  • However its evidence is based off of two studies back in 2003 and 2007, so likely incorrect.

https://baymard.com/blog/inline-form-validation

• Live inline validation is the best, in 2012 only 13% of online stores had it, whereas in 2016 60% of online stores have it
• Pitfalls
  • Premature inline validation - Input marked invalid before they've finished typing, which reprimands the user for mistakes they haven't made
    • Don't say the email field is invalid immediately when the user clicks the field, they haven't even had a chance to type!
    • Appearance of an error message while typing disrupts many user's typing as they're stopped to read and interpret the error. Even worse, some users interpreted the message as if what they entered so far had errors and thus began looking for mistakes that weren't there.
    • To avoid: Validity of input should not be checked until user has had a chance to fully type a valid input.
      • Typically means checking either...
        • When user leaves the field (most input types)
        • When field reaches the intended input length (like credit card numbers or zip codes where length is known)
        • Can show immediate warnings for inputs that have invalid characters, like letters inputted into an input that only is supposed to accept numbers
      • But once an error has occurred, the error message must then live-update on a keystroke level. So you give the user an initial first chance for valid input, but then once it's invalid, fully live validate so that they can see the error disappear as they finish
• Benefits of live validation
  • Locating errors is easier, user is told immediately
  • Positive validation increases confidence. Positive validation remove cognitive load from users since they can confidently proceed to the next field, resting assured their input is valid, also provides sense of accomplishment and visual feedback
• Best examples...
  • Etsy
  • Crutchfield
  • B&H Photo

Auto-generated task status

• Shared
• Designer
• .NET
• Android
• iOS
• TS
• UWP

[mdtauk]

Didn't the XAML validation changes to the Text Input controls get pushed back to 19H1? Android by default support field validation, but I can't speak for iOS. Do the FluentWeb/Fabric fields support validation states for HTML renderers?

[andrewleader]

We would add validation UI ourselves for platforms that don't have any.

[andrewleader]

Author ability to specify "required" text, and it's mandatory so we don't have to localize

[andrewleader]

Approved, updated with changes from our proposal review for adding the validationFailedText property.

Note that in the proposal review, we discussed the ability to specify the validationFailedText higher up, and let it cascade down to all inputs, but we decided that for now we'll just leave it on individual inputs. If that request comes up in the future, we can always add it.

[vijaysaimutyala]

Thanks for the wonderful work team. I understand that asking for a release date is bad, but we're using adaptive cards heavily in one of our bots and input validation is one of the important features we're missing. Do we have any tentative date for the 1.2 release or is any beta url for 1.2 with Input validation that I can test ?

[andrewleader]

Thanks @vijaysaimutyala! We still don't have any release date to share, but we've almost implemented all the 1.2 features so we're nearing the end. However, we haven't implemented this feature yet, so there's currently nothing you can try out. But this is a high priority feature (and planned to be part of 1.2), so we'll be working on it soon!

By the way, this feature only allows you to mark a field as required. It does NOT provide support for validating a valid email address, phone number, etc... if you need those features, let us know (and those will be addressed in a separate feature). Thanks!

[vijaysaimutyala]

Glad to know this @andrewleader. Marking the field as required will have most of the job done. But client side verification of inputs like email address or Phone Number like you said would be great. I'll try and come up with what all inputs validations will be useful. Thanks.

[dclaux]

As I implement the feature, I would like to suggest a couple changes to the spec:

• validationFailedText: this is a property of the validation object. Its name therefore doesn't need to start with "validation", just the same as "necessity" wasn't named "validationNecessity". I think we should rename this property into failureMessage
• I don't think we should require the failureMessage property. I think a built-in default failure message would be enough in case the property is omitted.
• I think we need to allow hosts to retrieve the list of inputs that fail validation:
  • Introduce a new Action.validateInputs(): Input[] method. The method would return a collection of all inputs that have failed validation
  • Introduce a new onInputValidationFailed(action: Action) event. This event would trigger instead of onExecuteAction when at least one of the inputs fails validation

[dclaux]

One more thing:

• I think ignoreInputValidation should be a property of Action.Submit (and Action.Http) only, not a property of the base Action type.

[andrewleader]

Good points, I agree with renaming to failureMessage or failedText or errorText (definitely should get rid of the leading "validation").

For the built-in default failure message, our concern is that it means we have to provide localized text for the default failure message. Additionally, we believe that in most cases, developers use custom strings anyways (but that's just a guess, we don't have evidence backing it up). Our main concern would be the localized text.

For hosts retrieving failed input validations, what would be the purpose of this? What's the use case? I'm sure you have one, but we need to know it before it makes sense to add those APIs :)

Agreed about ignoreInputValidation only being on actions that submit data from the inputs (like Submit/Http).

I can start a conversation with the whole team about these points Monday, but some more clarity around why you think we should have the two middle features will help!

[dclaux]

@andrewleader I know about that localization concern given I am part of that collective "we" you reference and helped shape this spec. As I implement it though, I do believe requiring the failure message is overkill. Maybe our default should be to not show an error message if not specified; this eliminates the localization issue.

As for the method/event:

• The method needs to exist anyway in some form; it would be how the renderer decides to trigger the onExecuteAction event or not. We might as well make that method public.
• But the actual use case is those hosts that have constrained height cards; there is not space to display the error messages in the card itself within messing up with the overall layout. Such hosts will want to display error messages their own way, say in a popup for instance.

[dclaux]

I suggest we use errorMessage (which is somewhat standard) instead of validationFailedText. That's what I will implement now, and I can always change it if necessary.

[andrewleader]

After consideration, we're making the following updates to the spec...

• Renaming validationFailedText to errorMessage (because "validation" is redundant since it's already inside a validation object, and error message sounds more accurate).
• Changing validationFailedText/errorMessage property from required to optional. We will NOT provide a default error message, so we still recommend developers provide an error message, but don't require it.

[vijaysaimutyala]

@andrewleader Did this make to the 1.2 release. We're able to access the necessity function in the official adaptivecards.io designer and it does not seem to work. Also I could find something here(#3066)

[andrewleader]

That issue #3066 is correct. isRequired isn't part of 1.2 and we're working on updating the designer so it doesn't have the necessity field.

[vijaysaimutyala]

Thanks @andrewleader. I hate to ask this but, do we have any timeline for the input validation to be available generally ?

[andrewleader]

Input validation is expected to be in 1.3, and it's right near the top of our list this time, so it almost certainly should make it. We've been shipping Adaptive Cards in ~6 month cadences, and then there's integration time for partner hosts to integrate the new version of Adaptive Cards into their apps, so maybe in about ~8-9 months input validation should be generally available in MS Teams (but no guarantees).

[andrewleader]

Being tracked with #3081 in combination with more advanced validation support

[kiranupadhyak]

In the future, you can imagine we'll add regex to the options.

@andrewleader Any updates on this?