Client-side form validation

[adamstep]

As explored in #305, there's a need to support client-side form validation in Hyperview. This doc will explore some approaches before we implement the feature.

What do we want to support?

• Validate on submit: User enters data in form and hits "Submit" button. Error messages appear on the invalid fields. As the user corrects the errors, the field error message disappear. When the user hits "Submit" again, the form is valid and the request is made.
• Validate on blur: User enters data in a field. As soon as they move to the next field, the previous field validates and shows an error message. As the user corrects the errors, the field error message disappears.
• Validate on change: As soon as the user starts entering data in the field, validation shows error messages.
• Disable form submit: The "Submit" button is disabled until all fields in the form are valid.
• Custom validators: Applications may want to customize how they validate data such as phone numbers, emails, etc.

What are we not supporting for now?

• Inter-field validation: Validation logic that depends on data across multiple fields can be done with server-side logic.
• Async validation: For example, validating that a username is already taken. I'm afraid this could complicate the design.

Design considerations

Declarative syntax

One of the design principles in Hyperview is that HXML should be completely declarative. The visual UI and behaviors should be defined as pure XML elements and attributes. Support for more sophisticated interactions is done by creating custom components and behaviors, which have the full power of arbitrary JS code.

Client-side validation should follow this same design principle. Validation logic should be expressed in pure HXML. Custom validation logic can be supported through an extension mechanism similar to behaviors.

Language agnostic

Another design principle in Hyperview is that the core library is as language agnostic as possible. Copy that appears in the app should be defined in the XML. For form validation, that means we don't want to hard-code the string "This field is required" anywhere in the app. This may make the syntax a little more verbose, but that's a similar tradeoff we make in other places as well.

However, do we want to pre-render all possible errors as hidden UI elements on the page, and toggle visibility? That doesn't seem very elegant. Perhaps we need a way to populate a single error UI element with the error message.

New namespace

We want to use XML namespaces for new features to avoid clashes when it comes to element names and attributes.

Prior Art

• Parsely is a web validation library with a declarative syntax.
  • Syntax is a little messy since HTML does not have the concept of <behavior>.
  • Only supports "validate on submit style" as far as I can tell
• Angular forms very flexible, with support for many states.
  • Not fully declarative
• In some custom elements used at Instawork, we use an attribute role to identify elements controlled by the custom component. In our S3 file upload component, a <text> element with role="upload-progress-text" gets populated with a text representation of the upload progress, eg "30%". We can use a similar idea for showing the

Proposal

All elements and attributes for validation will use the namespace https://hyperview.org/hyperview-validation. In examples, this will be aliased to v.

Declaring Validation

Validators on inputs are defined as child elements. Each child element must have a unique tag name. Other attributes on the validator element specify the validation parameters and error messages.

For example, here's the validator for a required input:

<v:required message="Age is required." />

Here's a validator to ensure the input value is an integer:

<v:integer message="Please enter a number" />

This validator include extra attribute to specify a min/max range of the input value:

<v:range min="18" max="99" message="Age must be between 18 and 99" />

A validator can only appear as a child element of an input element (<text-field>, <select-single>, etc). Each input can have many validators. For example, to define a required age input:

<text-field name="age" keyboard-type="number-pad">
  <v:required message="Age is required" />
  <v:range min="18" max="99" message="Age must be between 18 and 99" />
</text-field>

During field validation, the validators are checked in the order in which they appear under the input element. Checking the validators stops at the first failed check. If a check fails, the input is considered invalid with the message corresponding to the failed check. Subsequent validators are not checked during an instance of validation once a field is invalid. If all validator checks pass, the input is considered valid. Take the example above:

• If we run validation on an empty input, the input will be invalid with the message "Age is required".
• If we run validation on the input with value "15", the input will be invalid with the message "Age must be between 18 and 99".
• If we run validation on the input with the value "20", the input will be valid.

Creating custom validation rules

Like components and behaviors, users can register custom validators. A custom validator is implemented as a function that takes the value and validator element. It returns a JS object with a required key "valid" (boolean) and optional key "message" (string). As an example, here's a custom validator that checks the input value against a regular expression:

function (value, validatorElement) {
  const regex = new RegExp(validatorElement.getAttribute("regex"));
  const message = validatorElement.getAttribute("message");
  if (regex.test(value)) {
    return {valid: true};
  }
  return {valid: false message: message};
}

Registering a custom validator is similar to registering a custom behavior. The Hyperview RN component takes a validators prop, which is an array of objects. Each object has a key "name" with the name of the validator, and "callback" which is the validator function:

const regexValidator {
  action: "regex",
  callback: function(value, validatorElement) { /* ... */ }
}

return (
  <Hyperview
    entrypointUrl={url}
    validators={[regexValidator]}
  />
);

