Working with Templates in Apache Roller 4.0

Cart | Your Account | Trade | Sitemap

Want to know more about Packt's Article Network? Interested in contributing your article ideas?

Please visit our FAQ for more information.

In this article by Alfonso V. Romero, we'll see some of the Velocity elements used in Roller to display data from your weblog and work with Roller's model and data objects to access your weblog's data from custom templates.

To know more about $model object and $url read Working with Templates in Apache Roller 4.0.

In this article by Alfonso V. Romero, you'll learn to build a theme from the ground up, using several templates properties, and methods commonly used in Roller themes.

To learn more about some of the properties and templates used in Roller themes read Working with Templates in Apache Roller 4.0.
See More

This three part article series by Alfonso V. Romero, teaches you how to create and edit your first template in Roller, along with some basics about the Velocity template language, and how to create your first Roller theme from scratch. You'll also learn about Roller's model and data objects, and how to use these objects' properties, methods, and macros in a custom template to show data from your weblog.

Basically, in this article series you shall:

Learn how to create and edit your first template

Learn about the Velocity Template Language and how you can use it in your Roller templates

Work with Roller's model and data objects to access your weblog's data from custom templates

Create a Roller theme from scratch!

Your first template

In essence, a theme is a set of templates, and a template is composed of HTML and Velocity code. You can make your own templates to access your weblog's data and show this to your visitors in any way you want.

Creating and editing templates

In Apache Roller, you can create, edit, or delete templates via the Frontpage: Templates page. Let's see how to use this wonderful tool to create and edit your own templates!

Time for action – creating your first template

In this exercise, you'll learn to create and edit your first custom template via Roller's admin interface:

Open your web browser, log into Roller, and go to the Templates page, under the Design tab:
On the Add a new template panel, type mytemplate in the Name field, leave the default custom value in the Action field, and click on the Add button:
The mytemplate template you've just created will show up in the templates list:
Now click on the mytemplate link under the Name field, to open the mytemplate file for editing:
Leave the mytemplate value for the Name field, type mytemplate in the Link field, and type My First Template in Apache Roller! in the Description field:

Then replace the <html><body></body></html> line with the following HTML code:

<html>
<body>
Welcome to my blog, <b>$model.weblog.name</b> </br>
This is my first template </br>
My weblog's absolute URL is: <b>$url.absoluteSite</b> </br>
</body>
</html>

This is shown in the following screenshot:
Scroll down the page and click on the Save button to apply the changes to your new template. Roller will show the Template updated successfully message inside a green box to confirm that your changes were saved:
Now click on the [launch] link under the Link field to open a new tab in your web browser and see your template in action:
You can close this tab now, but leave the Frontpage: Templates window open for the next exercise.

What just happened?

Now you know how to create your own templates! Although the previous example is very simple, you can use it as a starting point to create very complex templates. As I said before, templates are composed of HTML and Velocity code.

The template we wrote in the previous exercise uses a few basic HTML elements, or tags:

HTML Tag

Definition

Tip

<html> , </html>

Defines the start/end of an HTML document.

You must write this tags at the beginning/end of each Roller template.

<body>, </body>

Defines the start/end of an HTML document’s body.

All the code you will write for your templates must go between the <body> and </body> tags.

, 

Shows text in bold.

Example: Hello shows up as

Hello



Indicates a line break.

Example: HelloWorld shows up as

Hello

World

Also, there are some elements from the Velocity Template Language, along with an example from the previous exercise:

Velocity Element

Definition

Example

$model.weblog.name

Shows the name of your weblog.

$model.weblog.name shows up as Ibacsoft’s Weblog

$url.absoluteSite

Shows the absolute URL of your weblog

$url.absoluteSite shows up as http://alromero.no-ip.org/roller

These are just some of the basic HTML tags and Velocity elements you'll learn to use for your templates. In the following sections, we'll see some more, along with elements from the Velocity Template Language.

