Lift Cookbook

You want to install and run Lift on your computer.

The only prerequisite for installing and running Lift is to have Java 1.5 or later installed. Instructions for installing Java can be found at http://java.com/.

You can find out if you have Java from the shell or command prompt by asking for the version you have installed:

Once you have Java, the following instructions will download, build and start a basic Lift application.

Lift isn’t installed in the usual sense of "installing software". Instead you use standard build tools, such as SBT or Maven, to assemble your application with the Lift framework. In this recipe we downloaded a ZIP file containing four fairly minimal Lift applications, and then started one of them via the build tool.

The Simple Build Tool documentation is at http://www.scala-sbt.org.

Tutorials for Lift can be found in Simply Lift at http://simply.liftweb.net/ and in Lift in Action (Tim Perrett, 2011, Manning Publications Co).

You want want to create a Lift web project from scratch without using the ZIP files provided on the official Lift website.

You will need to configure SBT and the Lift project yourself. Luckily, only five small files are needed.

First, create an SBT plugin file at project/plugins.sbt (all file names are given relative to the project root directory):

This file tells SBT that you will be using the xsbt-web-plugin and chooses the correct version based upon your version of SBT.

Next, create an SBT build file, build.sbt:

Feel free to change the various versions, though be aware that certain versions of Lift are only built for certain versions of Scala.

Now that you have the basics of an SBT project, you can launch the sbt console. It should load all the necessary dependencies, including the proper Scala version, and bring you to a prompt.

Next, create the following file at src/main/webapp/WEB-INF/web.xml:

The web.xml file tells web containers, such as Jetty as configured by xsbt-web-plugin, to pass all requests on to Lift.

Next, create a sample index.html file at src/main/webapp/index.html for our Lift app to load. For example:

Finally, setup the basic Lift boot settings by creating a Boot.scala file at src/main/scala/bootstrap/Boot.scala. The following contents will be sufficient:

Congratulations, you now have a working Lift project!

You can verify that you have a working Lift project by launching the Jetty web container from the sbt console with the container:start command. First the Boot.scala file should be compiled and then you should be notified that Jetty has launched and is listening at http://localhost:8080. You should be able to go to the address in your web browser and see the rendered index.html file you created earlier.

As shown above, creating a Lift project from scratch is a relatively simple process. However, it can be a tricky one for newcomers, especially if you are not used to the JVM ecosystem and its conventions for web containers. If you run into problems, make sure the files are in the correct locations and that their contents were not mistakenly modified. If all else fails, refer to the sample project below or ask for help on the Lift mailing list.

Lift projects using SBT or similar build tools follow a standard project layout, where Scala source code is in src/main/scala and web resources are in src/main/webapp. Your Scala files must be placed either directly at src/main/scala or in nested directories matching the organization and name you defined in build.sbt, in our case giving us src/main/scala/org/yourorganization/liftfromscratch/. Test files match the directory structure but are placed in src/test/ instead of src/main/. Likewise, the web.xml file must be placed in src/main/webapp/WEB-INF/ for it to be properly detected.

Given these conventions, you should have a directly structure looking quite, if not exactly, like this:

There is a sample project created using this method at: https://github.com/bubblefoundry/lift-from-scratch.

You want to develop your Lift application using your favourite text editor, hitting reload in your browser to see changes.

Run SBT while you are editing, and ask it to detect and compile changes to Scala files. To do that, start sbt and enter the following to the SBT prompt:

When you save a source file in your editor, SBT will detect this change, compile the file, and reload the web container.

An SBT command prefixed with ~ makes that command run when files change. The first semicolon introduces a sequence of commands, where if the first command succeeds, the second will run. The second semicolon means the reload command will run if the start command ran OK. The start command will recompile any Scala source files that have changed.

When you run SBT in this way, you’ll notice the following output:

And indeed, if you do press enter in the SBT window you’ll exit this triggered execution mode and SBT will no longer be looking for file changes. However, while SBT is watching for changes, the output will indicate when this happens with something that looks a little like this:

Edits to HTML files don’t trigger the SBT compile and reload commands. This is because SBT’s default behaviour is to look for Scala and Java source file changes, and also changes to files in src/main/resources/. This works out just fine, because Jetty will use your modified HTML file when you reload the browser page.

Restarting the web container each time you edit a Scala file isn’t ideal. You can reduce the need for restarts by integrating JRebel into your development environment, as described in [jrebel].

However, if you are making a serious number of edits, you may prefer to issue a container:stop command until you’re ready to run you application again with container:start. This will prevent SBT compiling and restarting your application over and over. The SBT console has a command history, and using the up and down keyboard arrows allows you to navigate to previous commands and run them by pressing the return key. That takes some of the tedium out of these long commands.

One error you may run into is:

The permanent generation is a Java virtual machine concept. It’s the area of memory used for storing classes (amongst other things). It’s a fixed size and once it is full this PermGen error appears. As you might imagine, continually restarting a container causes many classes to be loaded and unloaded, but the process is not perfect, effectively leaking memory. The best you can do is stop and then restart SBT. If you’re seeing this error often, check the setting for -XX:MaxPermSize inside the sbt (or sbt.bat) script, and if you can, double it.

There’s more about triggered execution at http://www.scala-sbt.org/release/docs/Detailed-Topics/Triggered-Execution.

Reference for the core SBT command line: http://www.scala-sbt.org/release/docs/Detailed-Topics/Command-Line-Reference.

Command reference for the web plugin for SBT is at: https://github.com/JamesEarlDouglas/xsbt-web-plugin/wiki.

You want to avoid application restarts when you change a Scala source file by using JRebel.

There are three steps required: install JRebel once; each year request the free Scala license; and configure SBT to use JRebel.

First, visit the https://my.jrebel.com/plans and request the free Scala license.

Second, download the "Generic ZIP Archive" version of JRebel, unzip it to where you like. For this recipe I’ve chosen to use /opt/zt/jrebel/.

When your have received your account confirmation email from JRebel, you can copy your "authentication token" from the "Active" area of ZeroTurnaround’s site. To apply the token to your local install, run the JRebel configuration script:

For Windows navigate to and launch bin\jrebel-config.cmd.

In the "Activation" setting select "I want to use myJRebel" and then in the "License" section paste in your activation token. Click the "Activate" button, and once you see the license status change to "You have a valid myJRebel token" click "Finish".

Finally, configure SBT by modifying the sbt script to enable JRebel. This means setting the -javaagent and -noverify flags for Java, and enabling the JRebel Lift plugin.

