Lift offers several ways for programmers to define which pages their applications will have. SiteMap is one of these ways. Besides defining the pages of your application, you can also control the access of each URL. This means that you can, for example, control whether a URL will have access restrictions or not and even control the restriction level of any given URL.
What does this mean? This means that you can think of SiteMap as the defined structure of your application containing every URL that will be accessible and the policies that are applied for each one of them.
Another thing that SiteMap does is automatic mapping between URLs and XHTML templates.
In this recipe, we will see how to configure SiteMap for a simple application. For this, let's suppose we want to create an application to store and manage contacts.
We will need one URL for each of the following actions:
List contacts
Create contacts
Edit contacts
Delete contacts
View contacts' details
Copy the contents of the lift_blank folder from the scala_29 folder to a new directory called contacts-app.
Carry out the following steps:
Edit the
Boot.scalafile by adding a function,LocParam, just before the declaration of theentriesvalue:val canManage_? = If(() => { true }, () => RedirectResponse("/"))This is to verify whether the user accessing the URL has management permission and is allowed to access it.
Then, add another
LocParamto check whether the user has administrative privileges:val isAdmin_? = If(() => { false }, () => RedirectWithState("/contacts/list",MessageState("Authorized personnel only" -> NoticeType.Warning)))After creating the functions, we'll define SiteMap by adding new menu items between the
Menu.i("Home") / "index"and theMenu(Loc("Static", …entries.Menu items that need to be added are as follows:
Menu.i("List Contacts") / "contacts" / "list", Menu.i("Create") / "contacts" / "create" >> canManage_?, Menu.i("Edit") / "contacts" / "edit" >> canManage_?, Menu.i("Delete") / "contacts" / "delete" >> isAdmin_?, Menu.i("View") / "contacts" / "view" >> canManage_?,Create a folder called
contactsinside thewebappfolder.Create five HTML files, one for each menu item defined in SiteMap:
list.htmlcreate.htmledit.htmldelete.htmlview.html
Then run the application and go to the URL
http://localhost:8080in your browser. The following screen will be displayed:
Lift will build the SiteMap object during the application boot process as a result of the invocation of the method, LiftRules.setSiteMap.
When a user tries to access, for example /contacts/list, Lift will use SiteMap to decide whether the resource is defined or not by matching the URL against the link list defined by the menu entries in SiteMap. Since we've defined it, Lift will serve the page to the user. However, if the user tries to access /contacts/lists, the match will fail and Lift will return a 404 error.
We still need to understand what the LocParam functions are that were mentioned in steps 1 and 2. LocParam is something that modifies how Lift handles the given entry of SiteMap. In our case, it is a function that redirects the user to a different URL if the condition being tested fails. So, if someone tries to access /contacts/create, Lift will execute the canManage_? function after matching the URL. If the function returns true, Lift will serve the page to the user; otherwise, it will redirect the user to /. The same logic applies to the view and edit URLs.
The same logic applies to the delete link; the only difference being the fact that the isAdmin_? function not only redirects the user to /, but also passes a message that will be displayed in the page. This happens because we've used If LocParam that takes two arguments. The first is a test function. If it returns true, the page can be accessed; and if the return value is false, the result of evaluating the second parameter, FailMsg, will be sent to the browser.
The entries variable is a list of menu items that will be processed when the application is started by Jetty.
Each menu item has a structure as shown in the following image.
Unique identifier
Link object
Text
Parameters
The unique identifier is used by Lift to keep a track of all the menu entries in SiteMap.
The Link contains the list that will be used to match the requested URL to check if it is defined or not.
The match head parameter, which is a Boolean value, defines whether Lift will match the exact URL or everything beginning with the given path. Notice that if you pass true, Lift will serve URLs containing /contacts/create or /contacts/create/*, where * is any HTML file existing inside webapps/contacts/create. If no such folder exists, Lift will return a 404 error. If you pass false, Lift will only serve /contacts/create and will return the 404 error for any other URL containing /contacts/create.
The URL that will be used to create the link on the page will be the value rendered in the href attribute of the anchor tag, <a href={url}>...</a>.
text is the text that will be shown when the link is displayed.
The parameters are functions, LocParam, that you want to execute when rendering the link or accessing the page.
Lift comes with several types of the LocParam functions, such as MenuCssClass to add a CSS class to the Menu and Title to define the title of the page.
To learn more about SiteMap, Menu, and the LocParam functions, please go to https://www.assembla.com/wiki/show/liftweb/SiteMap.