The Velocity template language

All templates in Roller use HTML tags, along with Velocity code. In the next subsections, you'll learn about some of the most widely used Velocity elements in your Roller templates.

Using Velocity macros in your Roller weblog

A macro in Velocity is a set of instructions that generate HTML code based on data from your weblog. They are very helpful when you need to do the same task more than once. In the following exercise, you'll learn to use some macros included in Roller in order to show your weblog data to your visitors.

Time for action – showing your weblog's blogroll and most recent entries

Now you will use the Velocity Template Language to show your weblog's bookmarks (blogroll) in your custom template, along with the most recent entries:

Go to your custom template editing page, and type the following code just above the </body></html> line:

</br>
These are my favorite Web sites: </br>
#set($rootFolder = $model.weblog.getBookmarkFolder("/"))
#showBookmarkLinksList($rootFolder false false)

A comprehensive, step-by-step guide on how to set up, customize, and market your blog using Apache Roller
Build a highly usable, customer-friendly, and effective web site in next-to-no-time
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

http://www.packtpub.com/apache-roller-4-0-beginners-guide/book

The entire code of your template should look like the following screenshot (the code you have to add is highlighted):
Save your changes and click on your template's [launch] link to open a new tab in your web browser and see how your template will look like:
Now close the results tab to return to the Front Page: Templates window, and add the following lines of code right after the code you added in steps 1 and 2 of this exercise:
```

And these are the most recent entries in my weblog: 
#set($entries = $model.weblog.getRecentWeblogEntries("nil", 5))
#showWeblogEntryLinksList($entries)
```
Now your template's code should look like the following screenshot:
Save your changes and click on your template's [launch] link to open a new tab in your web browser and see the results:
You can close this tab now, but leave the Frontpage: Templates window open for the next exercise.

What just happened?

In Velocity, a macro starts with the # character. In the previous exercise, you used two Velocity macros: one to show your weblog's blogroll and the other to show your weblog's most recent entries. There are two Velocity statements implicated in the blogroll macro:

#set($rootFolder = $model.weblog.getBookmarkFolder("/"))
#showBookmarkLinksList($rootFolder false false)

The first line gets the root bookmark folder (represented by "/") and assigns it to the $rootFolder variable. The second line is the showBookmarkLinksList macro, which uses the value in $rootFolder to generate a bookmarks list and show it in your template:

The two false arguments after $rootFolder indicate that we are not using subcategories inside the bookmark links list. If you want more information about these arguments, check the Roller template guide included in the Roller installation.

There are two more lines involved in the recent entries macro:

#set($entries = $model.weblog.getRecentWeblogEntries("nil", 5)
#showWeblogEntryLinksList($entries)

The first line gets the 5 most recent entries from your weblog and assigns the result to $entries. The "nil" parameter specifies that Roller must get the five most recent entries from all categories. If you want to get the most recent entries from a specific category, just replace "nil" with the name of that category.

The next line is the showWeblogEntryLinksList macro, which uses all the entries included in $entries to generate a list with links:

Summary

In this article, you learned how to create and edit your first template in Roller.

Specifically, we covered:

What is a template, and how to create/edit a custom template with Roller's admin interface
An introduction to the Velocity Template Language

A comprehensive, step-by-step guide on how to set up, customize, and market your blog using Apache Roller
Build a highly usable, customer-friendly, and effective web site in next-to-no-time
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

http://www.packtpub.com/apache-roller-4-0-beginners-guide/book

About the Author

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.

Joomla! with Flash

Joomla! 1.5 SEO

Zend Framework 1.8 Web Application Development

Ext JS 3.0 Cookbook

ICEfaces 1.8: Next Generation Enterprise Web Development

Spring Persistence with Hibernate

3D Game Development with Microsoft Silverlight 3: Beginner's Guide

Microsoft Office Live Small Business: Beginner’s Guide