Formality is a library that provides better, cleaner, more palatable form handling for Lift. Form handling without the pain, if you will.
The goal of creating this library was to eliminate as much repetition as possible while wielding the full power of Lift's stateful form mechanism and its CSS selector transforms, as well as embracing Lift's own error-reporting mechanisms.
Formality is still in an early state. While there are tests ensuring everything works, use in production is likely to uncover some undiscovered bugs. Those bugs will be crushed as quickly as possible once reported on Github.
You can include Formality directly as a dependency in your build.sbt,
suffixing the major and minor Lift version you are using (3.0 thru 3.3 are
currently supported).
For example to include the build for 3.3, you would write:
libraryDependencies ++= Seq(
"com.hacklanta" %% "lift-formality_3.3" % "1.2.0"
)
And for 3.2 you would write:
libraryDependencies ++= Seq(
"com.hacklanta" %% "lift-formality_3.2" % "1.2.0"
)
And soforth.
Formality provides a DSL for binding forms already defined in the HTML.
It leaves as much of the markup as possible to the markup itself, and
layers on only the necessary functionality from Lift's side. Amongst
other things, this means that the type of a field in the HTML is left
to the markup.
A basic form snippet would look like this:
import com.hacklanta.formality.Formality._
val registrationForm =
form withFields(
field[String](".name"),
field[String](".phone-number"),
field[Int](".age"),
checkboxField("#terms-and-conditions")
) onSuccess { (name, phoneNumber, age, termsAndConditions) =>
// Assuming a case class User(name: String, age: Int, phoneNumber: String, termsAndConditions: Boolean).
User(name, age, phoneNumber, termsAndConditions).save
}
"form" #> registrationForm.binderThe corresponding HTML5 markup could be:
<form data-lift="Registration.form">
<input class="name">
<input class="phone-number" placeholder="(XXX) XXX-XXXX">
<input class="age" type="number">
<label for="terms-and-conditions>
<input type="checkbox" id="terms-and-conditions">
I agree to the <a href="/terms">Terms and Conditions</a>
</label>
</form>This is a very basic registration form with no validations or event callbacks. The key here is that our success handler gets a set of properly-typed values. It is only called if all of the entries can properly be deserialized into their requested types (for example, putting in "hello" for the age would mean the success callback would not run).
Behind the scenes, Formality tries to deserialize the values. If
the deserialization fails, S.error is automatically set for the
appropriate field. You can then customize the behavior of S.error as
you desire (see LiftRules
for more, specifically the noticesToJsCmd property).
Formality can also do validation:
import com.hacklanta.formality.Formality._
import com.hacklanta.formality.Html5Validations._
val nameField = field[String](".name") ? notEmpty
val phoneNumberField = field[String](".phone-number")
val ageField = field[Int](".age") ? inRange(15, 120)
val termsField =
checkboxField("#terms-and-conditions") ? { incoming: Boolean =>
if (incoming) {
Empty
} else {
Full("You must agree to the terms and conditions.")
}
}
val registrationForm =
form withFields(
nameField,
phoneNumberField,
ageField,
termsField
) onSuccess {
// same as above
}Now we've taken it a step further. Validations can be simple
functions. These functions take the deserialized value (i.e., the value
after it has been typed properly) and return a Full Box with an
error message when there is an error, or an Empty Box if the value
is valid. In cases where a validation fails (by providing an error
message), that error message is associated with the appropriate field by
calling S.error.
Validations can also be more than simple functions. The built-in
validations, like inRange and notEmpty, extend the Validation
trait. These Validations are still functions that work as specified
above (i.e., they have an apply method that behaves as we specified
above). However, they also have a binder method that returns a
CssSel. These can be used to provide client-side attributes to also
enforce the validation client-side. Client-side validations have
the advantage of being able to run faster and without taxing the
server. Validations allow you to specify client-side validations and
pair them with server-side validations to ensure that valid data is what
makes it into your database.
The two built-ins used above are from the Html5Validations object,
which does client-side validation using HTML5 attributes. In particular,
the notEmpty validation applies a required attribute to the input,
and the inRange validation applies min and max attributes to the
input.
Also in progress is an object, ParsleyValidations, meant to support
the set of validations that are supported by
Parsley.js. These will have matching server-side
validation implementations.
In certain very specific cases, it can be useful to run a validation even
if the value in question isn't actually submitted in the form. Typically
this is used for a check that a required field was submitted, particularly
when it comes from a checkbox or radio button. Either way, in these cases
a validation can take a Box[T] instead of T. It will receive an Empty
if the field is not submitted, and a Full with the deserialized value if
the field is submitted. Lift-formality's own notBlank/notEmpty validators
will correctly handle unsubmitted fields.
Formality can also add server-side event handlers to form inputs:
import com.hacklanta.formality.Formality._
import com.hacklanta.formality.Html5Validations._
val nameField = field[String](".name") ? notEmpty
val phoneNumberField = field[String](".phone-number")
val ageField =
field[Int](".age") ?
inRange(15, 120) ->
on("change", { incoming: Int =>
if (incoming < 15) {
Run("$('#terms-and-conditions').attr('disabled', 'disabled')")
}
})
val termsField =
checkboxField("#terms-and-conditions") ? { incoming: Boolean =>
if (incoming) {
Empty
} else {
Full("You must agree to the terms and conditions.")
}
}
val registrationForm =
form withFields(
nameField,
phoneNumberField,
ageField,
termsField
) onSuccess {
// same as above
}-> on(<event>, <handler) is the syntax used to add an event handler to
a field. The event is whatever the event name will be on the client, as a
String, and the handler takes in the deserialized incoming value and
does something with it. It is expected to return a JsCmd, though keep
in mind that there is an implicit conversion from Unit to JsCmd
when necessary. Above, on change, we disable the terms and conditions
checkbox to ensure the user cannot select it if they are below
15*.
* - Obviously we could do this on the client as well, but this is merely an example :) ↩
A complicating factor is when your form includes uploaded files.
They will work perfectly if your form is not ajaxified, but submitting files as part of an ajax upload takes a little more effort. A classic approach is insert an iframe and submit to that, thus preventing your page from reloading.
This can be implemented clientside with the inclusion of a script along the lines of: (Adapted from this example)
$(function() {
function submitFormToIframe($form, target) {
$form
.attr('target', target)
.removeAttr('onsubmit')
.removeAttr('action')
.removeAttr('onclick')
.attr('action', '/ajax')
.attr('method', 'post')
.attr('enctype', 'multipart/form-data' )
.attr('encoding', 'multipart/form-data')
.find('input:submit,button[type=submit]')
.end()
.append($('<input type="hidden" name="' +
$form.find('input:submit').attr('name') +
'" value="_" />'))
.after(
// do not use attr() to set name. IE7 will hate this: http://stackoverflow.com/questions/2105815/weird-behaviour-of-iframe-name-attribute-set-by-jquery-in-ie
$('<iframe id="' + target + '" name="' + target + '" />')
.addClass('form-target')
.css('display','none')
);
}
submitFormToIframe($('form:has(input[type=file])'), 'fileUploadExampleForm');
});You may also wish to treat your uploaded files as optional. By default, a fileUploadField will fail validation if not provided. You can make the field(s) optional through a conversion into Option:
fieldGroup
.withFields(
fileUploadField("#anInputOfTypeFile")
)
.withBoxedConverter { optional: Box[FileParamHolder] =>
optional match {
case Full(fph) => Full(Some(fph))
case _ => Full(None)
}
}In case you have an aversion to using operators, the ? operator that
adds a validation to a field is originally named validatingWith, so
you can use that instead. Additionally, the -> operator that adds
an event handler is originally named handlingEvent.
Formality's default behavior is to send down deserialization and
validation errors using S.error. However, you may want to take
additional action when dealing with failures. Or, you may want to
ignore S.error in favor of your own error handling strategy. To
do this, you can add a failure handler to the form:
val registrationForm =
form withFields(
nameField,
phoneNumberField,
ageField,
termsField
) onSuccess {
// same as above
} onFailure { failures =>
failures.foreach {
case ParamFailure(message, _, _, validationErrors) =>
logger.error("Got " + message + " with validation errors: " + validationErrors)
case Failure(message, _, _) =>
logger.error("Got " + message)
case _ =>
}
}Note that the basic Failure message when validations fail simply says
" failed validations." However, in such cases, the failure is
a ParamFailure whose parameter is a list of Strings representing the
validation errors for that field.
Formality provides an abstraction above fields, called field groups. This lets you group fields into nested groups. By default, this looks like this:
val registrationForm =
form withFields(
fieldGroup.withFields(
nameField,
phoneNumberField,
ageField
),
termsField
) onSuccess {
case ((name :+: phoneNumber :+: age :+: HNil), terms) =>
// Assuming a case class User(name: String, age: Int, phoneNumber: String) this time.
if (terms) {
User(name, phoneNumber, age).save
}
User(name, age, phoneNumber, termsAndConditions).save
}But field groups also have a very important property: they can be converted
into a different type using its as function. In particular, a field group can
be a placeholder for a type that involves its combined fields. Let's redo the
above:
val registrationForm =
form withFields(
fieldGroup.withFields(
nameField,
phoneNumberField,
ageField
).as(User.apply _),
termsField
) onSuccess { (user, terms) =>
if (terms) {
user.save
}
}Our success handler now gets a full-on User object instead of the decomposed
fields, and we could use the User constructor directly.
as takes a function that takes the parameters from the group and produces a
type T. However, sometimes we want to be able to fail at the conversion step.
In those cases, we can use withConverter instead, which allows us to return a
Box[T], where a non-Full will cause a failed form submission:
val registrationForm =
form withFields(
fieldGroup.withFields(
nameField,
phoneNumberField,
ageField
).withConverter(User.createUnique _),
termsField
) onSuccess { (user, terms) =>
if (terms) {
user.save
}
}Above, createUnique can be considered as a version of User that creates the
new User object and returns a Full unless, say, the name is not unique. In that case it returns a Failure.
Note that failures at the group conversion level don't trigger S.error, since
there's no concrete field to associate the failure with. You can do your own
handling of the failure in the onFailure handler.
Field groups can also use a converter that takes the boxed values of the fields that it is made up of. This can be used, for example, to make choices between two fields that supply the same data. Let's take as an example an upload form that accepts a document in PDF format or a pasted text file:
val fileNameField = field[String](".file-name")
val pastedTextField = field[String](".pasted-text")
val uploadedFileField = fileUploadField(".pasted-text")
val uploadForm =
form withFields(
fileNameField,
fieldGroup.withFields(
pastedTextField,
uploadedFileField
).withBoxedConverter { (text: Box[String], file: Box[FileParamHolder]) =>
text.map(_.getBytes("UTF-8")) or file.data
}
).onSuccess { (fileName: String, fileData: Array[Data]))
DbFile.create(fileName, fileData)
}Above, we have a form with a field for the file's name, and then a group that
encloses the pasted text and the file upload. The converter receives both as
boxed values, which will be Empty if the user didn't specify anything for the
fields in question. The converter then uses the pasted text if it was specified,
or if not chooses the file data. The success handler then only sees two parameters:
the files name, and the final data array that represents its contents, which we've
resolved in the field group converter.
You can also add a scope to a field group. This is a CSS selector that ensures the fields in the field group are bound only if they're found within elements that match that selector:
val registrationForm =
form withFields(
fieldGroup(".user").withFields(
nameField,
phoneNumberField,
ageField
).withConverter(User.createUnique _),
termsField
) onSuccess ...With the above code, the markup that we introduced at the beginning would no longer successfully bind the user part of the registration form. Instead, we would need something like this:
<form data-lift="Registration.form">
<fieldset class="user">
<legend>User Information</legend>
<input class="name">
<input class="phone-number" placeholder="(XXX) XXX-XXXX">
<input class="age" type="number">
</fieldset>
<label for="terms-and-conditions>
<input type="checkbox" id="terms-and-conditions">
I agree to the <a href="/terms">Terms and Conditions</a>
</label>
</form>lift-formality is provided under the terms of the MIT License. No warranties
are made, express or implied. See the LICENSE file in this same directory.
lift-formality is copyright Hacklanta, and was
originally conceived and written by Antonio Salazar
Cardozo.
You can find our writings on the Hacklanta blog.