Learning Lift - HelloLift Lesson 3

Learning Lift – HelloLift Lesson 3

Overview

In HelloLift Lesson 1, we used Git to clone a Lift prototype project to create our HelloLift application. In Lesson 2 we made some minor changes to the application and continued to manage the changes using Git for version control. In Lesson 3 we will make some changes to the menu and learn a little about Lift’s configuration module and sitemap along the way. I hope you enjoy this lesson.

Learning Something

Learning Something tutorials like this one are prepared while I am learning something new. Because I am a newbie at whatever I am learning, these tutorials tend to be very basic. They are step-by-step instructions prepared by a newbie. Consequently, they may not show the best way to do something. They just show how I understood things at the time. Still, I hope you will benefit from my sharing of these tutorials and I hope you will add comments where you know a better way so we can all learn from each other.

I hope you enjoy and benefit from the Learning Something tutorials. Enjoy!

References

The following references were used to compile this document:

Pre-requisites

You need to complete HelloLift Lessons 1 and 2 in order to follow this lesson.

Part 1: Background

Step 1.1: Refresh our Memory

When we ran our application at the end of Lesson 2 it appeared as follows.

Go ahead and restart the HelloLift application so that you have the above page in your browser. You can follow the instructions in the earlier lessons if needed. In summary, the instructions are:

Launch a command prompt
Change to your project directory
Enter sbt at the command prompt in your project directory and click enter
Enter update at the SBT prompt and click enter
Enter jetty-run at the SBT prompt and click enter
Open your favourite browser and point it at http://localhost:8080/ to see your application as shown above.

Once you have started the application, click on the Sign Up menu item. You should see the following screen.

Enter the required details, including a new password and repeat password, and then click the Sign Up button. Once you have successfully signed up, you should be back at the Home page as shown below.

Notice that there is a Welcome message below the menu. This is displayed each time you log in. Other messages are also displayed here as needed.

Notice also that the Login, Sign Up and Lost Password menu items have been replaced by the Logout, Edit User and Change Password menu items because we are now logged in.

Step 1.2: Proposed Changes

We will make the following changes to the application in this lesson:

Move the Login, Signup and Lost Password menu items shown above away from the main menu and place them at the top right hand corner of the page
Similarly move the Logout, Edit User and Change Password menu items
Move the Home and Static Content menu items to the top of the page as a horizontal menu bar. We will have to move our application name a little to the left to make room for this menu bar
Add two more menu items for Customers and Product Catalogue. We will add content to these pages in future lessons
Add links for Help and Contact Us to the footer.

If all goes according to plan, at the end of this lesson, our menu and links will take up less room on our site and leave more space for the content we want to highlight.

We will expect to see three columns at the top of our page. The left column will show our application name, HelloLift. The middle column will display the horizontal menu bar. The right column will display the User login, logout and related links.

We will also expect to see the Help and Contact Us links in the footer. They will appear to the right of the HelloLift copyright text already displayed in the footer.

Part 2: Make the Changes

We will start by adding the required columns on our Web page. We will then add the links and menu items into their desired positions on the Page. Once we are satisfied that the top menu bar and the footer are correctly displayed and functioning, we can then remove the current sidebar menu from the page.

Step 2.1: Prepare the Columns at the Top of the Page

As we mentioned above, we want to have three columns at the top of our page. The first will contain the application name, the second will contain the horizontal menu bar and the third will contain the User menu items. The columns can be added by modifying the default.html template in the src/main/webapp/templates-hidden directory of our project. Follow the steps below to add the columns.

Step 2.1.1: Launch Git Gui

Launch Git Gui if it is not already running and open the HelloLift project repository. Your Git Gui screen should be as shown below.

Notice the HelloLift project directory appears in the title bar of the Git Gui window and we are in the master branch of the repository.

Step 2.1.2: Open the default.html File

Click on the Repository item in the Git Gui menu bar and select Explore Working Copy from the drop down menu. This will open the project directory in Windows Explorer as shown below.

Open the src/main/webapp/templates-hidden sub-directory and locate the default.html file as shown below.

Open the default.html file using your favourite editor. The file should appear as shown below.

Scroll down to view the rest of the file contents.

Step 2.1.3: Modify the default.html File

We will now make the desired changes to the default.html file. Start by adding the following immediate after the opening <div class=”container”> tag to create the three columns we desire.

top left

</div>

middle column

</div>

top right

</div>