For Mac and Linux, the script that’s included with the Lift downloads would become:

For Windows, modify sbt.bat to be:

There’s nothing else to do to use JRebel. When you start SBT you’ll see a large banner starting something like this:

With JRebel installed, you can now container:start your application, modify and compile a Scala file and reload a page in your application. You’ll see a notice that the class has been reloaded:

That change is live, without having to restart the container.

JRebel is very likely to speed up your development. It updates code in a running Java virtual machine, without having to stop and restart it. The effect is that, on the whole, you can compile a class, then hit reload in your browser to see the change in your Lift application.

Even with JRebel you will need to restart your applications from time to time, but JRebel usually reduces the number of restarts. For example, Boot.scala is run when your application starts, so if you modify something in your Boot.scala you’ll need to start and start your application. JRebel can’t help with that.

But there are also other situations that JRebel cannot help with, such as when a superclass changes. Generally, JRebel will emit a warning about this in the console window. If that happens, stop and start your application.

The -Drebel.lift_plugin=true setting adds Lift-specific functionality to JRebel. Specifically, it allows JRebel to reload changes to LiftScreen, Wizard and RestHelper. This means you can change fields or screens, and change REST serve code.

You’ll find details about how JRebel works in the FAQ at: http://zeroturnaround.com/software/jrebel/resources/faq/.

The Lift support was announced in a blog post in 2012 at http://zeroturnaround.com/jrebel/lift-support-in-jrebel/, where you’ll find more about the capabilities of the plugin.

You want to develop your Lift application using the Eclipse IDE, hitting reload in your browser to see changes.

Use the "Scala IDE for Eclipse" plugin to Eclipse, and the sbteclipse plugin for SBT. This will give Eclipse the ability to understand Scala, and SBT the ability to create project files which Eclipse can load.

The instructions for the Eclipse plugin are given at http://scala-ide.org. There are a number of options to be aware of when picking an update site to use: there a different sites for Scala 2.9 and 2.10, and for different versions of Eclipse. Start with the stable version of the plugin rather than a nightly or milestone version. This will give you an Eclipse perspective that knows about Scala.

Once the Eclipse plugin is installed and restarted you need to create the project files to allow Eclipse to load your Lift project. Install "sbteclipse" by adding the following to projects/plugins.sbt in your Lift project:

You can then create Eclipse project files (.project and .classpath) by entering the following to the SBT prompt:

Open the project in Eclipse by navigating to "File > Import…" and selecting "General > Existing Projects into Workspace". Browse to, and pick, your Lift project.You are now set up to develop your application in Eclipse.

To see live changes as you edit and save your work, run SBT in a separate terminal window. That is, start sbt from a terminal window outside of Eclipse and enter the following:

This behaviour of this command is described in [texteditor], but if you’re using JRebel (see [jrebel]) then you just need to run container:start by itself.

You can then edit in Eclipse, save to compile, and in your web browser hit reload to see the changes.

One of the great benefits of an IDE is the ability to navigate source, by cmd+click (Mac) or F3 (PC). You can ask the SBT eclipse command to download the Lift source and Scaladoc, allowing you to click through to the Lift source from methods and classes, which is a useful way to discover more about Lift.

To achieve this in a project, run eclipse with-source=true in SBT, but if you want this to be the default behaviour, add the following to your build.sbt file:

If you find yourself using the plugin frequently, you may wish to declare it in your global SBT configuration files so it applies to all projects. To do that, create a ~/.sbt/plugins/plugins.sbt file containing:

Note the blank line between the resolvers and the addSbtPlugin. In .sbt files, a blank line is required between statements.

Finally, set any global configurations (such as withSource) in ~/.sbt/global.sbt.

There are other useful settings for sbteclipse, described at https://github.com/typesafehub/sbteclipse/wiki. You’ll also find the latest version number for the plugin on that site.

The SBT ~/.sbt/ structure is described in the guide to using plugins at http://www.scala-sbt.org/release/docs/Getting-Started/Using-Plugins and in the wiki page for global configuration at http://www.scala-sbt.org/release/docs/Detailed-Topics/Global-Settings.

You want to use the Intellij IDEA development environment when writing your Lift application.

You need the Scala plugin for IntelliJ, and an SBT plugin to generate the IDEA project files.

The IntelliJ plugin you’ll need to install once, and these instructions are for IntelliJ IDEA 12. The details may vary between releases of the IDE, but the basic idea is to find the JetBrains Scala plugin, and download and install it.

From the "Welcome to Intellij IDEA" screen, select "Configure" and then "Plugins". Select "Browse repositories…". In the search box, top right, type "Scala". You’ll find on the left a number of matches: select "Scala". On the right, you’ll see confirmation that this is the "Plugin for Scala language support" and the vendor is JetBrains Inc. Select the "Download and Install" icon from the top of the window, or right click to download and install. "Close" the dialog, and OK out of the plugins window. You’ll be promoted to restart IntelliJ IDEA.

With the IDE configured, you now need to add the SBT plugin inside your Lift project by adding the following to the file projects/plugins.sbt:

Start SBT and at the SBT prompt create the IDEA project files by typing:

This will generate the .idea and .iml files that IntelliJ uses. Inside IntelliJ you can open the project from the "File" menu, picking "Open…" and then navigating to your project and selecting the directory.

To see live changes as you edit and save your work, run SBT in a separate terminal window. That is, start sbt from a terminal window outside of IntelliJ and enter the following:

This behaviour of this command is described in [texteditor], but if you’re using JRebel (see [jrebel]) then you just need to run container:start by itself.

Each time you compile or make the project, the container will pick up the changes, and you can see them by re-loading your browser window.

By default the gen-idea command will fetch source for dependent libraries. That means out-of-the-box you can click though to Lift source code to explore it and learn more about the framework.

If you want to try the latest snapshot version of the plugin, you’ll need to include the snapshot repository in your plugin.sbt file:

Setting up the SBT IDEA plugin globally, for all SBT projects, is the same pattern as described for Eclipse in [eclipse].

The sbt-idea plugin at https://github.com/mpeltonen/sbt-idea doesn’t have a configuration guide yet. One way to discover the features is to browse the release notes in the notes folder of that project.

JetBrains have a blog for the Scala plugin with feature news and tips: http://blog.jetbrains.com/scala/.

You’re developing using the default lift_proto.db H2 database, and you would like use a tool to look at the tables.

Use the web interface included as part of H2. Here are the steps:

