Introducing ATGValidator for Swift

A simple, easy to use, open-source validation framework written in Swift

When we started working on our first in-house eCommerce apps at Al Tayer Digital, one of the challenges we faced was performing user input validations efficiently and in a maintainable way. Our initial solution for validation was by adding ad-hoc solutions including length/character-set checks and regex string matching. Needless to say, in a few weeks, it became too difficult to track these pieces of code distributed across the project.

We started exploring open source frameworks to find if there is any that will match our requirements. Our main focus was on ease of use, low boilerplate code, and most importantly form validation. The main contenders for selection were SwiftValidator and Validator.

Both frameworks were rule-based but were functioning in different ways. SwiftValidator performed validations based on a Validator instance, and apps need to manually trigger validation by hooking up with UITextField and UITextView delegates. This introduced a lot of boilerplate code, and we wanted to avoid this.

Validator framework addressed this issue by adding targets to UITextField and UITextView in framework, and running validation when specific events occurred. This was looking promising, except one aspect. Validator was using generics extensively, and this made it impossible to club together different validation results. So no form validation was possible with it.

So we wanted to combine the best aspects of both frameworks and create a new framework that is easy to use, with minimal boiler-plate code, and form validation support. And that’s when we wrote ATGValidator.

ATGValidator is rule based validation framework written in a protocol based approach. You get a set of predefined rules, and can define new rules easily. UITextField and UITextView has build in support for validation, and it’s easy to add validation support for custom UI elements. You get a form validator which can group multiple UI elements together and give a unified result for validation. And you can run validations on individual data types like String, Int, Double etc independently without need for a UI element.

Let me show how easy it is to use the framework with an example below. Download the starter project from here.

Unzip the downloaded file, and go to the folder in Terminal, and run

pod install

Now open the generated xcworkspace file, and run the app. You can see a basic signup form implemented in the app. Now, let’s add some validation.

Import ATGValidator in ViewController.swift

import ATGValidator

Create an instance of FormValidator

let formValidator = FormValidator()

Now in viewDidLoad, add the following lines of code

nameTextField.validationRules = [StringLengthRule.min(5)]
numberTextField.validationRules = [
    StringLengthRule(min: 8, max: 12, ignoreCharactersIn: CharacterSet.whitespacesAndNewlines),
    CharacterSetRule.numbersOnly(ignoreCharactersIn: CharacterSet.whitespacesAndNewlines)
]
addressTextView.validationRules = [StringLengthRule.min(20)]
passwordTextField.validationRules = [
    StringLengthRule.min(6),
    CharacterSetRule.containsNumber(),
    CharacterSetRule.containsUpperCase(),
    CharacterSetRule.containsLowerCase()
]
confirmPasswordTextField.validationRules = [
    StringValueMatchRule(base: passwordTextField),
    StringLengthRule.required()
]
formValidator.add(nameTextField)
formValidator.add(numberTextField)
formValidator.add(addressTextView)
formValidator.add(passwordTextField)
formValidator.add(confirmPasswordTextField)

Now add a validation handler inside `didTapOnProceedButton` method as shown below;

formValidator.validateForm(completion: { result in
    let alert = UIAlertController(
        title: "Validation result",
        message: result.status == .success ? "Successful" : "Failed",
        preferredStyle: .alert
    )
    alert.addAction(UIAlertAction(title: "OK", style: .cancel))
    self.present(alert, animated: true)
})

Now when you tap on the proceed button, the framework validates the input with rules and provides a result object with an array of errors and the result is shown in an alert view.

Just showing if validation failed or succeeded will not be good enough to provide a good user experience. So, let’s add some meaningful error messages to the rules.

