There are several means to getting attributes:

  // Get a Box for the attribute:
  val myAttr = S.attr("test") openOr "Not found"
  // Get an attribute or return a default value:
  val myAttr = S.attr("name", "Fred")
  // Apply a transform function on the attribute value, or return an Empty:
  val pageSize = S.attr("count", _.toInt) openOr 20
  // There are also prefixed versions:
  val prefixedAttr = S.attr("prefix", "name") openOr "Not found"
   

attrs to a Map[String, String]. The key of the map depends on whether the attribute is prefixed or not. Prefixed attributes have keys of the form "prefix:name", while unprefixed attributes have keys of the form "name". If you only want attributes for a specific prefix, use prefixedAttrsToMap.

see

- # prefixedAttrsToMap ( String, Map )

- # prefixedAttrsToMap ( String )

attrs attributes to a MetaData object that can be used to add attributes to one or more XML elements. Similar to prefixedAttrsToMetaData, except that it handles both prefixed and unprefixed attributes. This version of the method will use all of the currently set attributes from S.attrs. If you want to filter it, use the attrsToMetaData(String => Boolean) version, which allows you to specify a predicate function for filtering. For example, if you want all of the current attributes to be added to a div tag, you could do:

   val myDiv = (
 {...} 
) % S.attrsToMetaData
   

return

- a MetaData instance representing all attributes in S.attrs

see

- # attrsToMetaData ( String = > Boolean )

See addHighLevelSessionDispatcher for an example of usage.

see

- # clearHighLevelSessionDispatcher

- LiftRules.dispatch

- # addHighLevelSessionDispatcher

- LiftRules.DispatchPF

See addSessionRewriter for an example of usage.

see

- # addSessionRewriter

- # removeSessionRewriter

- LiftRules.rewrite

attrs attributes to a MetaData object that can be used to add attributes to one or more XML elements. Similar to prefixedAttrsToMetaData, except that it handles both prefixed and unprefixed attributes. This version of the method will use all of the currently set attributes from S.attrs. If you want to filter it, use the attrsToMetaData(String => Boolean) version, which allows you to specify a predicate function for filtering. For example, if you want all of the current attributes to be added to a div tag, you could do:

   val myDiv = (
 {...} 
) % S.attrsToMetaData
   

return

- a MetaData instance representing all attributes in S.attrs

see

- # attrsToMetaData ( String = > Boolean )

return

- true if mapped functions will currently last the life of the session.

Using these bindings is considered advanced functionality.

This is a thin wrapper on Req.get_?

return

- true if the request is a GET, false otherwise.

see

- Req.get_ ?

see

- DispatchHolder

DispatchPF functions that are set for this session. See addHighLevelSessionDispatcher for an example of how these are used.

see

- # clearHighLevelSessionDispatcher

- # addHighLevelSessionDispatcher ( String, LiftRules.DispatchPF )

- # removeHighLevelSessionDispatcher ( String )

- LiftRules.DispatchPF

This does not include the template path or query string.

This is taken from the "Host" HTTP header, or if that does not exist, the DNS name or IP address of the server.

return

- true if this response should be rendered in IE6/IE7 compatibility mode.

see

- Req.isIE6

- Req.isIE8

- LiftSession.ieMode

- Req.isIE

- LiftRules.calcIEMode

- Req.isIE7

If the S object has not been initialized then functionality on S will not work.

This corresponds to the current Snippet's name. For example, the snippet:

  <lift:Hello.world />
   

Will return "Hello.world".

liftCoreResourceName varibale.

see

- LiftRules.liftCoreResourceName

localeCalculator method.

see

- java.util.Locale

- LiftRules.localeCalculator ( HTTPRequest )

loggedInTest. You can define your own function to check to see if a user is logged in there and this will call it.

return

- the value from executing LiftRules.loggedInTest, or false if a test function is not defined.

see

- LiftRules.loggedInTest

This is a thin wrapper over Req.post_?

return

- true if the request is a POST request, false otherwise.

return

- a List of any Cookies that have been set for this Response. If you want a specific cookie, use findCookie.

see

- # addCookie ( Cookie )

- # deleteCookie ( String )

- net.liftweb.http.provider.HTTPCookie

- # findCookie ( String )