The default Lift projects that include a database, such as lift_basic, use the H2 relational database as it can be included as an SBT dependency and requires no external installation or configuration. It’s a fine product, although production deployments typically use standalone databases, such as PostgreSQL or MySQL.

Even if you’re deploying to a non-H2 database it may be useful to keep H2 around because it has an in-memory mode, which is great for unit tests. This means you can create a database in-memory, and throw it away when your unit tests ends.

If you don’t like the web interface, the connection settings described in this recipe should give you the information you need to configure other SQL tools.

The properties of H2 are described at http://www.h2database.com.

If you’re using the console frequently, consider making it accessible from your Lift application in development node. This is described by Diego Medina in a blog post at https://fmpwizard.telegr.am/blog/lift-and-h2.

The example Lift project for [Squeryl] has the H2 console enabled. The source is: https://github.com/LiftCookbook/cookbook_squeryl.

You want to use the latest ("snapshot") build of Lift.

You need to make two changes to your build.sbt file. First, reference the snapshot repository:

Second, change the liftVersion in your build to be the latest version. For this example, let’s use the 2.6-SNAPSHOT version of Lift:

Restarting SBT (or issuing a reload command) will trigger a download of the latest build.

Production releases of Lift (e.g., "2.4", "2.5"), as well as milestone releases (e.g., "2.5-M3") and release candidates (e.g., "2.5-RC1") are published into a releases repository. When SBT downloads them, they are downloaded once.

Snapshot releases are different: they are the result of an automated build, and change often. You can force SBT to resolve the latest versions by running the command clean and then update.

To learn the detail of SNAPSHOT versions, dig into the Maven Complete Reference at http://www.sonatype.com/books/mvnref-book/reference/pom-relationships-sect-pom-syntax.html.

A new Scala version has just been released and you want to immediately use it in your Lift project.

You may find that the latest snapshot of Lift is built using the latest Scala version. Failing that, and assuming you cannot wait for a build, you may still be in luck. Providing that the Scala version is binary compatible with the latest version used by Lift, you can change your build file to force the Scala version.

For example, assuming your build.sbt file is set up to use Lift 2.5 with Scala 2.9.1:

Let’s assume that you now want to use Scala 2.9.3 but Lift 2.5 was only built against Scala 2.9.1. Replace %% with % for the net.liftweb resources and explicitly include the Scala version that Lift was built against for each Lift component:

What we’ve done here is change the scalaVersion to the new version we want to use, but explicitly specified we want the 2.9.1 Scala version for Lift. This works because the two different Scala versions are binary compatible.

Dependencies have a particular naming convention. For example, the lift-webkit library for Lift 2.5-RC6 is called lift-webkit_2.9.1-2.5-RC6.jar. Normally in build.sbt we simply refer to "net.liftweb" %% "lift-webkit" and SBT turns that into the name of a file that can be downloaded.

However, in this recipe we have forced SBT to explicitly fetch the 2.9.1 version of the Lift resources rather than allow it to compute the URL to the Lift components. This is the difference between using %% and % in a dependency: with %% you do not specify the Scala version as SBT will append the scalaVersion number automatically; with % this automatic change is not made, so we have to manually specify more details for the name of the library.

Please note this only works for minor releases of Scala: major releases break compatibility. For example Scala 2.9.1 is compatible with Scala 2.9.0, but not 2.10.

Binary compatibly in Scala is discussed on the Scala user mailing list at http://article.gmane.org/gmane.comp.lang.scala.user/39290.

The SBT behaviour is described at: http://www.scala-sbt.org/release/docs/Getting-Started/Library-Dependencies.

[snapshot] describes how to use a snapshot version of Lift.

You want to explore or debug CSS selectors interactively.

You can use the Scala REPL to run your CSS selectors.

Here’s an example were we test out a CSS selector which adds an href attribute to a link. Start from within SBT and use the console command to get into the REPL:

The Helpers._ import brings in the CSS Selector functionality, which we then exercise by creating a selector, f, calling it with a very simple template, in, and observing the result, res0.

CSS selector transforms are one of the distinguishing features of Lift. They succinctly describe a node in your template (left-hand side) and give a replacement (operation, the right-hand side). They do take a little while to get use to, so being able to test them at the Scala REPL is useful.

It may help to know that prior to CSS selectors Lift snippets were typically defined in terms of a function that took a NodeSeq and returned a NodeSeq, often via a method called bind. Lift would take your template, which would be the input NodeSeq, apply the function, and returns a new NodeSeq. You won’t see that usage so often any more, but the principle is the same.

The CSS selector functionality in Lift gives you a CssSel function which is NodeSeq => NodeSeq. We exploit this in the above example by constructing an input NodeSeq (called in), then creating a CSS function (called f). Because we know that CssSel is defined as a NodeSeq => NodeSeq the natural way to execute the selector is to supply the in as a parameter, and this gives us the answer, res0.

If you use an IDE that supports a worksheet, which both Eclipse and IntelliJ IDEA do, then you can also run transformations in a worksheet.

The syntax for selectors is best described in Simply Lift at http://simply.liftweb.net/.

See [eclipse] and [idea] for how to work with Eclipse and Intellij IDEA.

You want your CSS selector binding to apply to the results of earlier binding expressions.

Use andThen rather than & to compose your selector expressions.

For example, suppose we want to replace <div id="foo"/> with <div id="bar">bar content</div> but for some reason we needed to generate the bar div as a separate step in the selector expression:

When using & think of the CSS selectors as always applying to the original template, no matter what other expressions you are combining. This is because & is aggregating the selectors together before applying them. In contrast, andThen is a method of all Scala functions that composes two functions together, with the first being called before the second.

Compare the example above if we change the andThen to &:

The second expression will not match as it is applied to the original input of <div id="foo"/> — the selector of #bar won’t match on id=foo, and so adds nothing to the results of render.

The Lift Wiki page for CSS Selectors also describes this use of andThen: https://www.assembla.com/spaces/liftweb/wiki/Binding_via_CSS_Selectors.

You want to set the content of an HTML meta tag from a snippet.

Use the @ CSS binding name selector. For example, given:

The following snippet code will update the value of the contents attribute:

The @ selector selects all elements with the given name. It’s useful in this case to change <meta name="keyword"> tag, but you may also see it used with elsewhere. For example, in an HTML form you can select input fields such as <input name="address"> with "@address".

The [content] part is an example of a replacement rule that can follow a selector. That’s to say, it’s not specific to the @ selector and can be used with other selectors. In this example it replaces the value of the attribute called "content". If the meta tag had no "content" attribute, it would be added.