nameTextField.validationRules = [
  StringLengthRule.min(5).with(errorMessage: "Name needs to have atleast 5 characters")
]
numberTextField.validationRules = [
  StringLengthRule(
    min: 8,
    max: 12,
    ignoreCharactersIn: CharacterSet.whitespacesAndNewlines
  ).with(errorMessage: "Phone number must be between 8 and 12 digits long"),
  CharacterSetRule.numbersOnly(
    ignoreCharactersIn: CharacterSet.whitespacesAndNewlines
  ).with(errorMessage: "Phone number must have only numbers")
]
addressTextView.validationRules = [
  StringLengthRule.min(20).with(errorMessage: "Address must have atleast 20 characters")
]
passwordTextField.validationRules = [
  StringLengthRule.min(6).with(errorMessage: "Password must have atleast 6 characters"),
  CharacterSetRule.containsNumber().with(errorMessage: "Password must have atleast 1 number"),
  CharacterSetRule.containsUpperCase().with(errorMessage: "Password must have atleast 1 uppercase"),
  CharacterSetRule.containsLowerCase().with(errorMessage: "Password must have atleast 1 lowercase")
]
confirmPasswordTextField.validationRules = [
  StringValueMatchRule(base: passwordTextField).with(errorMessage: "Passwords does not match"),
  StringLengthRule.required().with(errorMessage: "Confirm password field cannot be empty")
]

ValidationError is a framework level enumeration conforming to Error protocol and is used for identifying default errors. It has an additional custom case with error message to be used for easy error handling.

Rule protocol has 2 helper methods to associate an error object or an error message to itself. The methods being used in above code sample is the one with errorMessage.

And update the form validation handler as follow;

formValidator.validateForm(completion: { result in
  let message = result.errors?.reduce("", { (string, error) -> String in
    let validationError = error as? ValidationError
    return string + (validationError?.customErrorMessage ?? String(describing: validationError)) + "\n"
  })
  let alert = UIAlertController(
    title: "Validation " + (result.status == .success ? "Successful" : "Failed"),
    message: message,
    preferredStyle: .alert
  )
  alert.addAction(UIAlertAction(title: "OK", style: .cancel))
  self.present(alert, animated: true)
})

The snippet above goes through all the error objects passed in from the validation result and creates an alert message from it.

This will not be the best experience we can give to the user. Rather than showing it in an alert view, let’s update the experience to give more context to the specified errors.

Let’s move around and clean up the code a bit to make it more readable.

First, create a Constants enumeration inside the Viewcontroller class.

private enum Constants {
  static let cornerRadius: CGFloat = 3.0
  static let borderWidth: CGFloat = 1.0
  static let errorColor: CGColor = UIColor.red.cgColor
  static let validColor: CGColor = UIColor.clear.cgColor
}

Now move all validation rule setting to a new method.

private func configureValidations() {
    nameTextField.validationRules = [StringLengthRule.min(5).with(errorMessage: "Name needs to have atleast 5 characters")]
    numberTextField.validationRules = [
        StringLengthRule(min: 8, max: 12, ignoreCharactersIn: CharacterSet.whitespacesAndNewlines).with(errorMessage: "Phone number must be between 8 and 12 digits long"),
        CharacterSetRule.numbersOnly(ignoreCharactersIn: CharacterSet.whitespacesAndNewlines).with(errorMessage: "Phone number must have only numbers")
    ]
    addressTextView.validationRules = [StringLengthRule.min(20).with(errorMessage: "Address must have atleast 20 characters")]
    passwordTextField.validationRules = [
        StringLengthRule.min(6).with(errorMessage: "Password must have atleast 6 characters"),
        CharacterSetRule.containsNumber().with(errorMessage: "Password must have atleast 1 number"),
        CharacterSetRule.containsUpperCase().with(errorMessage: "Password must have atleast 1 uppercase"),
        CharacterSetRule.containsLowerCase().with(errorMessage: "Password must have atleast 1 lowercase")
    ]
    confirmPasswordTextField.validationRules = [
        StringValueMatchRule(base: passwordTextField).with(errorMessage: "Passwords does not match"),
        StringLengthRule.required().with(errorMessage: "Confirm password field cannot be empty")
    ]
    formValidator.add(nameTextField)
    formValidator.add(numberTextField)
    formValidator.add(addressTextView)
    formValidator.add(passwordTextField)
    formValidator.add(confirmPasswordTextField)
}