The XML could now refer to a "regex" validator in any screen:

<text-field name="phone-number" keyboard-type="number-pad">
  <v:regex regex="^[\+]?[(]?[0-9]{3}[)]?[-\s\.]?[0-9]{3}[-\s\.]?[0-9]{4,6}$" message="Enter a valid phone number" />
</text-field>

Triggering Validation

Validation is triggered with a new validate behavior action. The target of the behavior can be a <form> element or an input element.

<form id="myForm">
  <text-field name="username">
    <v:required message="Username is required" />
  </text-field>

  <text-field id="ageField" name="age" keyboard-type="number-pad">
    <v:required message="Age is required" />
    <v:range min="18" max="99" message="Age must be between 18 and 99" />
  </text-field>

  <text>
    <behavior action="validate" target="myForm" />
    Validate Form
  </text>

  <text>
    <behavior action="validate" target="ageField" />
    Validate Age
  </text>
</form>

When validating an entire <form>, each input element in the <form> will be validated independently. In the example above, we will validate age even if username is invalid. Validating on individual inputs can be useful if triggered on blur:

  <text-field name="age" keyboard-type="number-pad">
    <behavior trigger="blur" action="validate" />
    <v:required message="Age is required" />
    <v:range min="18" max="99" message="Age must be between 18 and 99" />
  </text-field>

Validation state is reflected in the XML through the addition of a v:state attribute to the <form>, input, and validator elements. The v:state attribute values are valid, invalid, and indeterminate. Lack of the attribute implies indeterminate state. Post-validation, the form would have the following XML:

<form id="myForm" v:state="invalid">
  <text-field name="username" value="myname" v:state="valid">
    <v:required message="Username is required" v:state="valid" >
  </text-field>

  <text-field id="ageField" name="age" keyboard-type="number-pad" value="14" v:state="invalid">
    <v:required message="Age is required" v:state="valid" />
    <v:range min="18" max="99" message="Age must be between 18 and 99" v:state="invalid" />
  </text-field>
</form>

Note that <form>, <text-field>, <v:required> and <v:range> elements all contain the v:state attributes.

The state attribute can be set from the server. This is useful to combine server-side validation with client-side validation.

Showing Validation State

Error Messages

<view>
  <text-field id="ageInput" name="age" keyboard-type="number-pad">
    <v:required message="Age is required" />
    <v:range min="18" max="99" message="Age must be between 18 and 99" />
  </text-field>
  <text v:role="message" v:source="ageInput" />
</view>

Styles

We already have the concept of "modifier" styles. Current modifiers can reflect whether the element is pressed, selected, or focused. To support validation states, I recommend we add modifiers for valid and invalid states. The unmodified style corresponds to indeterminate state of the elements. The modifier would be applied immediately when the v:state attribute on an element changes.

<style id="text-field" borderWidth="1" borderColor="gray">
  <modifier validation="valid">
    <style borderColor="green" />
  </modifier>
  <modifier validation="invalid">
    <style borderColor="red" />
  </modifier>
</style>

Sometimes, it may be useful to modify the style of an element around the text field. For example, perhaps the label above the text field should turn red when the input is invalid. This can be achieved by adding the attribute v:role="style" to the element, and a v:source attribute with the ID of the validated input element. When the input element changes validation state, the corresponding elements will re-render with appropriate modifier styles.

<style id="label" color="gray">
  <modifier validation="invalid">
    <style borderColor="red" />
  </modifier>
</style>

...

<view>
  <text style="label" v:role="style" v:source="ageInput">Age</text>
  <text-field id="ageInput" name="age" keyboard-type="number-pad">
    <v:required message="Age is required" />
    <v:range min="18" max="99" message="Age must be between 18 and 99" />
  </text-field>
  <text v:role="message" v:source="ageInput" />
</view>

Summary of changes:

• Add validator framework, with support for custom validators
• Add validate action for behaviors
• Represent validation state with v:state attributes on validated forms and inputs.
• Use v:role and v:source attributes to modify elements in response to a validation:
  • v:role="message" populates error messages in <text> elements.
  • v:role="style" applies the valid or invalid style modifier to the element.
• Add valid and invalid style modifiers

[adamstep]

@terryatgithub I moved the discussion here, starting to evaluate options more seriously.

[eazuka]

i really really really like this proposed approach.
it is well thought out

[terryatgithub]

Wow, Adam, you are amazing.
The proposal is very comprehensive and impressive. even considering the below situation:
The state attribute can be set from the server. This is useful to combine server-side validation with client-side validation..
looking forward to it.

[adamstep]

I finally found time to make some progress here, check out the branch for current code: https://github.com/Instawork/hyperview/compare/adam/validate