There are two other replacement rules useful for manipulating attributes:

Examples of these would be…

…and…

The syntax for selectors is best described in Simply Lift at http://simply.liftweb.net/.

See [TestingAndDebuggingSelectors] for how to run selectors from the REPL.

You want to set the <title> of the page from a Lift snippet.

Select the content of the title element and replace it with the text you want:

Assuming you have a <title> tag in your template, the above will result in:

This example uses a element selector, which picks out tags in the HTML template, and replaces the content. Notice that we are using "title " to select the content of the title tag. If we had left off the "" the entire title tag would have been replaced with text.

As an alternative, it is also possible to set the page title from the contents of SiteMap, meaning the title used will be the title you’ve assigned to the page in the site map. To do that, make use of Menu.title in your template directly:

The Menu.title code appends to any existing text in the title. This means the following will have the phrase "Site Title - " in the title followed by the page title:

If you need more control, you can of course bind on <title> using a regular snippet. This example uses a custom snippet to put the site title after the page title:

Notice that our snippet is returning another snippet, <lift:Menu.title/>. This is a perfectly normal thing to do in Lift, and snippet invocations returned from snippets will be processed by Lift as normal.

[SnippetNotFound] describes the different ways to reference a snippet, such as data-lift and <lift: ... />.

At https://www.assembla.com/spaces/liftweb/wiki/SiteMap there’s more about Site Map and the Menu snippets.

You want to make use of Internet Explorer HTML conditional comments in your templates.

Put the markup in a snippet and include the snippet in your page or template.

For example, suppose we want to include the HTML5 Shiv (a.k.a. HTML5 Shim) JavaScript so we can use HTML5 elements with legacy IE browsers. To do that our snippet would be:

We would then reference the snippet in the <head> of a page, perhaps even in all pages via templates-hidden/default.html:

The HTML5 parser used by Lift does not carry comments from the source through to the rendered page. If you just tried to paste the html5shim markup into your template you’d find it missing from the rendered page.

We deal with this by generating unparsed markup from a snippet. If you’re looking at Unparsed and worried, your instincts are correct. Normally Lift would cause the markup to be escaped, but in this case we really do want unparsed XML content (the comment tag) included in the output.

If you find you’re using IE conditional comments frequently, you may want to create a more general version of the snippet. For example:

It would be used like this…

…and produces output like this:

Notice that the condition test defaults to "IE", but first tries to look for an attribute called "cond". This allows you to write:

The + symbol is the the URL encoding for a space, resulting in:

The IEOnly example is derived from a posting on the mailing list from Antonio Salazar Cardozo: http://bit.ly/lift-ieonly.

The html5shim project can be found at: http://code.google.com/p/html5shim/.

You want a snippet to return the original markup associated with the snippet invocation.

Use the PassThru transform.

Suppose you have a snippet which performs a transforms when some condition is met, but if the condition is not met, you want the snippet return the original markup.

Starting with the original markup…

…we could leave it alone or change it with this snippet:

PassThru is an identity function of type NodeSeq => NodeSeq. It returns the input it is given:

A related example is ClearNodes, defined as:

The pattern of converting one NodeSeq to another is simple, but also powerful enough to get you out of most situations as you can always arbitrarily re-write the NodeSeq.

You’re using Lift with the HTML 5 parser and one of your snippets is rendering with a "Class Not Found" error. It even happens for <lift:HelloWorld.howdy />.

Switch to the designer-friendly snippet invocation mechanism. E.g.,

In this Cookbook we use the HTML 5 parser, which is set in Boot.scala:

The HTML5 parser and the traditional Lift XHTML parser have different behaviours. In particular the HTML5 parser converts elements and attribute names to lower case when looking up snippets. This means Lift would take <lift:HelloWorld.howdy /> and look for a class called "helloworld" rather than "HelloWorld", which would be the cause of the "Class Not Found Error".

Switching to the designer-friendly mechanism is the solution here, and you gain validating HTML as a bonus.

There are three popular ways of referencing a snippet:

The key differences between the XHTML and HTML5 parser are outlined on the mailing list at http://bit.ly/lift-parsers.

You’ve modified CSS or JavaScript in your application, but web browsers have cached your resources and are using the older versions. You’d like to avoid this browser caching.

Add the with-resource-id attribute to script or link tags:

The addition of this attribute will cause Lift to append a resource ID to your src (or href), and as this resource ID changes each time Lift starts, it defeats browser caching.

The resultant HTML might be:

The random value that is appended to the resource is computed when your Lift application boots. This means it should be stable between releases of your application.

If you need some other behaviour from with-resource-id you can assign a new function of type String => String to LiftRules.attachResourceId. The default implementation, shown above, takes the resource name, /myscript.js in the example, and returns the resource name with an id appended.

You can also wrap a number of tags inside a <lift:with-resource-id>...<lift:with-resource-id> block. However, avoid doing this in the <head> of your page as the HTML5 parser will move the tags to be outside of the head section.

Note that some proxies may choose not to cache resources with query parameters at all. If that impacts you, it’s possible to code a custom resource ID method to move the random resource ID out of the query parameter and into the path.

Here’s one approach to doing this. Rather than generate JavaScript and CSS links that look like /assets/style.css?F61973, we will generate /cache/F61973/assets/style.css. We then will need to tell Lift to take requests that look like this new format, and render the correct content for the request. The code for this is:

This would be initialised in Boot.scala…

…or you could just paste all the code into Boot.scala, if you prefer.

With the code in place, we can, for example, modify templates-hidden/default.html and add a resource ID class to jQuery:

At run-time this would be rendered in HTML as:

Most of the work for this is happening in the statelessRewrite, which is working at a low-level inside Lift. The two parts to it are:

Looking at the RewriteRequest first, this expects three arguments: the path, which we care about, and then the method (e.g., GetRequest, PutRequest, etc) and the HTTPRequest itself, neither of which concern us in this instance. In the path part we’re matching on patterns that start with "cache", followed by something (we don’t care what), and then the rest of the path, represented by the name file. In that situation, we rewrite to the original path, which is just the file with the suffix, effectively removing the /cache/F352555437877UHCNRW part. This is the content that Lift will serve.

The source for LiftRules shows the default implementation of attachResourceId: https://github.com/lift/framework/blob/master/web/webkit/src/main/scala/net/liftweb/http/LiftRules.scala.

Google’s Optimize caching notes are a good source of information about browser behaviour: https://developers.google.com/speed/docs/best-practices/caching.