Create a new method to register validation handlers for individual fields and update the UI to display errors.

private func configureFieldErrorHandlers() {
    nameTextField.validationHandler = { [weak self] result in
        self?.nameTextField.layer.borderColor = result.status == .failure ? Constants.errorColor : Constants.validColor
        self?.nameTextField.layer.borderWidth = result.status == .failure ? Constants.borderWidth : 0.0
        self?.nameErrorLabel.text = (result.errors?.first as? ValidationError)?.customErrorMessage
    }
    numberTextField.validationHandler = { [weak self] result in
        self?.numberTextField.layer.borderColor = result.status == .failure ? Constants.errorColor : Constants.validColor
        self?.numberTextField.layer.borderWidth = result.status == .failure ? Constants.borderWidth : 0.0
        self?.numberErrorLabel.text = (result.errors?.first as? ValidationError)?.customErrorMessage
    }
    addressTextView.validationHandler = { [weak self] result in
        self?.addressTextView.layer.borderColor = result.status == .failure ? Constants.errorColor : Constants.validColor
        self?.addressTextView.layer.borderWidth = result.status == .failure ? Constants.borderWidth : 0.0
        self?.addressErrorLabel.text = (result.errors?.first as? ValidationError)?.customErrorMessage
    }
    passwordTextField.validationHandler = { [weak self] result in
        self?.passwordTextField.layer.borderColor = result.status == .failure ? Constants.errorColor : Constants.validColor
        self?.passwordTextField.layer.borderWidth = result.status == .failure ? Constants.borderWidth : 0.0
        self?.passwordErrorLabel.text = (result.errors?.first as? ValidationError)?.customErrorMessage
    }
    confirmPasswordTextField.validationHandler = { [weak self] result in
        self?.confirmPasswordTextField.layer.borderColor = result.status == .failure ? Constants.errorColor : Constants.validColor
        self?.confirmPasswordTextField.layer.borderWidth = result.status == .failure ? Constants.borderWidth : 0.0
        self?.confirmPasswordErrorLabel.text = (result.errors?.first as? ValidationError)?.customErrorMessage
    }
}

Above method has a lot of repeating code for displaying error messages, but I won’t be covering it’s refactor in this article.

Since we will be showing validation errors on individual fields, we don’t need to show the alert on tapping the proceed button. So, let’s update the FormValidator handler closure to update the state of the proceed button based on validation result. Add a new method as shown below;

private func configureFormHandler() {
    proceedButton.isEnabled = false
    proceedButton.alpha = 0.5
    formValidator.handler = { [weak self] result in
        let isFormValid = result.status == .success
        self?.proceedButton.isEnabled = isFormValid
        self?.proceedButton.alpha = isFormValid ? 1.0 : 0.5
    }
}

And remove the unnecessary code in IBAction for the proceed button as shown below;

@IBAction private func didTapOnProceedButton() {
    // TODO: Perform proceed action.
}

Now, let’s update the viewDidLoad method to call these methods;

override func viewDidLoad() {
    super.viewDidLoad()
    addObserversForKeyboard()
    
    nameTextField.layer.cornerRadius = Constants.cornerRadius
    numberTextField.layer.cornerRadius = Constants.cornerRadius
    addressTextView.layer.cornerRadius = Constants.cornerRadius
    passwordTextField.layer.cornerRadius = Constants.cornerRadius
    confirmPasswordTextField.layer.cornerRadius = Constants.cornerRadius
    configureFormHandler()
    configureValidations()
    configureFieldErrorHandlers()
}

Build and run the app. Voila, now we have a fully functional form validation in place. See it in action below;

You can download the complete sample project from here.

There are many more things under the hood in ATGValidator. And covering them all will not be possible in a single article.

If you want to learn in-depth about the framework head over to the readme section of the project in Github.

To learn more about using ATGValidator to validate credit card numbers, head over to this article.

If you found this article helpful, please don’t forget to clap. Cheers..!