Previous: Appendix A Up: Part III Next: Appendix C

B Message Handling

When we talk about message handling in Lift, we’re talking about how you provide feedback to the users of your application. While there are already a lot of mechanisms for displaying data to the user via snippets, views, etc, properly binding and setting up HTML-level elements can get complicated, especially when you’re dealing with callback functions or error handling. Lift provides an alternate mechanism for displaying messages to users that is easy to use and allows flexibility in display on the client side.

B.1 Sending Messages

Messages for non-Comet requests are handled via the S object (yes, even Ajax is handled automatically); specifically, the error, notice and warning methods allow you to send a String or a NodeSeq back to the user for display, with or without an association with a particular element id. The error method also provides an overload that takes a List[FieldError], the type returned from Mapper field validation (section 8.2.3↑). The messages that you send are held by a RequestVar (section 3.11↑) in the S object, so you can send messages from anywhere in your stateful request/response lifecycle without breaking the flow of your code. Listing B.1↓ shows how you could use messages in form processing to send feedback on missing fields.

Using messages in form processing

object data extends RequestVar[String]("")

def addNote (xhtml : NodeSeq) : NodeSeq = {
  def doAdd () = {
    //validate
    if (data.is == "") { 
      S.error("noteField", "You need to provide a note")
    } else {
      Note.create.note(data).save
      S.notice("Note added")
      redirectTo("/viewNotes")
    }
  }
  bind("form", xhtml,
       "note" -> SHtml.text(data.is, data(_), "id" -> "noteField"),
       "add" -> SHtml.submit("Add", doAdd))
}

In this particular case we use two different messages. One is an error to be displayed when the form is re-shown; this error is associated with the “noteField” element. The second message is a simple notice to let the user know that the data was successfully saved.

For Comet↓ the only difference in sending messages is that the error, notice and warning methods are defined in the CometActor class, so you just use those directly and Lift handles the rest.

B.2 Displaying Messages

The display of messages is handled by two builtin snippets, <lift:Msgs/> and <lift:Msg/>. The Msgs snippet displays all messages not associated with a particular element Id. The messages are displayed as an unordered list, but Lift allows customization of the messages via XML that you embed within the snippet. For each of the three message types, you can specify a <lift:TYPE_msg> and <lift:TYPE_class> element that controls the message label and CSS class, respectively. The default label is simply the title-case type (Error, Notice, Warning). For example, listing B.2↓ shows how we could change the error and notice messages.

Custom message labels

<lift:Msgs>
  <lift:error_msg>Danger, Will Robinson! </lift:error_msg>
  <lift:error_class>redtext</lift:error_class>
  <lift:notice_msg>FYI: </lift:notice_msg>
</lift:Msgs>

The Msg snippet is used to display all messages associated with a particular Id by specifying the id attribute on the <lift:Msg/> element. With Msg, you don’t get a message label, so there’s no override mechanism for it. You do, however, have the ability to to change the message class on a per-type basis by setting the noticeClass, errorClass, or warningClass attributes on the <lfit:Msg/> element. Listing B.2↓ shows usage of Msg corresponding to our snippet in listing B.1↑.

Per-id messages

<lift:Stuff.addNote form="POST">
  <form:note /><lift:Msg id="noteField" errorClass="redtext" />
  <form:add />
</lift:Stuff.addNote>

Previous: Appendix A Up: Part III Next: Appendix C