Read more about this book

For the following exercise, you’ll need to download Chapter 7’s support code from the book’s website. Extract the chapter07.zip file’s contents into a directory in your hard disk. For example, I used Ubuntu Linux in the exercise, created a chapter07 directory inside my Desktop directory, and copied the mytheme directory inside Desktop/chapter07. All the steps in the exercise are based on these assumptions.

Creating a directory for your theme

Every Roller theme has a directory and some required files such as weblog.vm, _day.vm, and theme.xml. The next exercise will show you how to create a directory for your new theme inside Roller’s themes directory, and how to copy these required files from the support files.

Time for action – creating a directory for your theme

Now, I’ll show you all the necessary steps to create your new theme directory inside Roller’s themes directory in a Linux Ubuntu system, and then copy all the required files. If you’re using Windows or any other flavor of Linux, the procedure is very similar:

1. Go to your Roller themes directory and create a directory named mytheme:

   

2. Open a terminal window, go to the themes subdirectory inside Desktop/chapter07, and type sudo cp * /usr/local/tomcat/webapps/roller/themes/mytheme to copy all the mytheme files to your Roller installation:

   

3. In the end, your mytheme directory will have four files, as shown in the following screenshot:

   

4. Now restart Tomcat and wait until it’s running again. Then open your web browser, log into Roller, and go to the Design tab to see the Weblog Theme page:

   

5. Click on the Shared Theme option and select My First Roller Theme from the drop-down listbox:

   

6. Click on the Update Theme button to change your current Roller theme, and then click on the See how your blog will look with this theme link:

   

7. Roller will open a new web browser tab to show you a preview of the new theme you selected:

   

8. Close the preview tab and leave the Front Page: Weblog Theme page open for the next exercise.

What just happened?

The mytheme theme has a very basic functionality. That’s because the CSS stylesheet (mystylesheet.css) is empty, so I’m going to show you how to add styles to your headings, links, and all the other elements displayed in your weblog. However, first we need to see a quick introduction to the four files that every Roller theme must have in order to run without any trouble:

File	Definition	Tip
weblog.vm	Describes the main page of your weblog.	In this file, you set the structure for your weblog, using macros and elements from Roller and the Velocity template language.
_day.vm	Describes how to display one day’s worth of entries in your weblog.	Here you can configure how to display each entry’s title, content, and comments, for example. You can set the font’s color and size of each element, based on the CSS stylesheet definitions.
mystylesheet.css	Stylesheet override file that defines the CSS style code used by your weblog.	Here you define all your weblog’s styles, such as size and color for headings and fonts used in your posts.
theme.xml	Theme definition file that describes each file used in your weblog.	You need to include some basic data about your theme, the stylesheet file, the weblog and _day templates, and every other file and/or resource used in your weblog.

The stylesheet override file

The first thing we need to do in order to change your new theme’s visual appearance is edit the stylesheet override file: mystylesheet.css. We can do this in two ways: Edit the file directly from the mytheme directory inside Roller’s themes directory, or use Roller’s Custom Theme feature. If we use the first option, we’ll need to restart Tomcat every time we make a modification to mystylesheet.css. On the other hand, if we choose the second option, we can edit the stylesheet inside Roller’s admin interface and see how our changes affect our weblog’s visual appearance immediately, so I’m going to show you how to use the second option.

Time for action – editing the stylesheet override file

It’s very easy to edit the stylesheet override file for your custom theme inside Roller, and the next exercise will show you how to do it:

1. Go to the Front Page: Weblog Theme tab in your web browser, select the Custom Theme option, click on the I want to copy the templates from an existing theme into my weblog checkbox, and click on the Update Theme button:

   

2. Roller will show you the following success message:

   

3. Now click on the Templates link to see a list of the templates you currently have in your custom space:

   

4. Looking at the template list in the previous screenshot, there are some templates from the other custom theme and we need to remove them now. Click on the Remove link of the custom.css, mytemplate, and _css templates to delete them from your custom space, as we won’t need them anymore, and they don’t belong to mytheme.
5. After removing all the unneeded files, there should be only two templates in your list:

   

6. Now click on the Stylesheet link to see and start editing your mystylesheet.css file’s code:

   

7. As you can see, your custom stylesheet is empty. If you click on the Front Page link in Roller’s menu bar, you’ll see your weblog’s current front page:

   

8. Now click on your web browser’s Back button to return to the stylesheet editing page, and add the following code to your custom stylesheet:

   div.dayTitle {
      color:brown;
      font-weight:bold;
      font-size:90%;
      text-transform:uppercase;
      border-bottom:1px dotted #666;
   }
   .entryTitle {
      font-weight: bold;
   }