This code adds three columns at the beginner of the container div. Styling for the columns is provided courtesy of the blueprint Cascading Style Sheet (CSS) injected by the following tag <lift:CSS.blueprint /> at line 8 of our default.html file.

You can learn more about blueprint CSS at http://www.blueprintcss.org/.

The modified default.html file is shown below.

Make sure to Save your changes.

Step 2.1.4: Verify our Changes

Let’s run the application and verify our changes were effective.

If you have not already started the application, go ahead and do so now. If needed refer to the instructions in Step 1.1 on how to launch the application.

Otherwise, if your application is already running, go to the Command Prompt from which you started the Jetty server. It should appear as shown below.

In the same Window, enter the jetty-stop command as shown below.

Click the enter key to stop the Jetty server. The Command Window should appear as follows.

At the SBT command prompt, enter jetty-run and click the enter key to start the server again. The Command Window should appear as shown below.

Now point your browser to http://localhost:8080/ and you should see the columns we have added to the top of our page as shown below.

Notice the words “top left”, “middle column” and “top right” appear in the top row of our page. Great, we have successfully added the three columns with some text as placeholders.

Step 2.2: Fill the Columns at the Top of the Page

Now that we have set up the three columns at the top of the page, let’s fill the columns as planned:

the first will contain the application name
the second will contain the horizontal menu bar
the third will contain the User menu items.

Step 2.2.1: Display the Application Name in the Left Column

Open the default.html file in the src/main/webapp/templates-hidden sub-directory of our project and locate the div tags we added in step 2.1.3 above. The div tags are highlighted in the image below.

Replace the div tags that define the top left column with the following:

<h2 class="alt">HelloLift<img alt="" id="ajax-loader" style="display:none; margin-bottom: 0px; margin-left: 5px" src="/images/ajax-loader.gif"/></h2>

</div>

The revised default.html module should appear as shown below.

Make sure to Save your changes.

Step 2.2.2: Verify our Changes

Let’s run the application and verify our changes were effective. When you stop and start the Jetty server, and then launch (or refresh) the application by navigating to the http://localhost:8080/ you should see the following on your Web page.

Great! Our HelloLift application name now appears in the top left column of the page.

Notice, however, that our page is starting to look cluttered. Let’s address that in the next step.

Step 2.2.3: Remove the Application Name from Top Centre of Page

Now that we have the application name appearing at the top left of the page, we don’t really need the application name that appears near the top centre of the page. Let’s remove it to reduce the clutter on our page.

The HelloLift application name that appears near the top centre of the page is generated by the div tags highlighted in the default.html file image below.

To remove the HelloLift application name from the top centre of the page, delete the highlighted div tags in the image above. The file should appear as follows after the specific div tags are removed.

Step 2.2.4: Verify our Changes

Let’s run the application again and verify our changes so far. The application should now appear as shown below.

Success! We have added the HelloLift application name at the top left of the page and removed it from the centre of the page.

Step 2.2.5: Display the Menu in the Centre Column

Our next step is to add the horizontal menu bar in the top middle column.

Open the default.html file in the src/main/webapp/templates-hidden sub-directory of our project and locate the div tags that define the three columns at the top of our page. The div tags are highlighted in the image below.

Replace the div tags that define the middle column with the following:

<lift:Menu.builder />

</div>

The revised default.html module should appear as shown below.

Make sure you Save your changes.

Notice that we have applied the topMenu style as part of our changes. However, we have not yet defined the topMenu style. Let’s do that now.

Step 2.2.6: Define the Style for the Horizontal Menu

Currently, the default.html file includes a definition of the sidebar style. This style is applied to the menu displayed on the left side of the page. The style elements are shown highlighted in yellow in the image below.

We will need to create a similar style for the horizontal menu that we want to display at the top centre of the page.

Edit the default.html file and add the topMenu styles immediately after the last sidebar style as shown in the image below.

Make sure you Save your changes.

The topMenu style elements are repeated below for your ease of reference.

.topMenu ul {

margin:0;

padding:0;

border-bottom:none;

}

.topMenu ul li {

margin:0;

padding:0;

list-style:none;

border:none;

border-bottom:none;

}

.topMenu ul li a {

display:inline;

float: left;

padding-right:6px;

text-decoration:none;

}

.topMenu ul li span {

display: inline;

float: left;

padding-right: 6px;

text-decoration: none;

}

.topMenu ul li a:hover {

background-color: #eee;

}