- # deleteCookie ( Cookie )

return

- A Full(Req) if S has been initialized, Empty otherwise.

see

- Req

The resource bundles are defined by the LiftRules.resourceNames and LiftRules.resourceBundleFactories variables.

see

- LiftRules.resourceBundleFactories

- LiftRules.resourceNames

return

- a List of any Cookies that have been added to the response to be sent back to the user. If you want the cookies that were sent with the request, see receivedCookies.

see

- net.liftweb.http.provider.HTTPCookie

- # receivedCookies

See addSessionRewriter for an example of how to use per-session rewrites.

see

- LiftRules # rewrite

- RewriteHolder

If you're sending XHTML and this is set to true, you need to include the DocType in your template.

see

- # skipDocType_ =(Boolean)

timeZoneCalculator method.

see

- java.util.TimeZone

- LiftRules.timeZoneCalculator ( HTTPRequest )

The URI is the portion of the request URL after the context path. For example, with a context path of "myApp", Lift would return the following URIs for the given requests:

HTTP request	URI
http://foo.com/myApp/foo/bar.html		/foo/bar.html
http://foo.com/myApp/test/		/test/
http://foo.com/myApp/item.html?id=42		/item.html

If you want the full URI, including the context path, you should retrieve it from the underlying HTTPRequest. You could do something like:

     val fullURI = S.request.map(_.request.getRequestURI) openOr ("Undefined")
   

The URI may be used to provide a link back to the same page as the current request:

     bind(...,
          "selflink" -> SHtml.link(S.uri,  { () => ... }, Text("Self link")),
          ...)
   

see

- net.liftweb.http.provider.HTTPRequest.uri

- Req.uri

param

str - the string to localize

return

- the localized version of the string

see

- # resourceBundles

This uses the String.format method to format the localized string.

param

params - the var-arg parameters applied for string formatting

str - the string to localize

return

- the localized and formatted version of the string

see

- String.format

- # resourceBundles

param

str - the string to localize

return

- the localized version of the string

param

params - the var-arg parameters applied for string formatting

str - the string to localize

return

- the localized version of the string

The analyzer methods are executed with the request, total time to process the request, and the List of query log entries once the current request completes.

see

- # queryLog

- # logQuery

The wrapper can execute code before and after the request is processed (but still have S scope). This allows for query analysis, etc. Wrappers are chained, much like servlet filters, so you can layer processing on the request. As an example, let's look at a wrapper that opens a resource and makes it available via a RequestVar, then closes the resource when finished:

   import net.liftweb.http.{ ResourceVar,S }
   import net.liftweb.util.LoanWrapper
  
   // Where "ResourceType" is defined by you
   object myResource extends ResourceVar[ResourceType](...)
  
   class Boot  {
     def boot  {
       ...
       S.addAround(
         new LoanWrapper  {
           def apply[T](f: => T) : T =  {
             myResource(... code to open and return a resource instance ...)
             f() // This call propagates the request further down the "chain" for template processing, etc.
             myResource.is.close() // Release the resource
   }
   }
       )
       ...
   }
   }
   

see

- LoanWrapper

- # addAround ( LoanWrapper )

The wrapper can execute code before and after the request is processed (but still have S scope). This allows for query analysis, etc. See S.addAround(LoanWrapper) for an example. This version of the method takes a list of LoanWrappers that are applied in order.

see

- LoanWrapper

- # addAround ( LoanWrapper )

Exceptions thrown from these functions will be swallowed, so make sure to handle any expected exceptions within your function.

param

f - The function to execute at the end of the request.

If you wish to delete a Cookie as part of the Response, use the deleteCookie method. An example of adding and removing a Cookie is:

   import net.liftweb.http.provider.HTTPCookie
  
   class MySnippet  {
     final val cookieName = "Fred"
  
     def cookieDemo (xhtml : NodeSeq) : NodeSeq =  {
       var cookieVal = S.findCookie(cookieName).map(_.getvalue) openOr ""
  
       def setCookie()  {
         val cookie = HTTPCookie(cookieName, cookieVal).setMaxAge(3600) // 3600 seconds, or one hour
         S.addCookie(cookie)
   }
  
       bind("cookie", xhtml,
            "value" -> SHtml.text(cookieVal, cookieVal = _),
            "add" -> SHtml.submit("Add", setCookie)
            "remove" -> SHtml.link(S.uri, () => S.deleteCookie(cookieName), "Delete Cookie")
       )
   }
   }
   

