diff --git a/docs/getting-started-tutorial/6-adding-usernames.adoc b/docs/getting-started-tutorial/6-adding-usernames.adoc index 7fdbe07f4e..b52dfdf9d5 100644 --- a/docs/getting-started-tutorial/6-adding-usernames.adoc +++ b/docs/getting-started-tutorial/6-adding-usernames.adoc @@ -121,7 +121,10 @@ there's a possibility of a value not being set.]: def sendMessage = { var message: Box[ChatMessage] = Empty - "#new-message" #> SHtml.text(message, { body: String => message = Full(ChatMessage(username.is, body)) }) & + "#new-message" #> SHtml.text( + message, + { messageBody: String => message = Full(ChatMessage(username.get, messageBody)) } // <1> + ) & "type=submit" #> SHtml.submitButton(() => { for (body <- message) { messageEntries ::= message @@ -130,10 +133,30 @@ there's a possibility of a value not being set.]: } ... ``` - -We use a `for` comprehension to unpack the value of `message`. The body of that -comprehension won't run unless `message` is a `Full` box containing a -`ChatMessage` sent by the client. +<1> Notably, `.get` is how you fetch the current value of a `SessionVar`. Don't + confuse it with the `.get` on `Option`, which is very dangerous! If you + prefer to use a method that is less easily confused with `Option`'s `.get` + (as many Lift developers and committers do), you can use `.is` instead, which + does the same thing. + +Let's break this one down to its composite parts. First, we update the handler +for the `#new-message` text field. Before, the handler function was `message = _`; +when `message` was a `String`, we could simply assign the message the user sent +directly to it, and we were good to go. However, `message` is now a `ChatMessage`--- +it has to carry not only the message body that the user typed, but also their +username. To do that, we write a complete handler function that takes in the +body that the user submitted with the form and creates a `ChatMessage` with +that body and the current user's username. + +Note also that we wrap the newly-created `ChatMessage` in a `Full`. Before, we +used an empty `String` as our starting value for the message. However, we can't +do that anymore here. Our only option would be to use `null`, but `null` is very +dangerous and, as a rule, we avoid using it in Scala. Instead, we use an `Empty` +`Box`, and, when we receive a message body, we create a `Full` `Box` with the +newly posted `ChatMessage`. As a result of the wrapping `Box`, we have to update +the submission handler. We use a `for` comprehension to unpack the value of +`message`. The body of that comprehension won't run unless `message` is `Full`, +so we can't try to insert an empty message into the message list. Now that we have a reasonably nice chat system with actual usernames, it's time to look at the underlying issue of *consistency*. If two users posted a chat