Batman.js is no longer in production at Shopify and is not actively maintained.

This website is left for reference (and for old times' sake).

batman.js

Batman.Validator extends Batman.Object and is the abstract superclass for all validators in batman.js. batman.js ships with a plethora of built-in validators.

  • Custom Validators

    You can create custom validators by:

    • subclassing Batman.Validator,
    • implementing ::validateEach, and
    • adding the new validator to the Batman.Validators array.

    For example:

    class App.LessThanPropertyValidator extends Batman.Validator
      @triggers 'lessThanProperty'
      @options 'allowBlank'
    
      validateEach: (errors, record, attribute, callback) ->
          value = record.get(attribute)
          compareAttr = @options.lessThanProperty
          otherValue = record.get(compareAttr)
          else !@handleBlank(value) && value >= otherValue
            errors.add(attribute, 'must be less than #{compareAttr}')
          callback()
    
    Batman.Validators.push App.LessThanPropertyValidator

    Could be used as:

    class App.Pyramid extends Batman.Model
      @encode 'top', 'base'
      # A pyramid's top must be smaller than its base:
      @validate 'top', lessThanProperty: 'base'
  • constructor(options : Object[, mixins...]) : Validator

    The first argument becomes the validator's @options. Subsequent arguments are mixed in to the validator with Batman.Object::mixin. You can override this method to alter the options object before it's assigned to @options. (Make sure to call super afterwards!)

  • @triggers(triggers...)

    When any of the strings in triggers is passed to Model.validate:

    • this validator will be instantiated and its validateEach will be invoked
    • the key-value pairs passed to Model.validate with these keys will be available on @options for this validator.

    Use this method when one validator will handle many kinds of validations. For example, a simplified length validator:

    class App.SimpleLengthValidator extends Batman.Validator
      @triggers 'minLength', 'maxLength', 'length'
    
      constructor: (options) ->
        # has access to options.minLength, options.maxLength, options.length
        super
    
      validateEach: (errors, record, attribute, callback) ->
        # has access to @options.minLength, @options.maxLength, @options.length

    All three of these validations will be handled by App.SimpleLengthValidator::validateEach:

    class App.Superhero extends Batman.Model
      @validate 'name', minLength: 3
      @validate 'bio', maxLength: 250
      @validate 'phone_number', length: 10
  • @options(options...)

    The key-value pairs passed to Batman.Model.validate with these keys will be available on @options for this validator.

    Unlike @triggers, the presence of a key in options will not cause this validator to be instantiated.

  • validateEach(errors: ErrorsSet, record: Model, attribute: String, callback: Function)

    This method is invoked to validate attribute on record. If this method determines that the attribute is invalid, it should add a validation error to errors:

    errors.add("phone_number", "isn't 10 characters long")

    When the validator is finished, it must call callback to continue the validation chain.

  • @handleBlank(value)

    Returns true if options.allowBlank is true and value is null, undefined or ""

  • format(attr, messageKey, interpolations, record) : String

    Generates a human-readable message for messageKey by:

    • Using the message option passed to @validate, if present
    • Looking up messageKey in the current locale's errors.messages

Help us improve our documentation!

Contributions to this page are welcome on Github. If you find a problem but you cannot fix it, please open an issue.

Discussion regarding batman.js documentation is also welcome on our mailing list.