see

- # responseCookies

- # deleteCookie ( Cookie )

- # deleteCookie ( String )

- net.liftweb.http.provider.HTTPCookie

These are basically functions that are executed when a request contains the 'name' request parameter.

dispatch. An example would be if we wanted a user to be able to download a document only when logged in. First, we define a dispatch function to handle the download, specific to a given user:

   def getDocument(userId : Long)() : Box[LiftResponse] =  { ... }
   

Then, in the login/logout handling snippets, we could install and remove the custom dispatch as appropriate:

     def login(xhtml : NodeSeq) : NodeSeq =  {
       def doAuth ()  {
         ...
         if (user.loggedIn_?)  {
           S.addHighLevelSessionDispatcher("docDownload",  {
             case Req(List("download", "docs"), _, _) => getDocument(user.id)
   } )
   }
   }
  
     def logout(xhtml : NodeSeq) : NodeSeq =  {
       def doLogout ()  {
         ...
         S.removeHighLevelSessionDispatcher("docDownload")
         // or, if more than one dispatch has been installed, this is simpler
         S.clearHighLevelSessionDispatcher
   }
   }
   

It's important to note that per-session dispatch takes precedence over LiftRules.dispatch, so you can override things set there.

param

disp - The dispatch partial function

name - A name for the dispatch. This can be used to remove it later by name.

see

- LiftRules.dispatch

- # clearHighLevelSessionDispatcher

- LiftRules.DispatchPF

- # removeHighLevelSessionDispatcher

This can be used if you only want a particular rewrite to be valid within a given session. Per-session rewrites take priority over rewrites set in LiftRules.rewrite, so you can use this mechanism to override global functionality. For example, you could set up a global rule to make requests for the "account profile" page go back to the home page by default:

   package bootstrap.liftweb
   ... imports ...
   class Boot  {
     def boot  {
       LiftRules.rewrite.append  {
         case RewriteRequest(ParsePath(List("profile")), _, _, _) =>
           RewriteResponse(List("index"))
   }
   }
   }
   

Then, in your login snippet, you could set up a per-session rewrite to the correct template:

   def loginSnippet (xhtml : NodeSeq) : NodeSeq =  {
     ...
     def doLogin ()  {
       ...
       S.addSessionRewriter("profile",  {
         case RewriteRequest(ParsePath(List("profile")), _, _, _) =>
           RewriteResponse(List("viewProfile"), Map("user" -> user.id))
   }
       ...
   }
     ...
   }
   

And in your logout snippet you can remove the rewrite:

     def doLogout ()  {
       S.removeSessionRewriter("profile")
       // or
       S.clearSessionRewriter
   }
   

param

name - A name for the rewrite function so that it can be replaced or deleted later. @rw The rewrite partial function

see

- # removeSessionRewriter

- LiftRules.rewrite

- # sessionRewriter

- # clearSessionRewriter

Only registers if the name is not already set.

Each attribute item is a pair of (key,value). The key is an Either that depends on whether the attribute is prefixed or not. If the attribute is prefixed, the key is a Right((prefix, name)). If the attribute is unprefixed then the key is a Left(name). For example, the following table shows how various tag attributes would be represented:

Snippet Tag	Parsed attrs
<lift:MySnippet testname="test" />	List((Left("testname"), "test"))
<lift:MySnippet anchor:name="test" />	List((Right(("anchor", "name")), "test"))

The prefixedAttrsToMap method provides a convenient way to retrieve only attributes with a given prefix. The prefixedAttrsToMetaData method can be used to add attributes onto an XML node

see

- # prefixedAttrsToMetaData ( String, Map )

- # prefixedAttrsToMap ( String, Map )

- # prefixedAttrsToMetaData ( String )

- # prefixedAttrsToMap ( String )

attrsToMetaData, but lets you specify a predicate function that filters the generated MetaData. For example, if you only wanted the "id" attribute, you could do:

   val myDiv = (
 {...} 
) % S.attrsToMetaData(_.equalsIgnoreCase("id"))
   

param

predicate - The predicate function which is executed for each attribute name. If the function returns true, then the attribute is included in the MetaData.

see

- # attrsToMetaData

param

f - - function returning a JsCmds

return

- ( JsonCall, JsCmd )

param

f - - function returning a JsCmds

name - -- the optional name of the command (placed in a comment for testing)

return

- ( JsonCall, JsCmd )

e. using SHtml helpers) inside the closure passed to callOnce, after your function is invoked, it will be automatically removed from functions cache so that it cannot be invoked again.

potentially very destuctive... use at your own risk!

param

f - the AFuncHolder that you want to wrap with execution context

param

f - - partial function against a returning a JsCmds

onError - -- the JavaScript to execute client-side if the request is not processed by the server

return

- ( JsonCall, JsCmd )

You can use the helpful Extractor in net.liftweb.util.JsonCommand

param

onError - -- the JavaScript to execute client-side if the request is not processed by the server

f - - partial function against a returning a JsCmds

name - -- the optional name of the command (placed in a comment for testing)

return

- ( JsonCall, JsCmd )

param

f - - partial function against a returning a JsCmds

return

- ( JsonCall, JsCmd )

attrsToMetaData, but lets you specify a predicate function that filters the generated MetaData. For example, if you only wanted the "id" attribute, you could do:

   val myDiv = (
 {...} 
) % S.attrsToMetaData(_.equalsIgnoreCase("id"))
   

param

predicate - The predicate function which is executed for each attribute name. If the function returns true, then the attribute is included in the MetaData.

see

- # attrsToMetaData

param

cookie - the Cookie to delete

see

- # deleteCookie ( String )

- net.liftweb.http.provider.HTTPCookie

- # addCookie ( Cookie )

param

name - the name of the cookie to delete

see

- # deleteCookie ( Cookie )

- net.liftweb.http.provider.HTTPCookie

- # addCookie ( Cookie )

Also it appends general purpose parameters defined by LiftRules.urlDecorate

param

name - - the name of the cookie to find

return

- Full ( cookie ) if the cookie exists, Empty otherwise

see

- # receivedCookies

- # deleteCookie ( Cookie )

- # deleteCookie ( String )

- net.liftweb.http.provider.HTTPCookie

- # addCookie ( Cookie )

unusedFunctionsLifeTime). In some cases (e.g., JSON handlers), you may want to extend the lifespan of the functions to the lifespan of the session.

