README.md

form-binder

Form-binder is a micro data binding and validating framework, very easy to use and hack.

It was initially created for my Scalatra-based project, but you can easily integrate it with other frameworks.

Features

• very lightweight, only ~900 lines codes (framework + built-in extensions)
• easy use, no verbose codes, and what you see is what you get
• high customizable, you can extend almost every executing point
• easily extensible, every extension interface is an alias of FunctionN
• immutable, you can share mapping definition object safely

Usage

Steps:

1. define your binder
2. define your mappings
3. prepare your data
4. bind and consume

p.s. every points above (1)/(2)/(3)/(4)/ are all extendable and you can easily customize it.

Install & Integrate

To use form-binder, pls add the dependency to your sbt project file:

libraryDependencies += "com.github.tminglei" %% "form-binder" % "0.12.2"

Then you can integrate it with your framework to simplify normal usage.

Here's the way in my Scalatra project:

First, I defined a FormBindSupport trait,

trait MyFormBindSupport extends I18nSupport { self: ScalatraBase =>
  import MyFormBindSupport._

  before() {
    request(BindMessagesKey) = Messages(locale, bundlePath = "bind-messages")
  }

  def binder(implicit request: HttpServletRequest) = FormBinder(bindMessages.get, errsTree())

  ///
  private def bindMessages(implicit request: HttpServletRequest): Messages = if (request == null) {
    throw new ScalatraException("There needs to be a request in scope to call bindMessages")
  } else {
    request.get(BindMessagesKey).map(_.asInstanceOf[Messages]).orNull
  }
}

Then mix it to my xxxServlet, and use it like this,

import com.github.tminglei.bind.simple._

class SampleServlet extends ScalatraServlet with MyFormBindSupport {

  get("/:id") {
    val mappings = tmapping(
      "id" -> long()
    )
    binder.bind(mappings, params).fold(
      errors => holt(400, errors),
      { case (id) =>
        Ok(toJson(repos.features.get(id)))
      }
    )
  }
}

p.s. you can check more integration sample codes under /integrations.

How it works

Principle

The core of form-binder is Mapping, tree structure mappings. With depth-first algorithm, it was used to validate data and construct the result value object.

Details

Major Components:

[1] binder: facade, used to bind and trigger processing, two major methods: bind, validate
[2] messages: used to provide error messages
[3] mapping: holding constraints, processors, and maybe child mapping, etc. used to validate/convert data, two types of mappings: field and group
[4] data: inputting data map

Check here and here for framework details.

binder bind method signature (return an Either and let user to continue processing):

//bind mappings to data, and return an either, holding validation errors (left) or converted value (right)
def bind[T](mapping: Mapping[T], data: Map[String, String], root: String = ""): Either[R, T]

binder validate method signature (validate only and not consume converted data):

//return (maybe processed) errors
def validate[T](mapping: Mapping[T], data: Map[String, String], root: String = "")

Check here for built-in mappings.

Extension Types:

(1) ErrProcessor: used to process error seq, like converting it to json
(2) PreProcessor: used to pre-process data, like omitting $ from $3,013
(3) Constraint: used to validate raw string data
(4) ExtraConstraint: used to validate converted value

* Check here for built-in PreProcessor/ErrProcessor.
**Check here for built-in Constraint/ExtraConstraint.

Options/Features:

1. label: feature, readable name for current group/field
2. mapTo: feature, map converted value to another type
3. i18n: feature, labels starting with @ will be used as a message key to fetch a i18n value from messages
4. eagerCheck: option, check errors as more as possible; default false, return right after a validation error found
5. skipUntouched: option, skip checking untouched empty field/values; default false, won't skip untouched
6. touchedChecker: function, check whether a field was touched by user; if yes, required fields can't be empty

p.s. for more dev and usage details, pls check the source codes and test cases.

How to

[TODO]

Build & Test

To hack it and make your contribution, you can setup it like this:

 $ git clone https://github.com/tminglei/form-binder.git
 $ cd form-binder
 $ sbt
...

To run the tests, pls execute:

 $ sbt test

Acknowledgements

• Play! framework development team, for the original idea and implementation;
• Naoki Takezoe and his scalatra-forms, a play-data implementation for scalatra.

License

The BSD License, Minglei Tu <[email protected]>