9. Your stylesheet should now contain the line beginning with /*, along with the code you’ve just entered:

   

10. Click on the Save button to apply the changes to your stylesheet, and then select the Front Page link to see how the code you entered affects your weblog’s visual appearance:

    

11. If you compare the previous screenshot with the one from step 7, you’ll see that the code you entered into the override stylesheet changed the way your weblog displays the day and entry titles. Now click on the Back button of your web browser to return to the stylesheet editing page, and add the following lines of code above the lines you entered in step 8:

    a {
      text-decoration: none;
    }
    
    a:link {
      color: blue;
      font-weight: medium;
    }
    
    a:visited {
      color: purple;
      font-weight: medium;
    }
    
    a:hover {
      text-decoration: underline overline;
    }
    
    body {
      font-family:"Lucida Grande", lucida, Geneva, Arial,
      sans-serif;
      background:#FFFFCC;
    }

12. Your stylesheet should now look like this:

    

13. Click on the Save button and then select the Front Page link to see your weblog’s front page:

    

14. Click on the Back button to return to your stylesheet editing page.

What just happened?

In the previous exercise, you edited your stylesheet override file (mystylesheet.css) to change your weblog’s visual appearance. To understand what these code segments do, let’s take a look at the _day template’s code:

<div class="dayBox">
  <div class="dayTitle">
   $utils.formatDate($day, "EEEE MMM dd, yyyy")
  </div>
  #foreach( $entry in $entries )
  <div class="entryBox">
    <p class="entryTitle">$entry.title</p>
    <p class="entryContent">
    #if($model.permalink)
     $entry.displayContent
    #else
     $entry.displayContent($url.entry($entry.anchor))
    #end
  </p>
  <p class="entryInfo">
    Posted at
     <a href="$url.entry($entry.anchor)">$utils.formatDate
     ($entry.pubTime, "hh:mma MMM dd, yyyy")</a>
   by $entry.creator.userName in <span
     class="category">$entry.category.name</span>
      &nbsp;|&nbsp;
   #if ($utils.isUserAuthorizedToAuthor($entry.website))
      <a href="$url.editEntry($entry.anchor)">Edit</a>
         &nbsp;|&nbsp;
   #end
   #if($entry.commentsStillAllowed || $entry.commentCount >
       0)
   #set($link = "$url.comments($entry.anchor)" )
      <a href="$link"
       class="commentsLink">Comments[$entry.commentCount]
       </a>
    #end
   </p>
  </div>
  #end
</div>

The lines in bold are the ones directly involved with the CSS code you entered in the exercise:

<div class="dayTitle">
   $utils.formatDate($day, "EEEE MMM dd, yyyy")
</div>

The div element represents a “division” or a section in a web page. The only code inside this division is $utils.formatDate($day, “EEEE MMM dd, yyyy”). This is a property from the $utils object used to show the date and time of each day containing one or more posts in the weblog, in the format specified by the “EEEE MMM dd, yyyy” string.

The class=”dayTitle” code segment indicates that this division will use the styles defined in the .dayTitle class from the stylesheet:

div.dayTitle {
  color:brown;
  font-weight:bold;
  font-size:90%;
  text-transform:uppercase;
  border-bottom:1px dotted #666;
}

This CSS code indicates that every text element inside this division will be shown in brown color, in bold style, with a smaller size (90%) than the other fonts outside the division, and the text will be converted to uppercase. The last CSS element indicates that there will be a one pixel-wide, dotted grey border at the bottom of each text element (#666 is a hexadecimal color code).

All this stuff means that each day in the weblog will be shown like this:

Now, the next line in the _day template:

<p class="entryTitle">$entry.title</p>

The <p> HTML tag indicates a paragraph inside your web page, and $entry.title is the only code inside this paragraph. As we saw before, $entry.title shows the title of an entry in your weblog. The class=”entryTitle” element is related to the .entryTitle code block in your stylesheet:

.entryTitle {
   font-weight: bold;
}

This CSS code indicates that all the text inside the paragraph will be shown in bold. In this case, each entry’s title of your weblog will be shown in bold:

The rest of the bold lines in the _day template use an <a> element, known as an anchor in HTML. This element is used to display links in web pages, and is related to all the a elements in the stylesheet:

a {
  text-decoration: none;
}

a:link {
  color: blue;
  font-weight: medium;
}

a:visited {
  color: purple;
  font-weight: medium;
}

a:hover {
  text-decoration: underline overline;
}

These elements define how the links in your weblog will be displayed. The first block of code indicates that the links won’t have a text decoration (that is, links won’t be underlined, as in most web pages), the color of each link will be blue, the font weight will be medium, and the color of visited links will be purple. The last block of code indicates that, if someone positions the mouse cursor over a link, it will be underlined and overlined.

The following screenshot shows what happens when you put your mouse cursor over the date and time hyperlink created with the <a href=”$url.entry($entry.anchor)”>$utils.formatDate($entry.pubTime, “hh:mma MMM dd, yyyy”)</a> line in the _day template:

You can see the underline and overline effects from the a:hover CSS element, along with the purple color due to the a:visited CSS element.

The <a href=”$url.editEntry($entry.anchor)”>Edit</a>  |  line from the _day template has similar effects:

The last block of code we used in the previous exercise is:

body {
  font-family:"Lucida Grande", lucida, Geneva, Arial, sans-serif;
  background:#FFFFCC;
}

In this case, the body CSS element defines the font used to display your weblog’s data. There are several fonts included, to maximize browser compatibility. You can experiment with different fonts and font families to see how your changes affect your weblog’s way of displaying data.

Summary

In this article we saw how to create a Roller theme from scratch. We also saw how to edit the mystylesheet.css stylesheet override file and how the _day.vm template uses CSS styles and Velocity code to display your weblog’s data.