param

f - A function to execute in the context of specified span

span - If true, extend the mapped function lifetime to the life of the session

see

- LiftRules.unusedFunctionsLifeTime

see

- # unset

- # set

- # setSessionAttribute

- # unsetSessionAttribute

- # getSessionAttribute

The default is XHTML 1.0 Transitional.

see

- DocType

- setDocType

If you want a request header, use Req.getHeader or S.getRequestHeader.

param

name - The name of the HTTP header to retrieve

return

- A Full(value) or Empty if the header isn't set

see

- # getHeaders ( List[ ( String, String ) ] )

- # setHeader ( String, String )

- # getRequestHeader ( String )

To retrieve a specific response header, use S.getHeader. If you want to get request headers (those sent by the client), use Req.getHeaders or S.getRequestHeader.

see

- # getHeader ( String )

- # getRequestHeader ( String )

- # setHeader ( String, String )

This is really just a thin wrapper on Req.header(String). For response headers, see S.getHeaders, S.setHeader, or S.getHeader.

param

name - The name of the HTTP header to retrieve

return

- A Full(value) or Empty if the header isn't set

see

- # getHeader ( String )

- # getHeaders ( List[ ( String, String ) ] )

- Req # header ( String )

- # setHeader ( String, String )

see

- # unset

- # set

- # setSessionAttribute

- # unsetSessionAttribute

- # get

Messages associated with the same id will be enlisted.

param

f - - the function that returns the messages

Generally this is handled by Lift during request processing, but this method is available in case you want to use S outside the scope of a request (standard HTTP or Comet).

param

session - the LiftSession for this request

f - Function to execute within the scope of the request and session

request - The Req instance for this request