The second last and third last style elements set the inline style. When applied, these styles will cause the menu to display horizontally.

The last style element defines the background colour for a menu item when the mouse hovers over the item.

Step 2.2.7: Verify our Changes

Let’s run the application again and verify our changes so far. The application should now appear as shown below.

Wow! We have the menu displaying at the top of the page. Now we have two menus on the page. Later, we will remove the menu from the sidebar so that we can have more space for our Web page content. For now however, let’s update the contents of the top right column.

Step 2.2.8: Display the User Menu Items in the Top Right Column

Our next step is to add the User menu items in the top right column.

Replace the div tags that define the top right column with the following:

<lift:Menu.item name="Login"/>

<lift:Menu.item name="CreateUser"/>

<lift:Menu.item name="LostPassword"/>

<lift:Menu.item name="Logout"/>

<lift:Menu.item name="EditUser"/>

<lift:Menu.item name="ChangePassword"/>

</div>

The revised default.html module should appear as shown below.

Make sure to Save your changes.

Step 2.2.9: Verify our Changes

Let’s run the application again and verify our changes so far. The application should now appear as shown below.

Excellent! We have added the three columns and placed the desired content in each column.

Step 2.2.10: Display Messages at the Top of the Page

Currently, we display any messages from our application below the sidebar menu. This is achieved through the <lift:Msgs showAll=”true”/> tag in the default.html file as shown below.

Let’s copy the <lift:Msgs showAll=”true”/> tag and the corresponding <div> tags surrounding it, to appear just below the HelloLift application name. The revised file is shown below.

Make sure to Save your changes.

Step 2.2.11: Verify our Changes

Let’s run the application again and verify our changes so far. The application should now appear as shown below.

Let’s login and see if the message appears as expected.

Click on the Login menu item to see the following screen.

Enter your login details (email and password) then click enter. You should see the following screen.

Notice that the message “Logged In” appears just below the header, in addition to its usual placement below the sidebar menu.

Step 2.2.12: Remove the Sidebar Menu & Message

Now that we have added the horizontal menu bar and messages section at the top of our page, we can remove the sidebar menu.

Open the default.html file and navigate to the appropriate section of where the sidebar menu is implemented as shown below.

Remove the tags that define the sidebar menu. These are highlighted in the image above. After removing the tags, the default.html file will appear as shown below.

Make sure to Save your changes.

Step 2.2.13: Verify our Changes

Let’s run the application again and verify our changes so far. The application should now appear as shown below.

Let’s login to confirm that the messages are still displayed at the top of our page.

Excellent! We have moved our menu and message text to the top of our HelloLift application page.

Step 2.2.14: Don’t Display the User Menu items in the Main Menu

Currently, the User menu items are appearing twice on our page: in the main menu and also at the top right corner of the page. Let’s remove these duplicate entries from the main menu.

Step 2.2.14.1: Create a Main Menu Group in SiteMap

Open the Boot.scala file in the src\main\scala\bootstrap\liftweb sub-directory of the project. Navigate to the highlighted SiteMap section in the image below.

Add the Home and Static Content menu items to the mainMenu Location Group by placing:

>> LocGroup(“main menu”) after the Home menu item and
, LocGroup(“mainMenu”) at the end of the Loc for the Static Content menu item.

The revised file is shown below.

Make sure to Save your changes.

Step 2.2.14.2: Update our Template to Show the MainMenu Group Only

Open the default.html file in the src\main\webapp\templates-hidden sub-directory of the project. Navigate to the <lift:Menu.builder /> tag and change it to <lift:Menu.builder group=”mainMenu”/> as shown in the image below.

Make sure to save your changes.

Step 2.2.15: Verify our Changes

Let’s run the application again and verify our changes so far. The application should now appear as shown below.

Notice that only the Home and Static Content menu items remain in the main menu. This is what we wanted to achieve. We now have space to add more items to our main menu.

Step 2.2.16: Add Customers and Product Catalogue to the Main Menu

In this step we will add Customers and Product Catalogue menu items to the main menu and add the pages that the user will see when they select these menu options.

Step 2.2.16.1: Add New Menu Items to the Application SiteMap

Let’s add the Customers and Product Catalogue menu items to the application SiteMap. Open the Boot.scala file located in the src/main/scala/bootstrap/liftweb directory and locate the SiteMap as shown below.

Modify the SiteMap by adding the following entries immediately after the Home menu.