You can learn more about URL re-writing at the Lift wiki: https://www.assembla.com/spaces/liftweb/wiki/URL_Rewriting.

You use a template for layout, but on one specific page you need to add something to the <head> section.

Use the head snippet so Lift knows to merge the contents with the <head> of your page. For example, suppose you have the following contents in templates-hidden/default.html:

Also suppose you have index.html on which you want to include red-titles.css to just change the style of just this page.

Do so by including the CSS in the part of the page that will get processed, and mark it with the head snippet:

Note that this index.html page is validated HTML 5, and will produce a result with the custom CSS inside the <head> tag, something like this:

If you find your tags not appearing the the <head> section, check that the HTML in your template and page is valid HTML 5.

You can also use <lift:head>...</lift:head> to wrap a number of expressions, and will see <head_merge>...</head_merge> used in code example as an alternative to <lift:head>.

Another variant you may see is class="lift:head", as an alternative to data-lift="head".

The head snippet is a built-in snippet, but otherwise no different from any snippet you might write. What the snippet does is emit a <head> block, containing the elements you want in the head. These can be <title>, <link>, <meta>, <style>, <script> or <base> tags. How does this <head> block produced by the head snippet end up inside the main <head> section of the page? When Lift processes your template, it automatically merges all <head> tags into the main <head> section of the page.

You might suspect you can therefore put a plain old <head> section anywhere on your template. You can, but that would not necessarily be valid HTML 5 mark up.

There’s also tail which works in a similar way, except anything marked with this snippet is moved to be just before the close of the body tag.

[JavaScriptTail] describes how to move JavaScript to the end of the page with the tail snippet.

The W3C HTML validator is a useful tool for tracking down HTML markup issues that may cause problems with content being moved into the head of your page. http://validator.w3.org/.

You want to show a customised "404" (not found) page.

In Boot.scala add the following:

The file src/main/webapp/404.html will now be served for requests to unknown resources.

The uriNotFound Lift rule needs to return a NotFound in reply to a Req and Box[Failure]. This allows you to customise the response based on the request and the type of failure.

There are three types of NotFound:

In the example we’re matching any not found situation, regardless of the request and the failure, and evaluating this as a resource identified by ParsePath. The path we’ve used is /404.html.

In case you’re wondering, the last two true and false arguments to ParsePath indicates the path we’ve given is absolute, and doesn’t end in a slash. ParsePath is a representation for a URI path, and exposing if the path is absolute or ends in a slash are useful flags for matching on, but in this case, they’re not relevant.

Be aware that 404 pages, when rendered this way, won’t have a location in the site map. That’s because we’ve not included the 404.html file in the site map, and we don’t have to because we’re rendering via NotFoundAsTemplate rather than sending a redirect to /404.html. However, this means that if you display an error page using a template that contains Menu.builder or similar (as templates-hidden/default.html does), you’ll see "No Navigation Defined". In that case, you’ll probably want to use a different template on your 404 page.

As an alternative, you could include the 404 page in your site map but make it hidden when the site map is displayed via the Menu.builder:

[CatchException] for how to catch any exception thrown from your code.

You want to show a customised page for certain HTTP status codes.

Use LiftRules.responseTransformers to match against the response and supply an alternative.

As an example, suppose we want to provide a custom page for 403 ("Forbidden") statuses created in our Lift application. Further suppose that this page might contain snippets so will need to pass through the Lift rendering flow.

To do this in Boot.scala we define the LiftResponse we want to generate and use the response when a 403 status is about to be produced by Lift:

The file src/main/webapp/403.html will now be served for requests that generate 403 status codes. Other, non-403, responses are left untouched.

LiftRules.responseTransformers allows you to supply LiftResponse => LiftResponse functions to change a response right at the end of the HTTP processing cycle. This is a very general mechanism: in this example we are matching on a status code, but we could match on anything exposed by LiftResponse.

In the recipe we respond with a template, but you may find situations where other kinds of response make sense, such as an InMemoryResponse.

You could even simplify the example to just this:

That redirect will work just fine, with the only downside that the HTTP status code sent back to the web browser won’t be a 403 code.

A more general approach, if you’re customising a number of pages, would be to define the status codes you want to customise, create a page for each, and then only match on those pages:

The convention in Customised is that we have a HTML file in src/main/webapp which matches the status code we want to show, but of course you can change that by using a different pattern in the argument to Templates.

One way to test the above examples is to add the following to Boot.scala to make all requests to /secret return a 403:

If you request /secret, a 403 response will be triggered, which will match the response transformer showing you the contents of the 403.html template.

[Custom404] explains the built-in support for custom 404 messages.

[CatchException] for how to catch any exception thrown from your code.

You want to include a clickable link in your S.error, S.notice or S.warning messages.

Include a NodeSeq containing a link in your notice:

You might pair this with the following in your template…

You may be more familiar with the S.error(String) signature of Lift notices than the versions that take a NodeSeq as an argument, but the String versions just convert the String argument to a scala.xml.Text kind of NodeSeq.

Lift notices are described on the Wiki: http://www.assembla.com/spaces/liftweb/wiki/Lift_Notices_and_Auto_Fadeout.

You want a button or a link which, which clicked, will trigger a download in the browser rather than visiting a page.

Create a link using SHtml.link, provide a function to return a LiftResponse and wrap the response in a ResponseShortcutException.

As an example, we will create a snippet that shows the user a poem and provides a link to download the poem as a text file. The template for this snippet will present each line of the poem separated by a <br>:

The snippet itself will render the poem and replace the download link with one which will send a response that the browser will interpret as a file to download:

Recall that SHtml.link generates a link and executes a function you supply before following the link.

The trick here is that wrapping the LiftResponse in a ResponseShortcutException will indicate to Lift that the response is complete, so the page being linked to (notused) won’t be processed. The browser is happy: it has a response to the link the user clicked on, and will render it how it wants to, which in this case will probably be by saving the file to disk.

SHtml.link works by generating a URL which Lift associates with the function you give it. On a page called downloadlink, the URL will look something like:

When that link is followed, Lift looks up the function and executes it, before processing the linked-to resource. However, in this case, we are short-cutting the Lift pipeline by throwing this particular exception. This is caught by Lift and the response wrapped by the exception is taken as the final response from the request.

This short-cutting is used by S.redirectTo via ResponseShortcutException.redirect. This companion object also defines shortcutResponse which you can use like this:

We’ve included a S.notice to highlight that throw shortcutResponse will process Lift notices when the page next loads, whereas throw new ResponseShortcutException does not. In this case, the notice will not appear when the user downloads the file, but it will be included the next time notices are shown, such as when the user navigates to another page. For many situations, the difference is immaterial.