The localized string is converted to an XML element if necessary via the LiftRules.localizeStringToXml function (the default behavior is to wrap it in a Text element). If the lookup fails for a given resource bundle (e.g. a null is returned), then the LiftRules.localizationLookupFailureNotice function is called with the input string and locale.

param

str - the string or ID to localize

return

- A Full box containing the localized XML or Empty if there's no way to do localization

see

- # resourceBundles

- LiftRules.localizationLookupFailureNotice

- # loc ( String, NodeSeq )

- # locale

- LiftRules.localizeStringToXml

param

dflt - the default string to return if localization fails

str - the string or ID to localize

return

- the localized XHTML or default value

see

- # loc ( String )

see

- LiftRules.snippets

The query log can be tested to see if queries for the particular page rendering took too long. The query log starts empty for each new request. net.liftweb.mapper.DB.queryCollector is a method that can be used as a log function for the net.liftweb.mapper.DB.addLogFunc method to enable logging of Mapper queries. You would set it up in your bootstrap like:

   import net.liftweb.mapper.DB
   import net.liftweb.http.S
   class Boot  {
     def boot  {
       ...
       DB.addLogFunc(DB.queryCollector)
       ...
   }
   }
   

Note that the query log is simply stored as a List and is not sent to any output by default. To retrieve the List of query log items, use S.queryLog. You can also provide your own analysis function that will process the query log via S.addAnalyzer.

see

- # addAnalyzer

- net.liftweb.mapper.DB.addLogFunc

- # queryLog

When this request is submitted to server the function will be executed and then it is automatically cleaned up from functions caches.

