As the web application I’m currently building will have a mobile app, a REST Interface is a nice clean way for the mobile app to connect, retrieve and update information from the website.
fortunately Liftweb makes it very easy to do this, all you need to do is extend your class with the RestHelper Trait and let liftweb know about it in your Boot.scala

Lets say we want to get a list of all books in the system when we access http://(server)/api/books/all

First we need to tell Lift we have a class that responds to requests in Boot.scala:

LiftRules.dispatch.append(BookRestApi)

then the class itself: BookRestApi.scala:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

object BookRestApi extends RestHelper  {
  serve {
    // list of books
    case "api" :: "books" :: "all" :: _ XmlGet _=>
      {
         <Books>
          {
            Book.findAll.map(book => book.toXml)
          }
         </Books>
      }
    case "api" :: "books" :: "all" :: _ JsonGet _=>
      {
        JsonWrapper("books", Book.findAll.map(book => book.toJS))
      }
  }
}

The RestHelper trait parses the Url and makes the relevant parts available for Scala’s pattern matching capabilities.

for the first case statement:

• the api :: books : all List will match if the url points to /api/books/all
• the XmlGet method will match if the client has indicated he can accept xml by setting an accept header or by ending the url with a .xml suffix

Scala’s inline XML capabilities make it very easy, to envelop the result in a <Books> element.

the second statement does the same but then when the client requests a json response.

For the Json part I used a JsonWrapper helper method because the inline code looked totally unreadable, this still isn’t very readable but at least it has a descriptive method name now

1
2
3

  def JsonWrapper(name : String, content : JValue) : JValue = {
    (name -> content)
  }

If you would call this method with the name “Books” and the content {“foo” : “bar” } it will output :

{"books" : 
  {"foo" : "bar"}
}

This shows both a positive and negative aspect to the Scala language, it makes for a very flexible and fast development, but loses a lot in readability, which makes maintenance more difficult.

Now if would want to get a single book when I specify the id of that book, I’d add the following:

1
2
3
4
5
6
7

case "api" :: "books" :: AsLong(id) :: _ XmlGet _=>
        {
          Book.findByKey(id) match {
            case Full(book) => {book.toXml}
            case (_) => NotFoundResponse("Book with id " + id + " not found\r\n")
          }
        }

This pattern will only match on /api/books/{id} and only if that Id can be converted to a Long, in which case it will try to look up a book with that id
if the book isn’t found (the Box returned from findByKey isn’t Full) it will give the text back

In the next article I’ll talk about PUT requests and authentication so we can add books through the rest interface

In this second article I want to focus on the persistence layer of Lift by taking you through the following use case:

As an admin I want to be able to add/edit news articles and choose whether or not they appear on the homepage

For this we need to store the articles in a database, A template and Snippet to show them and some way of managing them.
Lift has 2 built-in persistence frameworks, Mapper and Record, but also JPA is fully supported.
As Mapper has CRUD and User management I’ve chosen to go with that one.

Our News article will have a Title, an Author, the content and a boolean that allows it to be seen on the homepage

1
2
3
4
5
6
7
8
9

class News extends LongKeyedMapper[News]  {
  def getSingleton = News
 
  object title extends MappedString(this, 100)
  object author extends MappedString(this, 100)
  object content extends MappedTextarea(this, 4000)
  object showOnHomepage extends MappedBoolean(this)
}
object News extends News with LongKeyedMetaMapper[News]

* A class and a object with the same name are called companion’s in Scala and the relationship is that the object is a singleton instance of the class, and they have access to each others private methods.

by extending News with LongKeyedMapper[News] we are able to persist it to the database.

Now we will mix-in some traits to add some extra functionality, a Trait in Scala is like a Java interface but allows for partial implementation. Say we want to add a primary key field and two date fields to store created and updated values, all we need to do is add the triats: IdPk (for primary key) and CreatedUpdated to the class definition.

1

class News extends LongKeyedMapper[News] with IdPK with CreatedUpdated

this will add the MappedLong object id, and 2 MappedDate objects created and updated to the News class

To add CRUD functionality we just add the CRUDify trait, this one needs to be added to the object instead of the class so that one now looks like:

object News extends News with LongKeyedMetaMapper[News] with CRUDify[Long, News]

This will add the forms, validation and handling to the news object.

To hook this all up into Lift’s bootstrapping we have to add some lines to Boot.scala, which is the class that lift calls before anything else.
The following line will make sure Lift knows about our persistence class and creates the database tables if needed

Schemifier.schemify(true, Schemifier.infoF _, News)

Lift works with a Sitemap, any page you want Lift to serve needs to be added to the sitemap. so we need to add our CRUD pages there fortunately CRUDify has a convenient helper method for this.

val menu = Menu(Loc("HomePage", "index" :: Nil, "Home Page", Hidden)) ::: News.menus
LiftRules.setSiteMap(SiteMap(menu:_*))

This will create a Homepage menu item and adds the news crud pages to it.

If we want to create a news item through code we could just execute the following line:

News.create.title("A news Item").author("gertjan").content("Breaking news, an item has just been created").showOnHomePage(true).saveMe

Next the snippet that will display a number of news items on the homepage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

class Homepage {
 def news(in: NodeSeq) : NodeSeq = {
    val articles = News.findAll(By(News.showOnHomepage, true), OrderBy(News.createdAt, Descending), MaxRows[News](5))
 
    def bindArticles(template: NodeSeq): NodeSeq = {
      articles.flatMap {
                case (news) => bind("article", template, 
							"title" -> news.title, 
							"author" -> news.author, 
							"content" -> StringHelper.unescapeXml(news.content),
							"created" -> news.createdAt,
							"updated" -> news.updatedAt)
      }
   }
 
   Helpers.bind("news", in, "articles" -> bindArticles _)
  }
}

