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?