This can be used to change a snippet mapping on a per-session basis. For example, if we have a page that we want to change behavior on based on query parameters, we could use mapSnippet to programmatically determine which snippet function to use for a given snippet in the template. Our code would look like:

  import _root_.scala.xml.{ NodeSeq,Text }
  class SnipMap  {
  def topSnippet (xhtml : NodeSeq) : NodeSeq =  {
  if (S.param("showAll").isDefined)  {
  S.mapSnippet("listing", listing)
  } else  {
  S.mapSnippet("listing",  { ignore => Text("") } )
  }
  ...
  }
  def listing(xhtml : NodeSeq) : NodeSeq =  {
  ...
  }
  

Then, your template would simply look like:

  <lift:surround with="default" at="content">
  ...
  <p><lift:SnipMap.topSnippet /></p>
  <p><lift:listing /></p>
  </lift:surround>
   

Snippets are processed in the order that they're defined in the template, so if you want to use this approach make sure that the snippet that defines the mapping comes before the snippet that is being mapped.

param

func - The snippet function to map to.

name - The name of the snippet that you want to map (the part after "<lift:").

This can be used to add attributes to an XML element based on a map of attribute->value pairs. See prefixedAttrsToMetaData(String,Map) for an example.

param

in - The map of attributes

return

- MetaData representing the Map of attributes as unprefixed attributes.

see

- # prefixedAttrsToMetaData ( String, Map )

param

f - - the function that returns the messages

param

f - - the function that returns the messages

id - - the lookup id

param

f - - the function that returns the messages

The addSnippetForClass method is preferred

param

start - the initial Map

prefix - the prefix to be matched

return

- Map[String, String]

see

- # prefixedAttrsToMap ( String )

- # prefixedAttrsToMetaData ( String, Map )

- # prefixedAttrsToMetaData ( String )

param

prefix - the prefix to be matched

return

- Map[String, String]

see

- # prefixedAttrsToMetaData ( String )

- # prefixedAttrsToMap ( String, Map )

- # prefixedAttrsToMetaData ( String, Map )

The start Map will be 'merged' with the Map resulted after prefix matching and the result Map will be converted to a MetaData. The MetaData can be used to add attributes back onto XML elements via Scala's '%' method. For example, if we wanted to add attributes prefixed with "anchor" to any <a> elements we create, we could do something like:

     val myLink = (...) % S.prefixedAttrsToMetaData("anchor", Map("id" -> "myAnchor"))
   

param

start - the initial Map

prefix - the prefix to be matched

return

- MetaData representing the combination of current attributes plus the start Map of attributes

see

- # prefixedAttrsToMap ( String )

- # prefixedAttrsToMetaData ( String )

- # prefixedAttrsToMap ( String, Map )

These log entries are added via the logQuery method, which has a more detailed explanation of usage.

see

- # addAnalyzer

- # logQuery ( String, Long )

Otherwise the function is exactly the same as S.redirectTo(String), which has example documentation. Note that if the URL that you redirect to must be part of your web application or the function won't be executed. This is because the function is only registered locally.

param

func - The function to be executed when the redirect is accessed.

where - The new URL to redirect to.

see

- # redirectTo ( String )

Note that the underlying mechanism for redirects is to throw a ResponseShortcutException, so if you're doing the redirect within a try/catch block, you need to make sure to either ignore the redirect exception or rethrow it. Two possible approaches would be:

     ...
     try  {
       // your code here
       S.redirectTo(...)
   } catch  {
       case e: Exception if !e.instanceOf[net.liftweb.http.ResponseShortcutException] => ...
   }
   

or

     ...
     try  {
       // your code here
       S.redirectTo(...)
   } catch  {
       case rse: net.liftweb.http.ResponseShortcutException => throw rse
       case e: Exception => ...
   }
   

param

where - The new URL to redirect to.

see

- ResponseShortcutException

- # redirectTo ( String, ( ) => Unit)

See addHighLevelSessionDispatcher for an example of usage.

param

name - The name of the custom dispatch to be removed.

see

- # addHighLevelSessionDispatcher

- LiftRules.DispatchPF

- LiftRules.dispatch

- # clearHighLevelSessionDispatcher

See addSessionRewriter for an example of usage.

see

- # addSessionRewriter

- # clearSessionRewriter

- LiftRules.rewrite

Note that this must be called in a stateful context, therefore the S state must be a valid one.

param

f - - the user function that does the actual computation. This function takes one parameter which is the function that must be invoked for returning the actual response to the client. Note that f function is invoked asynchronously in the context of a different thread.

This can be used to load a template from within some other Lift processing, such as a snippet or view. If you just want to retrieve the XML contents of a template, use TemplateFinder.findAnyTemplate.

param

path - The path for the template that you want to process

return

- a Full Box containing the processed template, or a Failure if the template could not be found.

see

- TempalateFinder # findAnyTemplate

Otherwise the function is exactly the same as S.seeOther(String), which has example documentation. Note that if the URL that you redirect to must be part of your web application or the function won't be executed. This is because the function is only registered locally.

param

func - The function to be executed when the redirect is accessed.

where - The new URL to redirect to.

see

- # seeOther ( String )

Note that the underlying mechanism for redirects is to throw a ResponseShortcutException, so if you're doing the redirect within a try/catch block, you need to make sure to either ignore the redirect exception or rethrow it. Two possible approaches would be:

     ...
     try  {
       // your code here
       S.seeOther(...)
   } catch  {
       case e: Exception if !e.instanceOf[net.liftweb.http.ResponseShortcutException] => ...
   }
   

or

     ...
     try  {
       // your code here
       S.seeOther(...)
   } catch  {
       case rse: net.liftweb.http.ResponseShortcutException => throw rse
       case e: Exception => ...
   }
   

param

where - The new URL to redirect to.

see

- ResponseShortcutException

- # seeOther ( String, ( ) => Unit)

see

- # unset

- # getSessionAttribute

- # setSessionAttribute

- # unsetSessionAttribute

- # get

If this is not set, the DocType for Lift responses defaults to XHTML 1.0 Transitional.

see

- ResponseInfo.docType

- DocType

- getDocType

For example, you could set a "Warn" header in your response:

     ...
     S.setHeader("Warn", "The cheese is old and moldy")
     ...
   

see

- # getHeaders

see

- # unset

- # getSessionAttribute

- # set

- # unsetSessionAttribute

- # get

Note that this does not modify the current attributes available via S.attr.

param

attr - The attributes to set temporarily

If this is set to true, Lift will not emit a DocType definition at the start of the response content. If you're sending XHTML and this is set to true, you need to include the DocType in your template.

param

skip - Set to true to prevent Lift from emitting a DocType in its response

see

- # skipDocType

see

- # setSessionAttribute

- # getSessionAttribute

- # set

- # unsetSessionAttribute

- # get

see

- # setSessionAttribute

- # getSessionAttribute

- # set

- # unset

- # get