About: Lift Tags

Lift tags are tags built into Lift that ship by default and are available for use in your application templates.

Surround

<lift:surround with="template_name">children</lift:surround>

Uses: Surrounds the child nodes with a named template (located in the /templates-hidden directory of webapp).
It is used to apply a unified template to all the page in a site

Example

<lift:surround with="default">
  <b>Dude</b>... this is my page... but it'll appear in your 
  browser in a template.
</lift:surround>

Caveats: In the target template there must be a <lift:bind /> tag to indicate where the contents should be bound. Note that you can use multiple surround templates by adding them to the /templates-hidden directory. For example, you might want to have a separate template for your administrative pages. In that case, you might add that template as admin.html in the /templates-hidden directory and then call it from your other pages using:

<lift:surround with="admin">page code here</lift:surround>

Beware! You cannot have a hidden template with the same name as a sub-directory of your webapp directory. For example, if you had an admin.html template in /templates-hidden, you could not also have an admin directory.

with-param/bind-at

Typically in the template-hidden we use to mark the place where we want to render different contents depending on what page are we accessing. On one hand we have:

in the default template:

<lift:bind name="something"/>

<lift:bind name="something-else"/>

in index.html (the actual page that we need to render)

<lift:surround with="default" >
  ... content 1 ...
  <lift:bind-at name="something">
   ... content 2 ...
  </lift:bind-at>
  ... content 3 ...
  <lift:bind-at name="something-else">
   ... content 4 ...
  </lift:bind-at>
  ... content 5 ...
</lift:surrond>

Using bind-at or with-param element we can specify what content goes where when we have multiple bind points.

As you notices and are doing exactly the same thing. In time with-param may be deprecated.

Embed

<lift:embed what="template" />

Uses: Allows you to embed a template within another template (or to access a template from a JsCmd such as SetHtml, ModalDialog, etc.) Note that incoming requests that contain *-hidden in the request will not be serviced, but you can access templates in directories named *-hidden. So, you can put AJAX templates in /ajax-templates-hidden in webapps.

Also, Lift’s i18n support extends to templates as well, so you can specify “/ajax-templates-hidden/welcome”
and lift will serve the appropriate localized template. For example, if the current locale is set to French Canadian Lift will look for /ajax-templates-hidden/welcome_fr_CA.html, /ajax-templates-hidden/welcome_fr.html, and
/ajax-templates-hidden/welcome.html

Example

<lift:embed what="/ajax-templates-hidden/welcome" />

Caveats: JavaScript contained in templates rendered via JsCmd (sent in response to AJAX requests) will not be executed. This includes Comet Widgets.

Comet

<lift:comet type="ClassName" name="optional"/>

Caveats: if you have a <lift:comet /> tag and you’re using the tag from within sending AJAX stuff back, things might not work well.

Ignore

<lift:ignore>children</lift:ignore>

Uses: To have child tags that a browser may parse if the local file is loaded, but should not be included in the rendered code.

This is useful in two areas:

• To put comments in the page that should not be rendered out the the browser
• To have CSS and other stuff in the page even though the page will be surrounded by a template

Example

<lift:ignore>
<!-- The database info is scott/tiger -->
</lift:ignore>

Snippet

<lift:snippet form="METHOD" type="ClassName:method" multipart="true" />

form and multipart are optional attributes. For a more detailed explanation, please see About: Snippets

Children

<lift:children>children</lift:children>

Uses: An XML file must contain only 1 root element. If you have a file that contains, for example:

<div>This is the first DIV</div><div>This is the other DIV</div>

The file will not parse correctly. So, you can wrap the file in <lift:children/> and the child nodes will be returned. Stand-alone templates may be returned via <lift:embed what="/ajax-hidden/comfirm-delete"/> in SetHtml and other JsCmds that take a NodeSeq.

Example

<lift:children>
  <div>This is the first DIV</div>
  <div>This is the other DIV</div>
</lift:children>

Loc

<lift:loc id="What"/>

Head Merge

Since version 0.4, it is possible to declare several <head> sections anywhere under body (and its children), and every <head> section will be merged into the /html/head standard location at render time. The head section could be created in the html or in scala code (such as a snippet).

Example

Take the file: /webapp/template-hidden/default.html

  <html>
    <head>
      <title>foo</title>
    </head>
    <body>
      <lift:bind name="content" />
    </body>
  </html>

and: /webapp/index.html

  
<lift:surround with="default" at="content">
  <head>
    <script src="myscript.js"></script>
    <style>
      <!-- css goes here -->
    </style>
  </head>
  <h2>Welcome to the your project!</h2>
</lift:surround>

Will ultimately be rendered like:

<html>
  <head>
    <title>foo</title>
    <script src="myscript.js"></script>
    <style>
      <!-- css goes here -->
    </style>
  </head>
  <body>
    <h2>Welcome to the your project!</h2>
  </body>
</html>