This recipe has used Lift’s stateful features. You can see how useful it is to be able to close over state (the poem), and offer the data for download from memory. If you’ve created a report from a database, you can offer it as a download without having to re-generate the items from the database.

However, in other situations you might want to avoid holding this data as a function on a link. In that case, you’ll want to create a REST service that returns a LiftResponse.

[REST] looks at REST-based services in Lift.

[RestStreamContent] discusses InMemoryResponse and similar responses to return content to the browser

For reports, the Apache POI project, http://poi.apache.org/, includes libraries for generating Excel files; and OpenCSV, http://opencsv.sourceforge.net, is a library for generating CSV files.

You want to be able to test a function that needs a Req.

Supply a mock request to Lift’s MockWeb.testReq, and run your test in the context of the Req supplied by testReq.

The first step is to add Lift’s Test Kit as dependency to your project in build.sbt:

To demonstrate how to use testReq we will test a function that detects a Google crawler. Google identifies crawlers via various "User-Agent" header on a request, so the function we want to test would look like this:

We have the list of magic botNames that Google sends as a user agent, and we define a check, known_?, that takes the user agent string and looks to see if any robot satisfies the condition of being contained in that user agent string.

The googlebot_? method is given a Lift Req object and from this we look up the header. This evaluates to a Box[String] as it’s possible there is no header. We find the answer by seeing if there exists in the Box a value that satisfies the known_? condition.

To test this, we create a user agent string, prepare a MockHttpServletRequest with the header, and use Lift’s MockWeb to turn the low-level request into a Lift Req for us to test with:

Running this from SBT with the test command would produce:

Although MockWeb.testReq is handling the creation of a Req for us, the environment for that Req is supplied by the MockHttpServletRequest. To configure a request, create an instance of the mock and mutate the state of it as required before using it with testReq.

Aside from HTTP headers, you can set cookies, content type, query parameters, the HTTP method, authentication type, and the body. There are variations on the body assignment, which conveniently set the content type depending on the value you assign:

The Lift wiki discusses this topic and also other approaches such as testing with Selenium. https://www.assembla.com/spaces/liftweb/wiki/Testing_Lift_Applications.

You want to render Textile markup in your web application.

Install the Lift Textile module in your build.sbt file by adding the following to the list of dependencies:

You can then use the module to render Textile using the toHtml method.

For example, starting SBT after adding the module and running the SBT console command allows you to try out the module:

It’s a little easier to see the output if we pretty print it:

There’s nothing special code has to do to become a Lift module, although there are common conventions: they typically are packaged as net.liftmodules, but don’t have to be; they usually depend on a version of Lift; they sometimes use the hooks provided by LiftRules to provide a particular behaviour. Anyone can create and publish a Lift module, and anyone can contribute to existing modules. In the end, they are declared as dependencies in SBT, and pulled into your code just like any other dependency.

The dependency name is made up of two elements: the name and the "edition" of Lift that the module is compatible with, as shown in [ModuleVersioning]. By "edition" we just mean the first part of the Lift version number. This implies the module is compatible with any Lift release that starts "2.5".

This structure has been adopted because modules have their own release cycle, independent of Lift. However, modules may also depend on certain features of Lift, and Lift may change APIs between major releases, hence the need to use part of the Lift version number to identify the module.

There’s no real specification of what Textile is, but there are references available which cover the typical kinds of mark up to enter and what HTML you can expect to see: http://redcloth.org/hobix.com/textile/.

The home of the Textile module: https://github.com/liftmodules/textile.

The unit tests for the Textile module give you a good set of examples of what is supported: https://github.com/liftmodules/textile/blob/master/src/test/scala/net/liftmodules/textile/TextileSpec.scala.

[modules] describes how to create modules.

You want to process form data in a regular old-fashioned, non-Ajax, way.

Extract form values with S.param, process the values, and produce some output.

For example, we can show a form, process an input value, and give a message back as a notice. The template is a regular HTML form, with the addition of a snippet:

In the snippet we can pick out the value of the field "name" with S.param("name"):

The first time through this snippet there will be no parameter so we just pass back the form unchanged to the browser, which is what PassThru is doing. You can then enter a value into the "name" field and submit the form. This will result in Lift processing the template again, but this time with a value for the "name" input. The result will be your browser redirected to a page with a message set for display.

Manually plucking parameters from a request isn’t making the best use of Lift, but sometimes you need to do it, and S.param is the way you can process request parameters.

The result of S.param is a Box[String], and in the above example we pattern match on a value. With more than one parameter you’re probably see S.param used in this way:

If both "name" and "petName" are provided, the body of the for will be evaluated.

Related function on S include:

As an example of using S.request we could produce a List[String] for the values of all request parameters that have "name" somewhere in their parameter name:

Note that by opening up S.request we can access all the parameter names via paramNames function on Req.

Screen or Wizard provide alternatives for form processing, but sometimes you just want to pull values from a request, as demonstrated in this recipe.

Simply Lift covers a variety of ways of processing forms. See: http://simply.liftweb.net.

You want to process a form on the server via Ajax, without reloading the whole page.

Mark your form as an Ajax form with data-lift="form.ajax" and supply a function to run on the server when the form is submitted.

Here’s an example of a form that will collect our name, and submit it via Ajax to the server:

The following snippet will echo back the name via Ajax:

The render method is binding the name input field to a function that will assign whatever the user enters to the variable name. Note you’ll more typically see s => name = s written in the shorter form of name = _.

When the button is pressed, the process function is called, which will return the value of the name back to the element in the HTML with an ID of result.

The data-lift="form.ajax" part of this recipe ensures that Lift adds the Ajax processing mechanics to the form. This means the <form> element in the output will end up as something like:

In other words, when the form is asked to submit, Lift will serialise the form via Ajax. This means you don’t necessarily need the submit button at all. In this example with a single text field, if you omit the submit button you can trigger serialisation by pressing return. This will trigger the s => name = s function which was bound in our regular data-lift="EchoForm" snippet. In other words, the value name will be assigned even without a submit button.

Adding in a submit button gives us a way to perform actions once all the field’s functions have been executed.

Notice that Lift’s approach is to serialise the form to the server, execute the functions associated with the fields, execute the submit function (if any), then return a JavaScript result to the client. The default serialisation process is to use jQuery’s serialization method on the form. This serializes fields except submit buttons and file uploads.