This prototype supports some basic validation that can be triggered via a behavior action. The example shows validation on button press, input change, or focus/blur:

validation_prototype.mp4

Markup for this video:

<form>
  <view style="FormGroup">
    <text style="label">Validate with button press</text>
    <text-field
        placeholder="First name"
        placeholderTextColor="#8D9494"
        name="text"
        style="input"
        id="input-1"
    >
      <v:required message="First name required" />
      <v:length min-length="2" max-length="5" message="Length must be between 2 and 5" />
    </text-field>
    <text style="help help--error" v:role="message" v:source="input-1" />

    <view style="Button">
      <behavior trigger="press" action="validate" target="input-1" />
      <text style="Button__Label">Validate</text>
    </view>
  </view>

  <view style="FormGroup">
    <text style="label">Validate on change</text>
    <text-field
        placeholder="First name"
        placeholderTextColor="#8D9494"
        name="text"
        style="input"
        id="input-2"
    >
      <behavior trigger="change" action="validate" target="input-2" />
      <v:required message="First name required" />
      <v:length min-length="2" max-length="5" message="Length must be between 2 and 5" />
    </text-field>
    <text style="help help--error" v:role="message" v:source="input-2" />
  </view>

  <view style="FormGroup">
    <text style="label">Validate on focus & blur</text>
    <text-field
        placeholder="First name"
        placeholderTextColor="#8D9494"
        name="text"
        style="input"
        id="input-3"
    >
      <behavior trigger="blur" action="validate" target="input-3" />
      <behavior trigger="focus" action="validate" target="input-3" />
      <v:required message="First name required" />
      <v:length min-length="2" max-length="5" message="Length must be between 2 and 5" />
    </text-field>
    <text style="help help--error" v:role="message" v:source="input-3" />
  </view>
</form

[eazuka]

Really Awesome!

[terryatgithub]

Thanks @adamstep for your great job. Sorry for the late reply, I haven't followed Github for a while.
I haven't had time to take a close look at your source code, but the demo shows that some of the desired effects have been achieved, in a more elegant way.
It's Amazing.

We have recently adopted Hyperview for a new project, and they also have a lot of business involving front-end form validation. We are all happy to see this progress and looking forward to the official release asap.

Thank you again and wish all the best.

[Sakura-pgh]

Can’t wait to see the new version! @adamstep.
Our company plans to start a new modularized Hyperview program. This function is very crucial to us which solves a problem that bother us for a long time.
Thanks again, hopes everything going well.

[WayneWLO]

Hello @adamstep, my company's products use Hyperview to dynamically load app views. This form validation feature seems to be very necessary, may I ask when it will be updated. Thank you so much!

[adamstep]

Hi @WayneWLO , I haven't had time to make progress on it recently. I have some other projects I need to complete in the next few weeks, then I'll jump back on the client-side form validation support!

[eazuka]

You are amazon @adamstep, this has been long awaited. Now i can start my project with hyperview.

[adamstep]

Updated with an approach to changing styles on elements other than input field. Latest code is here: https://github.com/Instawork/hyperview/compare/adam/validate2

[eazuka]

Hello @adamstep, it's been a while. hope you doing good.
I am starting a new mobile app project and this time, using Hyperview is a must.

What is the status of this feature, it's been like 3yrs and it seem completed/useable going by your last message of may last year. Has it been released yet and now part of the hyperview client? I asked because going through the hyperview documentation, I didn't see any mention of client side validation.

If it hasn't been released yet, how can I use/add this frontend validation feature?

[adamstep]

Work in progress is here: https://github.com/Instawork/hyperview/commits/adam/valid1/

This new branch is ported to TypeScript, and includes full support for custom input element (with multiple name/value pairs). Will put up as a pull request once I've finished adding tests.

[ehenighan]

I've got a small suggestion for an extension to make, based on building something similar with events and a custom form-validation component:

It would be even more powerful if you also had the option of adding your <v:...> tags elsewhere in the form with child elements and target the appropriate input field via its name attribute, instead of purely as children of the validated element with a piece of text. That way, you have the option to move your validation errors to the top/bottom/side of a component, or show all errors in bulk in one place instead of next to the field, etc.

What I've got working at the moment looks roughly like:

<form id="this-form">
    <text-field name="valueA" />
    <form-validation:form-constraint xmlns:form-validation="<validation-namespace>" form-field="valueA" required="true">
        <view style="flex-none flex-col jc-center ai-center h-single w-100 clr-alert-warning-bg clr-alert-warning-border b-1 br-10">
            <text style="flex-none w-100 tx-c clr-alert-warning-text">Please enter Value A</text>
        </view>
    </form-validation:form-constraint>
    <inputs:number-field xmlns:inputs="<inputs-namespace>" name="valueB" />
    <form-validation:form-constraint xmlns:form-validation="<validation-namespace>" form-field="valueB" required="true" min="2" max="100">
        <view style="flex-none flex-col jc-center ai-center h-single w-100 clr-alert-warning-bg clr-alert-warning-border b-1 br-10">
            <text style="flex-none w-100 tx-c clr-alert-warning-text">Please enter a value in the right range for Value B</text>
        </view>
    </form-validation:form-constraint>
    <view>
        <text>Submit</text>
        <behavior trigger="press" action="submit-form" target="this-form" />
        <behavior trigger="on-event" event-name="submit-form:this-form" action="replace" verb="post" target="this-form" href="..."/>
    </view>
</form>

The form-field attribute on the form-constraint entries lets me target inputs in the parent form by name and the form-constraint component just only renders its children when the relevant show-constraint attribute is set to true by the form submit hooks - that way, if I want to re-render an invalid form from the server with messages in place, I can render it with show-constraint="true" from the start.

The form submit hook then looks like a worse version of what you've got because I've done it with custom events instead of forking the framework code - submit-form behaviour is handled, form found either by explicit target or ancestor form element of the behavior tag, form-constraint elements found within the form, checks made and form-constraint elements made visible if they don't pass, and if the form does pass we emit a submit-form:<form ID> event which then completes the loop.

Not going to post any code details of that bit because:

1. Elements of it are pretty similar to your pattern only inside a custom submit-form behaviour handler
2. Yours is much much nicer!

But you get the idea - the thing I'm mostly getting at is the idea of being able to wrap & position arbitrary UI components around the form within a validator tag. I think looking at your commits it would be a pretty small extension that would fit with what you've already built - you'd just add a form-field or target attribute to your validator element and optionally use that instead of always expecting the parent input, and allow it to have children that are only shown when the target element is invalid. Then you've got all the nice behaviour you've already written, plus the ability to radically extend the UI for it.

Very basic example - the below error is client-side but could go anywhere within the form and show any UI elements I want, like a big 'X' SVG icon, a hyperlink to an explanation of what you have to type in the field, etc., and I could start it off visible on render if I wanted:

It's particularly useful as a pattern for cases like this where there are actually multiple input elements and I may need to apply validation across a group of them, so there's not just one single long input that can show my whole error text. Another example where this helps is with validation like 'you must fill out at least one of these text inputs' - you don't want to show that error if any of the text fields is filled out, but when they're all empty then you want to either show the same error next to them all or show one error in a sensible place.

[adamstep]

Thanks for sharing. I like some of the ideas in your proposal:

• more flexible placement of constraints. This doc did not cover inter-field validation. My thinking was to support validators as direct children of the <form> element in the future. Do you think that would cover your needs, as opposed to completely free placement within the form?
• Full UI control on invalid inputs. My proposal only sets a text message, but that's not as flexible as your approach. However, how would your proposal scale to support a UI on valid inputs? For example, sometimes we want to show a "Valid password" message when a user enters a password that matches the min length.

[ehenighan]

Direct child of form would work fine for me, I think - would have to be doing some fairly odd juggling of layouts to need anything more complex.

For on-valid display, I would probably lean on the event-driven behavior approach for flexibility, e.g.:

• extend the form-constraint component with a show-on="valid | invalid" attribute used to determine the initial visibility state and invert the conditions for rendering the child components
• add a trigger="change" action="evaluate-constraints" target="<input-name spaced list>" behavior to any input I want to constantly re-validate, which would trigger a re-evaluation of constraints attached to that specific input (potentially with evaluate-constraints-valid and evaluate-constraints-invalid flavours for flexibility)
• if you wanted to be incredibly granular you could have action="evaluate-constraint" target="<constraint-element-id spaced list>" to let you pick off individual constraints to check, in the event that some can be evaluated as you type and some should be left until form-submission. I think that's probably overkill though.

That way you could have invalid or valid constraint UI showing as soon as a relevant input is updated, or you could just have them showing on form submit, or any sensible combination, using the existing declarative behavior mechanism:

• valid UI shown as you type, invalid UI shown on form-submit failure
• valid and invalid UI shown as appropriate as you type (probably annoying?)
• valid and invalid UI shown as appropriate on form submission, with a delay to the server call so when you click Submit, e.g. green ticks appear for a second or two before the form is replaced

And, by using the behavior to cause evaluation of the constraints, you also unlock the ability to trigger per-component constraint evaluation from other actions/components/events - e.g. a 'check this input is valid' button, or if you had a pick-list component that lazy-loaded options (I don't, I'm just thinking of examples), or a form with some dynamic-visibility stages, you could choose to fire an event to evaluate the appropriate constraints when the list loaded, conditional input became visible, etc.

EDIT: fixed example behavior definition to use target attribute for consistency