Menu.i(“Customers”) / “customers” >> LocGroup(“mainMenu”),

Menu.i(“Product Catalogue”) / “products” >> LocGroup(“mainMenu”),

Make sure to include the commas at the end of both lines.

The revised SiteMap is shown below.

Make sure to Save your changes.

Step 2.2.16.2: Add New Pages to the Application View

Now we will create the customers and products pages that the user sees when they select the new menu items.

Step 2.2.16.2.1: Add New Pages to the Application View

Let’s start by creating the customers.html page in the src/main/webapp sub-directory of our project folder as shown below.

I created the customers.html by copying the index.html in the same directory and renaming it. You can do the same or simply create a new empty file called customers.html.

Using your favourite editor, open the customers.html file you just created and replace its contents with the following:

<lift:surround with="default" at="content">

<h2>Customers</h2>

<p>

Customers list and details will be accessible from this page.

</p>

</lift:surround>

The file is as shown below.

Make sure to Save your changes.

Let’s take a moment to understand the contents of the customers.html page. The page is enclosed in the <lift:surround with=”default” at=”content”> tag. This tag tells Lift that the contents of this page are to be surrounded by the page identified by the with attribute, in this case, default.html. Furthermore, the at attribute tells Lift where to place the contents in the surrounding page. In this case, the at attribute is set to content so Lift will display the customers.html page in the content part of the default.html template page. The content section of the default.html template is highlighted in the image below for your reference.

The highlighted section shown in the default.html template image above is where Lift will bind the contents of our customers.html page. You do not need to make any change to default.html. The above is just to show you how lift knows where to place the content of our customers.html page.

Step 2.2.16.2.2: Add New Pages to the Application View

Now that we have completed the setup of the customers.html page, we can follow similar steps to create the products.html page. Make a copy of the customers.html page in the src/main/webapp sub-directory and rename the copy to products.html. Open the new products.html file and change the contents to be as follows:

<lift:surround with="default" at="content">

<h2>Product Catalogue</h2>

<p>

Product list and details will be accessible from this page.

</p>

</lift:surround>

The file is as shown below.

Make sure to Save your changes.

Step 2.2.17: Verify our Changes

Let’s run the application again and verify our changes so far. The application should now appear as shown below.

Notice that the Customers and Product Catalogue menu items have been added to the main menu. Let’s click on the Customers menu item to verify that menu item displays the correct page as shown below.

Now click on the Product Catalogue menu item to verify that it is also linking to the correct page as shown below.

Excellent! We have added the two new menu items and the pages that correspond to these items.

Step 2.2.18: Add Help and Contact Us in the Footer Section

In this step we will add the Help and Contact Us links to the footer on the HelloLift application pages. We will achieve this by adding Help and Contact Us to the HelloLift SiteMap, creating the two pages that correspond to these links, and finally adding the links to the footer in the default.html template. We have performed similar steps in the earlier parts of this tutorial so the activities we do here should be familiar to us.

Step 2.2.18.1: Add Help and Contact Us Items to the Application SiteMap

We will add Help and Contact Us to the SiteMap so that Lift can display these pages when they are requested. So once again, let’s open the Boot.scala file located in the src/main/scala/bootstrap/liftweb directory and locate the SiteMap as shown below.

Modify the SiteMap by adding the following entries immediately after the Home menu.

Menu.i(“Help”) / “help” >> LocGroup(“footerMenu”),

Menu.i(“Contact Us”) / “contactus” >> LocGroup(“footerMenu”),

Make sure to include the commas at the end of both lines. Notice that we have also created a new LocGroup for the footer menu.

The revised SiteMap is shown below.

Make sure to Save your changes.

Step 2.2.18.2: Add New Pages to the Application View

Now we will create the help and contactus pages that the user sees when they select the new menu items.

Let’s start by creating the help.html and contactus.html pages in the src/main/webapp sub-directory of our project folder as shown below.

I created both pages by copying the customers.html page that we created earlier. You can do the same or simply create two new empty files called help.html and contactus.html.

Using your favourite editor, open the help.html file you just created and replace its contents with the following:

<lift:surround with="default" at="content">

<p>

Help information will be accessible from this page.

</p>

</lift:surround>

The file is as shown below.

Make sure to Save your changes.

Similarly, open the contactus.html file and change the contents to be as follows:

<lift:surround with="default" at="content">

<h2>Contact Us</h2>