The first line will lookup 5 news items that have the showOnHomepage boolean set to true and order them on date created.
The method bindArticles method will create bindings for each item found. as Lift escapes all xml/html by default, we need to unescape it especially when we want rich content.
The last line, will bind the collection to <news:articles/>

Then all is left is the html template:

<lift:surround with="default" at="content">
    <div class="news">
    <lift:homepage.news>
	<news:articles>
          <h3><article:title /></h3>
          <h4><i>by:</i><article:author /> <i>created:</i><article:created /> <i>updated:</i><article:updated/></h4>
          <p><article:content /></p>
        </news:articles>
    </lift:homepage.news>
    </div>
</lift:surround>

Because the <news:articles> contains a collection, lift will loop over it and process the inner html with each item in the collection.

A thing about authorization, we want the CRUD pages (and probably some other pages) to be accessible only to logged in users, this can be handled in several ways.
1) The Menu class has a parameter that defines the visibility of it, this can be easily used to check if a user is logged in:

val adminLoc = Loc("AdminPage", "admin" :: Nil, "Admin Page", Test((u) => u = User.loggedin_?))

or override the specific menu methods that are defined in the CRUDify trait

override def editMenuLocParams = If(User.loggedIn_? _, RedirectResponse("/user_mgt/login")) :: super.editMenuLocParams

And there it is, with surprisingly little code, we now have the beginnings of a content management system.

I’ve been playing around with Lift for a while now, and I’d like to share some of my experiences with you all, although i’m inexperienced with both Scala and lift, I’m able to get things done pretty quickly in comparison with doing it in Java. which says a lot about both the language and the framework.

I’m building a webapplication that holds my collection of books, so the first use case I want to present to you and go through the implementation is the following:

As a user I want to be able to quickly import a list of isbn numbers

Lift moves away from your typical model view controller framework, but focuses on keeping your template’s designer friendly without any logic or code in there. Besides that the main focus areas are security and scalability, read the documentation on the lift website if you want to know more about this.

Taking the use case, we need to build a form with a textarea that allows us to copy/paste a list of isbn numbers in and add those to the database. Later use cases will then look up title/author information from for instance amazon, google books, or isbndb

Our html template which contains the form looks like this:

<lift:surround with="default" at="content">
  <h3>Import Isbnn rumbers</h3>
  <lift:ImportIsbn.bulk form="POST">
    <entry:text /><br/>
    <entry:submit />
  </lift:ImportIsbn.bulk>
 </lift:surround>

• The <lift:surround> tells lift to ‘surround’ this template with the default.html template which contains the header, footer and navigation for our website, inserting this template at the <lift:content /> tag in that template.
• The <lift:ImportIsbn.bulk> tells Lift to look for a class named ImportIsbn with a method bulk with the inner html as a parameter for us to manipulate
• The <entry:*>’s we will bind to form elements in the snippet code later on

Something more about templates:

• if a snippet takes long to complete, surround it with <lift:lazy-load> this will show an ajax loading gif while the snippet is executed.
• if you have a lot of snippets that take a while, surround them with <lift:parallel> to execute them in different threads

now to create our form:

1
2
3
4
5
6
7
8

class ImportIsbn
  var isbnnrs = ""
  def bulk(in : NodeSeq) : NodeSeq = {
        bind("entry", in,
          "text" -> SHtml.textarea(isbnnrs, isbnnrs = _),
          "submit" -> (SHtml.hidden(processIsbnNrs) ++ <input type="submit" value="Add" />))
  }
}

The bind method is a helper method that looks in the html (NodeSeq) passed on for tags marked with the “entry” prefix and binds them to html elements, in good functional programming the SHtml.* methods take a function as a parameter, for the textarea, we assign the value of the textarea to it, the hidden one calls the method processIsbnNrs
we could also have used

SHtml.submit("Add", processIsbnNrs)

but the above allows us to quickly make a ajax form out of it.
To do this we simple put a Shtml.ajaxForm around the bind.

 SHtml.ajaxForm(
        bind(.... etc )
      )

This will create the javascript methods to submit this form without doing a normal post

Due to Scala’s inline xml capabilities a snippet can also return xhtml directly, lift only works with xhtml (and if you use the 2.2-SNAPSHOT even html5)

  def mySnippet(in: NodeSeq) : NodeSeq = {
  <p>This is returned from my snippet</p>
  }

After submitting the method processIsbnNrs is called which looks like this:

1
2
3
4
5
6
7
8
9
10
11
12

      def processIsbnNrs() = {
        isbnnrs split " " map {addBook _}
      }
 
      def addBook(nr : String) {
        Book.find(By(Book.isbn, nr)) match {
          case (Full(book)) => alreadyInDb += " " + nr
          case (_) => Book.create.isbn(nr).saveMe
        }
        msg = "Skipped: " + alreadyInDb
        S.warning(Text(msg))
      }

As the isbnnrs var is bound to the textarea it will now contains the list of isbnnrs, the first line will split it on a space and then calling the addBook method for each entry

The addBook method will try to find the book in the Database, (the following post will look at Mapper the persistence layer in Lift). if it doesn’t it will add it to the database.
and that is all to it, I left out validation and initializing of the var’s here.  but the code is public at github if you want to take closer look.

A close observer will see the use of the method Full() in there, Scala has the Option class with which can be an instance of Some or None, which is designed to make continuous null pointer exception checking unnecessary.
Lift takes this one step further by having a Box class, which can be Full, Empty or Failure.  This in combination with Scala’s match/case functionality is very powerful and creates very readable and thus maintable code.
In our case if a Book is found (the box is full) do nothing, if not save a book with that isbn nr to the database.

See the Box article on Liftweb for more information about this.