Apache Roller 4.0: Creating a Theme

Exclusive offer: get 50% off this eBook here
Apache Roller 4.0 – Beginner's Guide

Apache Roller 4.0 – Beginner's Guide — Save 50%

A comprehensive, step-by-step guide on how to set up, customize, and market your blog using Apache Roller

$26.99    $13.50
by Alfonso V. Romero | November 2010 | Beginner's Guides Open Source

In this article by Alfonso V. Romero, author of Apache Roller 4.0 Beginner's Guide, we will look at how to create your first Roller theme from scratch. We will also cover the basics about the theme.xml, weblog.vm, _day.vm, and stylesheet override files used inside a Roller theme.

 

Apache Roller 4.0 – Beginner's Guide

Apache Roller 4.0 – Beginner's Guide

A comprehensive, step-by-step guide on how to set up, customize, and market your blog using Apache Roller

 

  • Create, optimize, and maintain your own blog server using Apache Roller
  • Incorporate multimedia content from popular web tools like YouTube, Google Maps, Twitter. and SlideShare in your posts
  • Customize the appearance of your blog with visually appealing, powerful themes and templates
  • Increase your blog's search engine ranking and keep track of visitors using Google Webmaster Tools
        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:

    Apache Roller

  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:

    Apache Roller

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

    Apache Roller

  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:

    Apache Roller

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

    Apache Roller

  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:

    Apache Roller

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

    Apache Roller

  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:

    Apache Roller

  2. Roller will show you the following success message:

    Apache Roller

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

    Apache Roller

  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:

    Apache Roller

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

    Apache Roller

  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:

    Apache Roller

  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:

    Apache Roller

  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:

    Apache Roller

  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:

    Apache Roller

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

    Apache Roller

  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:

Apache Roller

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:

Apache Roller

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:

Apache Roller

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:

Apache Roller

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.

Apache Roller 4.0 – Beginner's Guide A comprehensive, step-by-step guide on how to set up, customize, and market your blog using Apache Roller
Published: December 2009
eBook Price: $26.99
Book Price: $44.99
See more
Select your format and quantity:

About the Author :


Alfonso V. Romero

Alfonso Romero is a freelance computer consultant and translator from Mexico. He's been working with Linux and open source software since 1999. He started operating his first web server (Apache) from a PC at home, offering free hosting services to experiment with Postfix, Squirrel Mail, MySQL, Apache, Tomcat, and Virtual Hosting. Since then, he's been working as a computer consultant for several clients in Mexico – writing Java, C++, and Web applications. Since 2000, he has worked for Pearson Education in Mexico as a computer books freelance translator and consultant. His latest book translations are the Spanish versions of Java How to Program, Seventh Edition, from Deitel & Deitel, and C++ How to Program, Sixth Edition, also from Deitel & Deitel. Al enjoys writing tutorials and teaching about Java, C++, PHP, the Apache Web server, Tomcat, MySQL, Web applications like Apache Roller, and all of the wonderful open source applications used today, and when he's not experimenting with new trends in Open Source applications, he enjoys playing his electric guitar.

Books From Packt


Apache OfBiz Cookbook
Apache OfBiz Cookbook

OSGi and Apache Felix 3.0 Beginner's Guide
OSGi and Apache Felix 3.0 Beginner's Guide

Apache MyFaces 1.2 Web Application Development
Apache MyFaces 1.2 Web Application Development

Apache CXF Web Service Development
Apache CXF Web Service Development

PostgreSQL 9.0 High Performance
PostgreSQL 9.0 High Performance

Blender 2.5 Lighting and Rendering
Blender 2.5 Lighting and Rendering

Inkscape 0.48 Essentials for Web Designers
Inkscape 0.48 Essentials for Web Designers

Learning jQuery 1.3
Learning jQuery 1.3


No votes yet

Post new comment

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
h
f
W
M
2
a
Enter the code without spaces and pay attention to upper/lower case.
Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software