<p>

Our contact details will appear here.

</p>

</lift:surround>

The file is as shown below.

Make sure to Save your changes.

Step 2.2.18.3: Add Links to the Application Footer

Now we will add the Hello and Contact Us links to the footer in the default.html template so they appear on all pages that are surrounded by the template.

The footer of our application currently displays the HelloLift copyright statement centred at the bottom of the page and is composed of one <div> tag as shown below.

Change the footer to be as follows:

<a href="http://localhost:8080/"><i>HelloLift</i></a>

</h4>

</div>

<lift:Menu.builder group="footerMenu"/>

</div>

Notice that we have used the bottom class from BlueprintCSS to format the footer and created two columns, the first to display the copyright notice and the second to display the footer menu.

Notice also that we have used the topMenu class to format the footer menu. This is because the topMenu class creates a horizontal menu instead of a vertical list. Maybe it would have been better to call the class horizontalMenu instead of topMenu. We will leave that refactoring for another time. For now, take a look at the default.html template below and make sure you have the same contents in your template.

Make sure to Save your changes.

Step 2.2.19: Verify our Changes

Let’s run the application again and verify our changes so far. The application should now appear as shown below.

Notice that the Help and Contact Us menu items have been added to the footer. Let’s click on the Help menu item to verify that menu item displays the correct page as shown below.

Now click on the Contact Us menu item to verify that it is also linking to the correct page as shown below.

Excellent! We have added the two new menu items to the footer and the pages that correspond to these items.

That concludes the modifications we want to make as part of this tutorial. The application now matches the objectives we set out for ourselves at the beginning of the tutorial.

Part 3: Source Code Management

Now that we have a completed our changes and have a new version of the application, let’s commit our changes using Git.

Step 3.1: Launch Git

Launch Git Gui and open the hellolift repository as shown below.

If Git Gui is already running, you can click on the Rescan button to make sure that Git Gui is displaying the latest changes to the application.

We can see from the image above that there are six unstaged changes. These are the two modified files (Boot.scala and default.html) and four new files (customers.html, products.html, help.html and contactus.html).

Step 3.2: Stage our Changes

Select the documents listed in the Unstaged Changes panel in the first column of the Git Gui screen. Now click the Stage Changed button. The modified documents should now move to the Staged Changes (Will Commit) panel while the new documents remain in the Unstaged Changes panel as shown below.

Correction: Note that we have only partially staged our changes. To stage the new files, we should click on the white icon next to each file name in the Unstaged Changes panel. Go ahead and do that now. All documents should be in the Staged Changes (Will Commit) panel only.

Step 3.3: Commit our Changes

Enter our text to describe this commit in the Commit Message box. The suggested text for your commit message is:

Restructure the View

Remove the sidebar menu and restructure the application to free up space for content on each page.

Once you’ve entered the commit message, the Git Gui screen should appear as shown below. Note that if you have applied the correction that appears at the end of Step 3.2, your screen should not show any Unstaged Changes remaining.

Now that we have entered our commit message text, click on the Commit button to commit our changes. Once the commit is complete, the Git Gui screen should be as shown below. Again, if you applied the correction given at the end of Step 3.2 your screen will have no Unstaged Changes remaining.

Clearly, we want the Unstaged Changes to also Commit but they have not yet Committed. Oops! We have made a mistake and committed only part of our changes. Of course, if you applied the correction that we gave earlier you will not have made the same mistake as me.

Step 3.4: Fix our Mistake

In the previous step we committed only the modified files but missed the new files that should also have been included in the commit. We will recover from our mistake in this section. However, if you have made the correction at the end of Step 3.2 already, then you will not need to do anything here.

If on the other hand, you ever encounter a mistake like the one I made, you will be happy to learn that Git Gui allows us to make corrections to the previous commit.

Let’s correct our mistake now. First we will click on the white icon next to each new document listed in the Unstaged Changes panel. Git Gui will move the documents to the Staged Changes (Will Commit) panel. Once all documents have been staged in this manner, click on the Commit menu and select Amend Last Commit from the drop down menu. Git Gui will now appear as below.

Notice that our previous commit message is retrieved for us and the radio dial above it is set to Amend Last Commit instead of New Commit.

Go ahead and click the Commit button to commit the changes, including the new files that we missed earlier.

Once the commit is successfully completed, the Git Gui screen will be clear as shown above. We have now amended the previous commit. All our changes have now been committed.