Function order is discussed in the Lift Cool Tips wiki page: http://www.assembla.com/spaces/liftweb/wiki/cool_tips.

Form serialization is described at http://api.jquery.com/serialize/.

[AjaxFileUpload] describes Ajax file uploads.

You want to process a form via Ajax, sending the data in JSON format.

Make use of Lift’s jlift.js JavaScript library and JsonHandler class.

As an example we can create a "motto server" that will accept an institution name and the institution’s motto and perform some action on these values. We’re just going to echo the name and motto back to the client.

Consider this HTML, which is not in a form, but includes jlift.js:

This HTML presents the user with two fields, a name and a motto, wrapped in a div called jsonForm. There’s also a placeholder for some results, and you’ll notice a jsonScript placeholder for some JavaScript code. The jsonForm will be manipulated to ensure it is sent via Ajax, and the jsonScript will be replaced with Lift’s code to perform the serialisation. This happens in the snippet code:

Like many snippets, this Scala code contains a render method which binds to elements on the page. Specifically, jsonForm is being replaced with SHtml.jsonForm, which will take a NodeSeq (which are the input fields) turns it into a form that will submit the values as JSON. The submission will be to our MottoServer code.

The jsonScript element is bound to JavaScript that will perform the transmission and encoding of the values to the server.

If you click the "Send" button and observe the network traffic, you’ll see the following sent to the server:

This is the value of the all parameter in the JsonCmd being pattern matched against in MottoServer.apply. Lift has taken care of the plumbing to make this happen.

The result of the pattern match in the example is to pick out the to field values, and send back JavaScript to update the results div with: "The motto of the Royal Society is Nullius in verba".

The JsonHandler class and the SHtml.jsonForm method are together performing a lot of work for us. The jsonForm method is arranging for form fields to be encoded as JSON and sent, via Ajax, to our MottoServer as a JsonCmd. In fact, it’s a JsonCmd with a default command name of "processForm".

Our MottoServer class is looking for (matching on) this JsonCmd, extracting the values of the form fields, and echoing these back to the client as a JsCmd that updates a div on the page.

The MottoServer.jsCmd part is generating the JavaScript required to deliver the form fields to the server. As we will see later, this is providing a general purpose function we can use to send different JSON values and commands to the server.

Notice also, from the network traffic, that the form fields sent are serialised with the names they are given on the page. There are no "F…" values sent which map to function calls on the server. A consequence of this is that any fields dynamically added to the page will also be serialised to the server, where they can be picked up in the MottoServer.

The script jlift.js is providing the plumbing to make much of this happen.

Before going on, convince yourself that we’re generating JavaScript on the server-side (MottoServer.jsCmd), which is executed on the client side when the form is submitted, to deliver results to the server.

There are further examples of JsonHandler at http://demo.liftweb.net/json_more.

If you want to process JSON via REST, take a look at the examples at http://demo.liftweb.net/stateless_json.

Lift in Action, section 9.1.4 discusses "Using JSON forms with AJAX", as does section 10.4 of Exploring Lift at http://exploring.liftweb.net.

You want to provide a date picker to make it easy for users to supply dates to your forms.

Use a standard Lift SHtml.text input field and attach a JavaScript date picker to it. In this example we will use the jQuery UI date picker.

Our form will include an input field called birthday to be used as a date picker, and also the jQuery UI JavaScript and CSS:

This would normally produce a regular text input field, but we can change that by adding JavaScript to attach the date picker to the input field. You could do this in the template, but in this example we’re enhancing the text field as part of the snippet code:

Notice in render we are binding a regular SHtml.text field to the element with the ID of "birthday", but also appending JavaScript to the page. That JavaScript selects the birthday input field and attaches a configured date picker to it.

When the field is submitted, the logDate method is called with the value of the text field. We parse the text into a java.util.Date object. The tryo Lift helper will catch any ParseException and return a Box[Date] which we open, or default to the current date if a bad date is supplied.

Running this code and submitting the form will produce a log message something like this:

The approach outlined in this recipe can be used with other date picker libraries. The key point is to configure the date picker to submit a date in a format you can parse when the value is submitted to the server. This is the "wire format" of the date, and does not have to necessarily be the same format the user sees in the browser, depending on the browser or the JavaScript library being used.

Dive into HTML5, at http://diveintohtml5.info , describes how to detect browser features.

jQuery UI’s date picker has many configuration options, which are described at http://api.jqueryui.com/datepicker/.

The HTML5 date input types submit dates in RFC3339 format. These are specified at http://tools.ietf.org/html/rfc3339

You want to provide an autocomplete widget, to give users suggestions as they type into a text field.

Use a JavaScript autocomplete widget, for example the jQuery UI autocomplete via the AutoComplete class from the Lift Widgets module.

Start by adding the Lift widgets module to your build.sbt:

To enable the autocomplete widget, initialize it in Boot.scala:

We can create a regular form snippet…

…and connect the AutoComplete class to the element with the ID of "autocomplete":

The last line of this snippet shows the binding of the AutoComplete class, which takes:

Running this code renders as shown in [AutoCompleteWidgetScreenGrab].

When the form is submitted, the submit function will be passed the selected value. The submit function is simply logging this value:

The autocomplete widget uses jQuery autocomplete. This can be seen by examining the NodeSeq produced by the AutoComplete.apply method:

This chunk of markup is generated from the AutoComplete(default, suggest, submit) call. What’s happening here is that the jQuery UI autocomplete JavaScript and CSS, which is bundled with the Lift Widgets module, is being included on the page. Recall from [AddToHead] that Lift will merge the <head> part of this markup into the <head> of the final HTML page.

When the page loads, the jQuery UI autocomplete function is bound to the input field, and configured with a URL which will deliver the user’s input to our suggest function. All suggest need to do is return a Seq[String] of values for the jQuery autocomplete code to display to the user.

[ButtonTriggerServerCode] describes jsonCall.

The behaviour of the widget module with respect to new values is described in a ticket on the module’s GitHub page: https://github.com/liftmodules/widgets/issues/4. Enhancing modules is one route to get involved with Lift, and [ContributingAndHelp] describes other ways to contribute.

The jQuery UI Autocomplete widget is documented at: http://jqueryui.com/autocomplete/ . The version included with the Lift widgets module is version 1.0.2.

You can find documentation for Twitter Bootstrap Typeahead at http://twitter.github.io/bootstrap/javascript.html#typeahead.

You want users to select an option using radio buttons.

Use SHtml.radioElem to present the options as radio buttons, but retain type safety.

To illustrate this, let’s create a form to allow a user to specify their gender:

We’re using an enumeration, but it could be any class. The toString of the class will be used as the label shown to the user.

To present these options and handle the section, we use the enumeration in a snippet:

Rather than generate the radio buttons in one expression on the render method, we’ve pulled out the intermediate values to show their types. The radio.toForm call is generating the radio buttons and we’re binding them to the CSS selector ".option" in the following template:

The "options" span will be replaced with the radio buttons from the code, and when the form is submitted the function supplied to SHtml.radioElem will be called resulting in the selected value being logged:

…or perhaps…

Many of the Lift SHtml methods return a NodeSeq which can be directly bound into our HTML. However, radioElem is different in that it gives us a ChoiceHolder[T], and to generate a NodeSeq from that we’re calling toForm. This has implications for how you customize radio buttons, as we’ll see later.

The radioElem method expects three parameters:

The first is the set of options to show, as a Seq[T]. The second is the value to be pre-selected as a Box[T]. In the example we have no pre-selected value, which is represented as Empty. Finally, there’s the function to run when the form is submitted, of type Box[T] => Any.

Note that even if the user selects no value, your function will be called, and it will be given the value Empty.

To understand a little more of what’s happening, take a look at the default HTML produced by radioElem:

Notice that:

This might be a surprise if you were just expecting something like:

By using random values, Lift has helped us by protecting against a range of form-based attacks, such as submitting values we’re not expected or setting values on fields we don’t want set.

Each of the random radio button values is associated, on the server, with a value from our options (a BirthGender instance). The hidden value maps to a function that’s called when the form is submitted, and by using the common "name" value on the fields, it is able to pick out the selected radio button and identify the corresponding BirthGender value and pass it to our code.

You want to add the disabled attribute to a SHtml.checkbox based on a conditional check.

Create a CSS selector transform to add the disabled attribute, and apply it to your checkbox transform.

For example, suppose you have a simple checkbox…

…and a corresponding template:

Further suppose you want to disable it roughly 50% of the time. We could do that by adjusting the NodeSeq generated from SHtml.checkbox:

When the checkbox is rendered, it will be disabled roughly half the time.

The disable method returns a NodeSeq => NodeSeq function, meaning when we apply it we need to give it a NodeSeq, which is exactly what SHtml.checkbox provides.

The [disabled] part of the CSS selector is selecting the disabled attribute and replacing it with the value on the right of the #>, which is "disabled" in this example.

What this combination means is that half the time the disabled attribute will be set on the checkbox, and half the time the checkbox NodeSeq will be left untouched because PassThru does not change the NodeSeq.

[PassThru] describes the PassThru function.

You want to show the user a number of options in a select box, and allow them to select multiple values.

Use SHtml.multiSelect(options, default, selection). Here’s an example where a user can select up to three options:

In this example the user is being presented with a list of three items, with the first one selected, as shown in [MultiSelectExample]. When the form is submitted the selection function is called, with a list of the selected option values.

The template to go with the snippet could be:

This will render as something like:

Recall that an HTML select consists of a set of options, each of which has a value and a name. To reflect this, the above examples takes our inventory of objects and turns it into a list of (value,name) string pairs, called options.

The function given to SHtml.multiSelect will receive the values (IDs), not the names, of the options. That is, if you ran the above code, and selected "Coffee" and "Milk" the function would see List("a", "b").

The "Submit Styling" discussion section in [AjaxFormProcessing] discusses the use of hidden fields as function calls.

[SelectOptionChange] describes how to trigger a server-side action when a selection changes in the browser.

Chapter 6 of Exploring Lift, "Forms in Lift", discusses multiselect and other types of form elements at http://exploring.liftweb.net/.

The issue relating to no options being selected is on Github: https://github.com/lift/framework/issues/1139

You want a snippet to allow users to upload a file to your Lift application.

Use a FileParamHolder in your snippet, and extract file information from it when the form is submitted.

Start with a form which is marked as "multipart=true":

We bind the file input to SHtml.fileUpload and the submit button to a function to process the uploaded file:

The fileUpload binding ensures that the file is assigned to the upload variable. This allows us to access the Array[Byte] of the file in the processForm method when the form is submitted.

HTTP includes an encoding type of "multipart/form-data" which was introduced to support binary data uploads. The ?form=post;multipart=true parameters in the template mark the form with this encoding, and the HTML generated will look like this:

When the browser submits the form, Lift detects the "multipart/form-data" encoding and extracts any files from the request. These are available as uploadedFiles on a Req object, for example:

However, as we’re dealing with a form with a single upload field it’s easier to use SHtml.fileUpload to bind the input to our upload variable. Lift arranges for the function f => upload = Full(f) to be called when a file is selected and uploaded via this field. If the file is zero length, the function is not called.

The default behaviour for Lift is to read the file into memory and present it as a FileParamHolder. In this recipe we’re pattern matching on the fields of the FileParamHolder and simply printing out what we know about the file. We’re ignoring the first parameter which will be Lift’s generated name for the field, but capturing the mime type, original filename and the raw data that was in the file.

You probably don’t want to use this method for very large files. In fact, LiftRules provides a number of size restrictions which you can control:

Why two settings? Because when the form is submitted, there may be a number of fields on the form. For example, in the recipe the value of the submit button is send as one of the parts, and the file is sent as another. Hence, you might want to limit file size, but allow for some field values, or multiple files, to be submitted.

If you hit the size limit an exception will be thrown from the underlying file upload library. You can catch the exception, as described in [CatchException]:

Be aware that the container (Jetty, Tomcat) or any web server (Apache, NGINX) may also have limits on file upload sizes.

Uploading a file into memory may be fine for some situations, but you may want to upload larger items to disk and then processes them in Lift as a stream. Lift supports this via the following setting:

The handleMimeFile variable expects to be given a function that takes a field name, mime type, filename and InputStream and returns a FileParamHolder. The default implementation of this is the InMemFileParamHolder, but changing to OnDiskFileParamHolder means Lift will write the file to disk first. You can of course implement your own handler in addition to using OnDiskFileParamHolder or InMemFileParamHolder.

With OnDiskFileParamHolder, the file will be written to a temporary location (System.getProperty("java.io.tmpdir")) but it’s up to you to remove it when you’re done with the file. For example, our snippet could change to:

Be aware that OnDiskFileParamHolder implements FileParamHolder so would match the original FileParamHolder pattern used in the recipe. However, if you access the file field of OnDiskFileParamHolder, you’ll bring the file into memory, which would defeat the point of storing it on disk to process it as a stream.