User Guide

Apache Roller

Version 3.1

Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. The ASF licenses this file to You under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. For additional information regarding copyright in this work, please see the NOTICE file in the top level directory of this distribution.

1 - Introduction

This user guide describes how to use Roller, a web application that can support a single user weblog, thousands of weblogs and/or group weblogs. You'll learn how to register as a new user, create weblogs, edit and post weblog entries and manage your weblog. You'll also learn how to customize your weblog's blogroll, a list of links to your favorite web sites,and how to change the look-and-feel or theme of your weblog.

A word about terminology is necessary because the word weblog is both a noun and a verb. In this guide we use the words weblog and weblog entry as follows:

• Weblog: a weblog or blog is an online journal written by one or more authors. In Roller a weblog consists of weblog entries, weblog categories, favorite bookmarks and settings that define the appearance and behavior of the weblog.

• Weblog entry: a weblog entry is an individual entry within a weblog with a title, date and text.

2 - Getting started with Roller

We'll start by explaining how to get started with a fresh Roller server, one that was just created and has no users at all. If you are using an existing Roller server, which has already been setup by somebody else, then you can skip to section 2.2 - Getting started with an existing Roller installation where we discuss how to register for an ordinary Roller user account.

2.1 - Getting started with a new Roller installation

If you've just installed a new Roller server, make sure that you create the first user yourself. Roller grants global admin permission to the very first user that is created. Later, you can use that admin user to grant global admin permission to other users. Here's how to create your first user:

How to create the first user and weblog on a fresh Roller site:

1. Start Roller and navigate to the main page (e.g. http://localhost:8080/roller).

2. Click the Register link in the top right corner of the page.

3. Fill out the information for your new user, perhaps using the username 'admin' since the first user is the admin user. Once you've filled out the form. click the Register User button.

4. On the Welcome to Roller page, choose the Click here link to login as your new user. You'll be taken to the Roller Main Menu page.

5. On the Main Menu page, click the create a weblog link to create a new weblog.

6. Fill out the Create Weblog page and when you're done click the Create Weblog button.

2.2 - Getting started with an existing Roller installation

To get started on an existing Roller installation, first you need to create a user account. Once you've done that, you can create one or more weblogs for your user.

How to create a user account

Some Roller sites require you to use a separate system to create a Roller account. For example, at Sun we require blogs.sun.com bloggers to register using an internal system called BAM.

With a stock Roller installation, here's how you register a new user:

1. Use your web browser to go to the main page of the Roller installation

2. Click the Register link in the top right corner of the page

3. Fill out the information for your new user. Once you've filled out the form. click the Register User button.

4. On the Welcome to Roller page, choose the Click here link to login as your new user. You'll be taken to the Roller Main Menu page.

How to create a weblog for your user

Here's how you create a new Roller weblog for your user:

1. Login to Roller by clicking the Login or the Main Menu link

2. On the Main Menu page, click the create a weblog link to create a new weblog.

3. Fill out the Create Weblog page and when you're done click the Create Weblog button.

2.3 - Accepting an invitation to join a weblog

Roller supports group blogging. That means that more than one user can edit and manage a single weblog. If somebody invites you to join their weblog, an invitation message will appear at the top of the Main Menu page. Depending on how Roller is configured, you may also get an email message that informs you of the invitation. To accept an invitation, login to Roller go to the Main Menu page and you'll see something like this.

Illustration 1: Main Menu with invitation to join a group blog

That's an invitation to join the weblog with the handle 'adminblog'. To accept click the accept button. Once you do, you'll be a member of the weblog and the weblog will appear on your Main Menu page as one of your weblogs.

2.4 - Getting around in Roller

When you log into Roller, Roller sends you to the Roller editor interface -- a set of web pages for editing and managing your weblog and (if you have global admin privileges) the Roller installation itself.

Find your way around the editor interface

No matter where you go in the Roller editor interface, you'll always see a status bar across the top of the page with convenient links to the Roller front page and main menu.

Illustration 2: Status bar, no weblog

That's what the status bar looks like when you are logged in (assuming your username is 'admin'), but you haven't chosen a specific weblog in which to work. What's going on here?

• The text on the left indicates that you are logged in as user admin.

• On the right, the words Front Page link to the front page of the Roller site. Your site's administrator may have changed the words Front Page to something else, but the link should still take you to the site's front page.

• Also on the right, the words Main Menu link to the main menu of Roller, where you can manage your weblog(s), create new weblogs and accept invitations to join other user's weblogs.

If you are logged into Roller and you are editing one specific weblog, the status bar will include a link to that weblog. For example, the bar below indicates that user 'admin' is logged-in and editing weblog called 'adminblog.'

Illustration 3: Status bar within weblog

Going from your weblog back to the editor interface

When you're on your weblog page and you need a way to get back to the Roller editor interface, look for the weblog navbar. All of Roller's built-in themes include the navbar. It looks slightly different in each theme, but it always includes the same set of links.

Illustration 4: Weblog navigation bar

That's what weblog navbar looks like this when you are not logged in (note that the exact appearance varies in each theme). The words Front Page link to the front page of the Roller installation and as with the front page link in the banner-status bar, the words may be different on your site. Next are links to the public pages of the weblog, and this particular weblog includes pages called Weblog and About. Finally, there is a link to Login.

Illustration 5: Weblog editor navbar

That's what weblog navbar looks like this when you are are logged in. After the familiar Front Page link and the page links there's a link to the weblog's New Entry page, the weblog's Settings page and a Logout link.

After the logout link is the editor navbar, which includes shortcuts to all of the editor pages for this particular weblog. It is also included on all of the built-in Roller themes, but is a separate component from the plain old weblog navbar.

Now that we've covered the basics of registering a new user, creating a new weblog and finding your way around let's start blogging.

2.5 Changing the Language of the editor interface

The Roller editor interface uses the locale (language and country) User Profile setting to select the text to display in the editor navbar and in each editor page. You can select your preferred locale when registering or, if you have already registered, on the Your Profile page. If a translation for your preferred language is available on your Roller installation, the editor interface will use this language for all the editor pages. If you have selected your preferred language and the pages are still displayed in English (or the default language of your Roller installation?) there may not be a translation available for your language. (If you or the person(s) responsible for your Roller installation would like to translate Roller to an additional language, please visit the Roller project website...) (Translations are currently available for...)

3 - Creating and editing your weblog

First, you login to Roller. What happens next depends on the number of weblogs that you have. If you have one weblog, you'll be taken directly to the New Entry page for that weblog. If you have more than one weblog or none at all, then you'll be taken to the Main Menu page, shown below, so you can pick which weblog to edit and/or create new weblogs.

Illustration 6: Main menu

The main menu page lists all of your weblogs and for each, shows you links to its New Entry, Edit Entries and Settings pages. You can also create a new weblog, edit your user profile and perform administrative duties (if you have global admin permissions).

3.1 - Creating and editing a weblog entries

Use the Create & Edit -> New Entry page (also known as the Weblog editor page) to create, edit and publish weblog entries. Using the page, shown below in illustration 7, you can set entry title, category, content and summary. You can also set some advanced settings by expanding the Plugins To Apply and Advanced Settings controls at the bottom of the page. Let's review those fields, buttons and settings.

Illustration 7: Weblog editor

3.1.1 - Weblog editor fields

Let's discuss each of the fields on the New Entry page, so you know how to use them.

• Title – Each weblog entry must have a title. Be careful when you pick your title, it will be used in the link to your weblog entry. For best results, do use titles that are short and to-the-point. Don't include any HTML in your titles, just plain text – if you want your titles to be bold, then customize your templates instead of embedding HTML in your titles.

• Status – This read-only field tells you about the current state of the weblog entry that you are editing. There are three possible status settings:

• Not Saved – the entry has never neen saved

• Draft – the entry is saved as a draft and is not yet visible to your weblog's readers

• Published – the entry has been published and is visible to your weblog's readers

• Permalink – this read-only field is the permalink link to your weblog entry. It is set the first time that you save an entry, based on the title at the time you save – and it cannot be changed later.

• Category – You can pick one category for your weblog entry. Categories are for folks who want to organized the entries in their weblog into a small-set of fixed and possible hierarchical categories, defined by the weblog admin (that's probably you). You can add and remove categories via the Create & Edit -> Categories page.

• Tags – (optional) Enter a list of one or more tags that describe your weblog entry, separated by spaces. As you type, Roller may suggest tags that you've used before.

• Content – This is the main body of your weblog entry, in HTML format. We try to make that easy by providing two ways to edit the content. Via the Preferences -> Settings page, you can pick either of these:

• Rich Text Editor (Xinha) – a rich-text editor that's designed to make editing HTML as easy as using MS Word or Open Office.

• Text Editor – a plain-text editor that you can use to edit the raw HTML markup of your weblog entries. Don't use this unless you know HTML.

• Summary – (optional) If you wish, you can enter a short summary of your weblog post. If you do so, then the short summary will be displayed on the main page of your weblog and your readers will have to click a Read More link to get to the full-content. Some bloggers like to do this when they have very long post and they don't want that long post to dominate the main page of their weblog.

3.1.2 - Weblog editor buttons

Here's a guide to the buttons that appear on the Weblog editor page.

• Post to weblog – Using this button will publish your weblog entry and make it visible to the world. Make sure you're happy with your post before you publish because once something is published on the web, and grabbed by the blog aggregators and search engines, there's really no way to un-publish it.

• Submit for review – if you're just a limited blogger, you won't see the Post to weblog button because you cannot post to the web. Instead, you'll see a Submit for review button which you can use to send your entry to the author/admin of the blog that you are working in. If they like the post, they can publish it – or they can return it to you for further edits.

• Save as draft – this will save your weblog post for later editing, but will not publish it to the web. When you're working on a new weblog entry, use Save as draft often so you won't lose your post in the event of internet connection loss or session time-out.

• Delete entry – use this to delete the current weblog entry, you'll be asked to confirm.

• Full preview – You won't see this button until you've saved your entry as a draft. It allows you to view, in a separate window, a preview of your entry, displayed using the layout and style of your blog.

3.1.3 - Weblog editor plugin settings

If you expand the Plugins to Apply control, you'll see a set of check-boxes, one for each Weblog Entry Plugin that is available. Check the ones that you'd like to apply to your current weblog entry. If you have a favorite plugin, one that you want to use on every entry, then you can set it as a default on your weblog's Preferences -> Settings page.

3.1.4 -
Weblog editor advanced settings

If you expand the Advanced Settings control, you'll see what's below.

All of these are optional settings.

• Pub Time – if you'd like to set the publication time of your weblog entry to a specific time, possibly one in the future, you can do so here.

• Allow comments for – this setting allows you to turn comments on/off for your weblog entry and to limit the number of days that comments are allowed.

• Text reads left-to-right – this settings allows you to set the reads left-to-right flag for a weblog entry. Currently, none of the stock Roller templates respect this setting.

• Pinned to main – only Global Administrators will see this setting. It's a way to indicate that a post is a special announcement that should be pinned to the top of the front-page of a weblog site. The front-page theme respects this setting).

• Enclosure URL: if you'd like to include a audio, video or image file as a Podcast in your weblog's RSS feed, then enter the URL of that file here.

3.2 - Finding and editing weblog entries

All of your blog entries are saved in a database. Once your blog entries scroll off the front page or off the recent entries list of the Create & Edit:New Entry page, they are still available to your readers on your weblog pages. They're available to you too.

3.2.1 - Finding old entries with the Create & Edit:New Entry page

If you go to the Create & Edit:New Entry page, you'll see on the right a list of recent Pending Entries, Draft Entries, and Recent Entries. You can edit any of these by simply clicking on title.

• Pending Entries are entries created by limited bloggers who are not allowed to publish directly to the web. If you have author or admin permission in the blog you can edit and publish these entries.

• Draft Entries are entries that are not yet visible on the web becuase you, or somebody else in your weblog is not yet done editing them. You can edit any draft entries in your weblog.

• Recent Entries are entries that have been published to the web. If you have author or admin permission in the blog you can edit and re-publish these entries.

Illustration 8: Edit entries page

3.2.2 - Finding old entries with the Create & Edit:Entries page

You can use the Create & Edit:Entries to find and edit your old posts. That includes posts that have scrolled-off the bottom of the Pending, Draft and Recent Entries lists we discussed above. When you first arrive on the page it will show you most recent entries, as shown in the screenshot below. If you want to find an old post you can use the start and end date calendars to look for posts in a specific time period. You can edit any of the entries in the Weblog Entries list by simply clicking on its title.

3.2.3 - Finding old entries using the pages of your weblog

You can also use the pages of your weblog to navigate into the past and find old blog entries. If you do this when you are logged in, then you'll see an Edit link on each weblog entry, which will load that entry into the weblog editor (i.e. the New Entry page).

There are several ways to do this:

• Using the calendar: most weblog themes include a calendar, which you can use to navigate back and forwards in time.

• Using the next/prev links: most weblog themes include next/previous links, which allow you to navigate back and forwards in time.

• Using URLs: you can also use URL's to navigate back in time. Roller URLs take the form /page/username and /page/username/date where date is formatted YYYYMMDD. So, you can navigate into the past by using URLs.

3.2.4 - Finding old entries with Roller's built-in search engine

Roller also has a built in search engine, which you can use to search for entries in the entire site, or in just your blog. If you're logged in, when you find one of your old entries, it will have an Edit link.

3.3 - Weblog categories

Roller's weblog categories feature allows you to organize your weblog posts by category. For example, you might setup a category called "Family" for your family related posts, a category called "Music" for your music posts, and a category called "Misc" for everything else.

When you write a new weblog post you must decide which category to place it in. On the Create & Edit:New Entry page, there is a combo-box that allows you to pick a category for your post or to change the category when you edit an old post. Currently, Roller only allows you to assign each weblog post to one category.

3.3.1 - The Weblog Category Chooser

When a user views your site, they can choose which category to view. All of the stock Roller weblog templates include the #showWeblogCategoriesList() close to the top of the page so that your readers can pick which category to display or "All" for all categories of posts.

3.3.2 - RSS Feed for Each Category

Your weblog's main RSS newsfeed includes all categories, but users can choose to subscribe to specific categories. Most of the stock Roller weblog templates display a list of your RSS feeds, one for all categories and one for each separate category.

3.3.3 - Adding, Renaming, and Removing Weblog Categories

You can change the names of your categories, add new categories, and delete categories using the Create & Edit:Categories page of the Roller Editor UI.

3.4 - Using a blog client with Roller

A blog client allows you to post to Roller remotely, from your desktop or from some other web site. For example, desktop applications such as Ecto and MarsEdit can post to Roller and so can the photo-sharing web site Flickr.com. This is possible because Roller supports the standard Blogger and MetaWeblog APIs.

Configuring a blog client for use with Roller

First, make sure to enable Blogger API support in your weblog via the Preferences:Settings page. Next, start your blogging client, find the preferences or account setup dialog. You'll need to set the following parameters:

Username: your Roller username

Password: your Roller password

BlogID: the handle of your Roller weblog

URL: the URL of Roller's XML-RPC endpoint

Note that you may not need to enter your BlogID because some blog clients will login to Roller and then present you with a list of the weblogs that are available to your user.

A blogs.sun.com example

For example, if you have an account on blogs.sun.com, your username is fred and your blog's handle is fredsblog (i.e. your weblog's URL is http://blogs.sun.com/fredsblog), then your paramrters would be:

Username: fred

Password: (your password)

BlogID: fredsblog

URL: http://blogs.sun.com/roller-services/xmlrpc

You may not need to enter your BlogID because some blog clients will login to Roller and then present you with a list of the weblogs that are available to your user.

A jroller.com example

If you have an account on jroller.com, your username is fred and your blog's handle is fredsblog (i.e. your weblog's URL is http://jroller.com/fredsblog), then your paramters would be:

Username: fred

Password: (your password)

BlogID: fredsblog

URL: http://jroller.com/roller-services/xmlrpc

3.5 - Podcasting with Roller

Roller now includes support for podcasting, a way to distribute files through your weblog's newsfeed. Typically, folks use Podcasting to distribute audio files, but the technique can be used to distribute any type of file. Specialized Podcast client software (such as iPodderX) downloads the audio files that are referenced in your newsfeed and copies them to an music player, such as an MP3 player.

3.5.1 - How to create a podcast feed with Roller

In Roller a Podcast is like an attachment to a weblog entry. We call it mediacasting in the Roller UI because it can be any type of file and is not necessarily destined for play on an Apple iPod. Here are the steps involved in Podcasting with Roller:

• Record an interesting Podcast (that's the hard part, by the way)

• Save your Podcast in MP3 format (or whatever you prefer).

• Upload your Podcast to a web server somewhere and take note of your Podcast's URL. If you have the space for it and your Roller admin allows MP3 files, you can use file-upload capability to upload it to your Roller website. Chose the Create & Edit: File Uploads menu item to get to Roller's file-upload page. For example, if Nina of example.com were to upload a file to Roller, then the URL would look something like this:

	http://example.com/roller/nina/resource/mycast.mp3

• Create a new Roller Weblog entry via Create & Edit:New Entry describing your new Podcast. You might want to provide a link to it so that those without a Podcast client can click to download it directly. Using Nina as an example again, she would add the following HTML to her blog entry to provide a link to her Podcast:

	Hey now! I just created my first Podcast you can download it here:

	<a href="http://example.com/roller/nina/resource/mycast.mp3">mycast.mp3</a>

• And the most important step: in the lower-half of the Edit Weblog page, you'll see an expandable control labelled +MediaCast Settings. Click on that to expand the MediaCast control and paste into the URL field the URL of your Podcast.

• Once your blog post is ready, save it as a draft or publish it. Once you've done that you'll see that the MediaCast Settings control has the content-type and file-size of your Podcast. If not, then Roller could not access your Podcast due to network problems or perhaps a bad URL. Make sure the URL is correct and save again. If your Podcast is OK, you'll see something like this:

Illustration 9: Podcast URL field

• Roller will add the Podcast to your RSS newsfeed as an <enclosure>. You can check this by looking at your RSS newsfeed. Go to your weblog and click the orange XML icon, or just enter your newsfeed URL into your browser. After you download your newsfeed file, open it with your favorite text editor and in the most recent entry you'll see an RSS enclosure. For example, Nina would see the following enclosure in her newsfeed:

	<enclosure url="http://example.com/roller/nina/resource/mycast.mp3" 
		type="audio/x-mpeg" length="3409127" />

That's all there is to podcasting with Roller.

4 - Working with comments and trackbacks

Roller supports weblog comments and trackbacks, which provide a way for other bloggers to add comments to your blog remotely. By default comments and trackbacks are enabled, but you can turn them off on your weblog's Preferences:Settings page of your weblog. Note that turning off comments, disables both comments and trackbacks.

4.1 - Comment notification via email

If you're going to leave comments turn on then take the time to read them, to respond where appropriate and, when you receive spam or other forms of offensive comments, delete them from your weblog. You can't respond to comments if you don't know when you get one, so make sure you enable email notification of comments. You can do that on the Preferences:Settings page.

If you've got email turned on then you'll receive an email every time you get a new comment and the email will include the text of the comment, a link to the entry that was commented upon and a link to the comment management page, shown below, where you may choose to approve, mark as spam or even delete the new comment.

4.2 - Comment management and moderation

If you'd like to preview and approve comments before they are displayed on your weblog, then you'll want to turn on comment moderation via Preferences:Settings. When comment moderation is enabled, then each new comment will be marked as pending and unapproved and will not appear on your weblog. To check for new comments, go to the Create & Edit:Comments to check for and either approve or delete new comments. If you've got comment notification enabled, make sure you also enable comment notification so you'll know when new comments arrive. To moderate comments, use the comment management page, described below.

The comment management page

The comment management page, shown in illustration 10, allows you to manage comments for your weblog. If you arrive on the page from the link in a comment notification email, then you'll see only the comments for the one entry that was commented upon. If you arrive via the menu, you'll see all recent comments in reverse chronological order.

Comments that are suspected to be spam are shown with a light red background, with the spam check-box checked. Comments that are new and pending your review are shown with a light yellow background.

How to moderate comments

• Review each new comment and decide if it is to be approved for display, marked as spam and hidden or deleted entirely.

• Only comments that are marked as approved and are not spam will be displayed on your weblog. So set (or unset) the corresponding checkboxes for each comment, or leave them the way they are.

• When you are done. Click the save changes button at the bottom of the page. You'll see that comments that were pending are no longer pending and those that you marked for delete will be gone.

How to search weblog comments

You can also use the comment management page to search for comments across all entries in your weblog by keyword, status and date. Use the Filter comments area of the page to set the fields you want to search and click the Query button. If there are more comments than can be displayed on one page, then a next page link will be displayed at the top of the list of comments so that you can navigate into the past.

Illustration 10Comment (and trackback) management page

Global comment management

If your user has global adminstration privileges, then you can manage comments across the entire Roller site, including every weblog. To do this, go to the Server Adminstation:Comments page and you'll see a page that is almost identical to the weblog-specific comment management page.

Limitations of global comment management

You can use this page to mark as spam or delete any comment in the system, however you cannot change the approval status of comments through this interface. Approving comments for display is the duty and responsibility of the individual webloggers, so comment approval is only available in the context of a weblog.

A word about receiving trackbacks

Incoming trackbacks are treated differently, depending on how your Roller site is setup. Your site adminstrator may choose to disable incoming trackbacks entirely. In that case, anybody who tries to send a comment to your weblog via trackback will receive and error messae and no comment will be added.

Your site administrator may choose to enable a spam prevention measure known as trackback verification. If that's the case, then each incoming trackback will be verified. If the weblog that sent you the trackback does not link to your weblog entry, then that trackback will be marked as un-approved and pending. You'll have to visit the comment management page to approve that trackback before it is displayed as a comment on your weblog.

4.3 - Preventing weblog spam

There are three forms of comment spam that can affect your weblog:

• Comment spam: spam that arrives via the comment form on your weblog. Sometimes spam comments are added by a human and sometimes by a computer program known as a spambot.

• Trackback spam: spam that arrives via trackbacks sent by a spambot.

• Referrer spam: spam that arrives in web requests and appears on the Create & Edit:Referrers page of your Roller blog or on your blog (but only if your blog theme uses the #showReferrers() macro).

Fortunately, there are counter-measures for each type of spam. For comment and trackback spam, you can use email notification of comments, comment moderation and trackback verification (described in the previous section) to manage spam. That's not all. Roller also includes a blacklisting feature, which can be used to fight all three forms of spam.

4.3.1 - Three levels of blacklisting

Roller uses a blacklist, a lists of words which are used to check incoming comments, trackbacks and referrers for spam. The blacklist includes several thousand words and regular expressions which which are used to check incoming comments and trackbacks. If the name, URL or content of a comment or trackback includes one of the blacklist words or matches one of the expressons then that comment or trackback is marked as spam and is not displayed on your weblog, unless you use the comment management page to unmark it.

Actually, there are three levels of blacklist:

• Level 1 blacklist: This is the built-in blacklist, the one that comes with Roller. This can only be changed by somebody with root access to the Roller server itself.

• Level 2 blacklist: This is the site wide blacklist, which can only be edited by a global administrator via the Server Admin:Configuration page.

• Level 3 blacklist: Weblog specific blacklist, which you control in the Preferences:Settings page of your weblog.

Incoming comments and trackbacks are checked against all three levels of blacklist. Incoming referrers, however, are only checked against the levels 2 and 3 blacklist.

4.3.2 - How to add words and expressions to the blacklist

If you have a spam problem on your weblog and you'd like to add words to the blacklist, it's probably better for you to ask your administrator to add the words to the level 2 blacklist for you. That way, every blogger on the site will benefit from the addition. If you must do it yourself, here's how you do it:

• Go to the Preferences:Settings page and scroll down to the blacklist fields

• Enter your spam words, one per line

• Lines that begin with a left parenthesis will be treated as regular expressions (see the Java API documentation for javax.util.regex.Pattern for a guide to regular expressions). Don't try to use a regular expression unless you really know what you're doing.

4.4 - Sending trackbacks

If you are writing about something you read on another weblog, you want to let the author and readers of that weblog know that you are doing so, and that other weblog is trackback enabled, then you should send that weblog a trackback ping. Here's a story that illustrates how trackback works:

• You read an interesting blog entry on Otto's blog. You notice that Otto's blog entry has a trackback URL, so instead of leaving a comment on Otto's blog you decide to comment by writing a blog entry in your own blog. You copy that trackback URL (using ALT-C, or right-click-copy, or whatever) cause you'll need it later.

• You go to your blog and write a new blog entry in response to Otto's entry. Click the Post to Weblog button to publish your new entry. After you publish, scroll down on the New Entry page until you see the following text field and button:
  

Illustration 11: Send trackback control

• Enter the trackback URL from Otto's blog entry into the text field and click the Send Trackback button. Roller will respond by printing the response received from Otto's blog server. If the trackback was successful, you should see something like this:

Illustration 12: Result of sending trackback

• You should now see your trackback listed among the comments on Otto's blog entry.

4.5 - Referrer rankings

The Weblog:Referrer referrer rankings page shows the hits that are coming in from other websites and weblogs that have links to your weblog and to specific entries in your weblog. By looking at your referrer logs, you can get an idea of who is reading and commenting on your weblog.

5 - Managing your weblog settings

As a Roller user, you are free to customize the look-and-feel of your weblog as you wish. When you establish your Roller user account, you can choose one of the dozen or so stock themes for your website. Later, you can use the theme switcher to switch to a different theme. Or, if you know something about HTML and CSS you can customize the look-and-feel and layout of your weblog yourself by modifying the page templates that make up your site and by adding new pages. Best of all, you can do all of this through the web-based Roller Editor UI.

To manage your weblog, use the Preferences menu. You can get there from the Main Menu page, by clicking the Settings link for your blog. Or, if you're already editing your weblog, you can just click on the Preferences menu in the tabs. Once you're there, the tabbed menu should look like this:

Illustration 13: Weblog preferences menu

In the rest of this section we'll cover each of the items on the Preferences menu.

5.1 - Weblog settings

The Preferences:Settings page allows you to set the configuration parameters for your weblog. The page is large, so we've split it into two screen-shots. Here's the first one.

Illustration 14: Weblog settings page part 1

Here is an explanation of each of the settings on the weblog Preferences:Settings page:

General settings

• Title - The title of your weblog may include HTML, but the HTML will be stripped out in your RSS feed. You can access your title in a page template with the expression #showWebsiteTitle()

• Description - The description of your weblog may include HTML, but the HTML will be stripped out in your RSS feed. You can access your description in a page template with the expression #showWebsiteDescription().

• Email address of weblog owner: Enter the email address that you would like people to use to contact the person in charge of your blog; usually that's you. To thwart spammers, your email address will be obfuscated when displayed on your blog. Please enter a valid address, otherwise Roller's email features will not work.

• Weblog editor page to be used - Choose a weblog editor page, some are rich-text editors:

• editor-text.jsp: Simple text editor, you must enter HTML

• editor-rte.jsp: Rich text editor (works in Firefox and IE but not Safari)

• Weblog is active: un-check this box to indicate that your weblog is no longer active and should not appear in hot-blog and other weblog listing on the site. You might want to do this if you take a very long vacation or if you have decided to stop updating your weblog for some other reason.

• Number of entries to display on weblog: Enter the maximum number of entries to be displayed on your weblog.

Internationalization Settings

• I publish my weblog in multiple languages: check this box if you blog in multiple languages and would like to specify a language locale for each of your weblog entries.

• Show my weblog entries from all languages on my home page: check this box if you'd like your weblog's main page to show your posts in all languages. If you don't check it, then readers will only see weblog entries from your default locale.

• Locale set the default locale for your weblog.

• Timezone: the timezone to be used in your weblog.

Comments

• Allow comments for your weblog? – Check this box to allow visitors to leave comments on your weblog.

• Moderate comments – Check this box to enable comment moderation (i.e. you must approve each comment before it is displayed).

• Email comments – Check this box to receive an email notification of each new comments.

• Default from e-mail address for comments – This will be used as the from address in comment emails sent by Roller.

Default comment settings

• By default, allow comments for new entries – Check this box to enable comments on your weblog. You can also control comments on each individual weblog entry.

• Default time to allow comments for new entries – Choose the default amount of time to allow comments for new blog entries. This setting may also be overridden using the Comment Settings section of the New Entry page.

• Apply comment defaults to all existing entries? - If you check this box, when you click the Save button the comment defaults you have set will be applied to all existing comments.

Settings on the weblog Preferences:Settings page (continued):

Weblog client API

• Enable Blogger API for your weblog - Set to true to enable weblogging via the Blogger API. This will allow you to use handy blogging clients like w.bloggar to post to your weblog.

• Category for posts received via Blogger API - Choose the category for incoming posts made via the Blogger API. This only applies if you blogging client does not support categories.

Formatting

• Default entry formatters: this is the list of plug-ins to be enabled by default on a new weblog entry.

Spam pevention

• Ignore incoming referrer URLs that contain any of these (comma-separated) words - you can use this to filter out what referrers are accepted. Somewhat useful if you start getting hit by referrer spam, but not a complete solution to the referrer spam problem. See section for more information on spam prevention.

Illustration 15: Weblog settings page part 2

5.2 - Weblog themes

A weblog theme is a set of templates, style-sheets and image that determine how your weblog will be displayed. A theme can define both the layout and color-scheme of your weblog. When you start a Roller weblog, you choose from one of the built-in themes. You can change your weblog's theme at any time by going to the Preferences:Theme page, show below.

Illustration 16: Theme selection page

You can also choose to customize your theme. If you click the Customize button the templates that define your current theme will be copied into your blog where you can edit theme. See the Template Authors Guide for complete documentation on customizing your weblog's theme.

WARNING: if you have customized your theme, then watch out. Switching themes using the Preferences:Theme page will destroy the custom changes you've made.

5.3 - Uploading Files

If you'd like to upload images or other files for use in your weblog, go to your weblog's Create & Edit -> File Uploads page. From there you can upload files and manage the files that you have already uploaded. Illustration 17 shows the file-upload page.

Illustration 17: File-Upload page

Using this interface you can:

• Upload up to five files at a time. To upload a file click a Browse button, select the file you wish to upload on the file-system and click the Upload button to upload it to Roller.

• Create sub-directories (one level deep) to organize your uploaded files. Just enter the desired name of the new directory in the New Directory field and click the Create button.

• Delete uploaded files and directories. To delete a file or directory, just check the Delete check-box them click the Delete Selected button at the bottom of the page.

Now let's discuss how to upload an image for your weblog.

5.3.1 - How do I upload and include an image in a weblog entry?

If you want to upload an image to Roller and then include that image in a blog post, here's what you do.

Step 1: Upload the image. From the Create & Edit -> File Upload page of your weblog, click one of the Browse buttons. You'll get a File-Open dialog-box. Use that to find and select the image that you'd like to upload. Click the upload button to upload it. Once the upload is complete, you'll see a success message like this:

Step 2: Copy the URL of the uploaded image. Use your mouse to select the URL of the uploaded image. Use your browser's Edit-Copy menu CONTROL-C to copy the URL to the clipboard.

Step 3: Create or edit a weblog entry. Create a new weblog entry or open an existing weblog entry in which you'd like to include the image.

Step 4: Include the image in the weblog entry. Enter the text of your weblog entry and then position the cursor where you'd like to include the image. There are two ways to include the image.

If you're using the Rich Text Editor, then click the image button and paste in the image URL that you saved in step 3. The editor will create the HTML needed to display your image.

If you're using the Text Editor, then you'll have enter the HTML yourself. For example, to display the image indicated by the green success message above we'd use the following HTML:

<img src="http://rollerweblogger.org/roller/resource/weblogeditor.png" 
    alt="Image of the weblog editor" />

5.4 - Setting up a group blog

To create a group blog, create a new weblog or log into an existing weblog that you'd like members to contribute to. Creating a weblog for group blogging is the same a creating a personal weblog (see section [3] for instructions). Navigate to the Members menu item in the Preferences tab. The Preferences:Members page enables weblog admins to invite members to a group blog and manage the group blog user access.

Illustration 18: Weblog permissions page

You can use the Invite new member link to invite any Roller user to join you weblog, but before you do you should understand the three different permission levels allowed for members of a weblog. They are:

• Admin: an admin can create/edit weblog entries and publish them to the web. They can also manage the weblog by changing the theme, editing the page templates that define the look of the blog, and managing the users of the blog. Roller will grant you admin rights in any weblog you create. Admin users can see both the Create & Edit tab and the Preferences tab of Roller.

• Author: author permission allows users to create entries, edit entries and upload files. But authors cannot change weblog settings, modify the theme or manage users. Authors can see the weblog Create & Edit tab, but not the weblog Preferences tab.

• Limited: limited bloggers can create and edit blog entries and save them as drafts, but cannot publish them to the web.

Select Invite new member from the right navigation to invite Admins, Authors, and Limited authors to join the group blog. You'll need to know the users individual blog username to find them in the list of users. You may scroll through the list, but it's best to begin typing their username to locate them. Set the users Permissions by selecting Admin, Author, or Limited. Click on Send Invitation. If roller is not configured to talk to the mail server, you may get the following messages:

User successfully invited.
ERROR: Notification email(s) not sent, due to Roller configuration 
or mail server problem.

As long as the first message is present, the invite is successful. The next time the user logs into the blog site, they will see the following: on the Main Menu page:

You are invited to join weblog [weblog name will appear here] – accept  |  decline

Once a user is a member of your blog, you can change their permissions. Just click the appropriate radio button in the table and click the Save button. You can also remove users from the site, but note that you cannot reduce your own permissions or remove youself from the weblog.

Accept or Decline a Group Blog Invitation

If you are invited to become a member of a group blog, an invitiation will be present at the top of the Main Menu page. Example:

You have one or more invitations to accept or decline:
You are invited to join weblog [sputnik] –  accept  |  decline
You are invited to join weblog [dotSunNews] -  accept  |  decline

Click 'accept' to become a member of the group blog or 'decline' to turn down the invitation.

Contribute to a group blog

Once you're a member of a group blog, contributing is as easy as creating blog entry content. To access the group blog, login, from the Main Menu navigate to the group blog you'd like to contribute to and select any of the following: New Entry, Edit Entries, Settings (weblog admins only).

For users who participate in multiple weblogs it is important to note that the Main Menu page is how you switch between the various weblogs you can author to. The Main Menu will always show you what weblogs you are participating in and what privilages you have on each weblog.

Resign from a Group Blog

To resign from a group blog, login, on the Main Menu page, navigate to the blog information for which you wish to resign. Select 'Resign'.

6 - Managing your weblog's blogroll

Roller makes it easy to maintain a blogroll, that is, a list of your favorite weblogs and web sites that is displayed in the sidebar of your weblog.

6.1 - Adding new links to your blogroll

Individual blogroll items are known as bookmarks. Use the Create & Edit:Bookmarks page to add, edit and delete bookmarks and bookmark folders in your blogroll.

Illustration 19: Bookmarks management page

Here are some notes about the bookmarks page:

• The Add bookmark link takes you to the Add bookmark form, see below.

• The Add folder link talks you to the Add folder form, see below.

• The check-box allows you to select a bookmark for deletion or for moving to another folder.

• The Edit icon allows you to edit a bookmark using the Edit bookmark form, see below.

• The Visit icon allows you to visit the link.

6.2 - Adding new links to your blogroll

The Add/Edit bookmark form, shown below, allows you to enter information about one bookmark.

Here's an explanation of the fields:

• 
  Illustration 20: Add and edit bookmark form

  
  Name: Text to be displayed on the link

• Description: Description, displayed when viewer hovers over link

• Bookmark URL: The URL of the bookmark

• Newsfeed URL: The URL of the newsfeed associated with the bookmark (if any)

• Sort priority: Lower numbered bookmarks displayed first in blogroll

• Display weight: Higher numbered bookmarks displayed bolder/larger

6.3 - Adding new bookmark folders

If you'd like to display a separate list of links somewhere on your weblog, or you'd like to store links in Roller for some other reason, you can use the Add folder form, shown below, to do that.

Illustration 21: Add folder form

Displaying new bookmark folders

You can use the #showBookmarks() macro to display your bookmarks on your website pages. The macro will display all of the bookmarks in one of your bookmark folders. The arguments are String folderName, boolean showFolderName, and boolean expandingFolder. The expanding folder feature is implemented using Javascript so, it will only work if the Roller Javascript file is included on the page where the macro is used.

For example, let's say that you want to display a folder named "News", you want to display the folder name, and you want to display it as an expanding folder. First, near the top and inside the <head> tag of your page, include the Roller Javascript page roller.js, as shown below:

...
   <html>
      <head>  
         <title>My badass blog</title> 
         <script type="text/javascript" src="/theme/scripts/roller.js"></script>
      </head>
   <body>
...

Later in your page, include the #showBookmarks macro to display your bookmarks:

...
   #showBookmarks( "News" true true )
...

6.4 - Bookmark import and export via OPML

Roller makes it easy to import bookmarks and build your blogroll by importing bookmarks in OPML format. XBEL might be a better bookmarks format, but OPML is more popular in the world of weblogs.

How to import OPML into Roller

1. download bookmarks in OPML format from a site such as Scripting.COM and save them as a file on your hard disk.

2. Login to Roller and choose the Bookmarks:Import menu option.

3. Use the file-upload capability to upload the OPML file into Roller. The bookmarks will be imported into a folder called "unfiled". You can use Roller to organize the bookmarks as you wish.

How to export OPML from Roller

Your bookmarks are automatically made available in OPML form via a URL of the form:

http://serverhostname/flavor/webloghandle?flavor=opml

You can also export one specific folder by using the path paramter. For example, if you have a folder called Solaris, export it like so:

http://serverhostname/flavor/webloghandle?flavor=opml&path=/Solaris

NOTE: For OPML export, Roller bookmarks must have at least a name and an HTML url; the name is taken from the text attribute (or if that is absent, the title attribute) of the OPML element, and the HTML url is taken from the htmlUrl attribute (or if that is absent, the url attribute) of the OPML element; if this forms a bookmark lacking a name or HTML URL then that entry will be silently skipped during import.

7 - Using weblog pings

Weblog update pings provide a means for you to notify aggregation and indexing sites, (for example Weblogs.com, Technorati and javablogs.com) that your weblog has changed so that they will pick up your latest content from your RSS feed.

Roller supports conventional XML-RPC weblog update ping mechanism used by many sites for such notifications.

7.1 - Registering with an Aggregator

Generally speaking, aggregation sites first require you to register your weblog with their site. During this registration process you normally provide both the HTTP URL and the RSS feed URL for your weblog. This is important because the ping message conveys only the normal HTTP URL of your site, and the site will use that to lookup the registered RSS feed URL to fetch from.

Aggegation sites that accept ping notifications generally publish the ping URL to use to ping their site on their (human-readable) web site. Once you have registered your site with an aggregator, you can set up your weblog to deliver pings to that site.

7.2 - Ping Targets, Common and Custom

You can set up the Roller server to ping sites of your choice automatically whenever you post published updates to your weblog.

Roller uses the term ping target to refer to a site, such as an aggregator, that accepts weblog update ping notifications. A ping target is configured with a (display) name and the ping URL needed to reach the site. Before you can send a ping to a site, you must configure a ping target in Roller for the site. Roller supports the configuration of two types of ping targets:

• common ping targets
  These are ping targets that are configured by a Roller administrator, and are available to be used by all users. This allows the ping URLs for several well-known aggregator sites to be configured once for everybody.
• custom ping targets
  These are ping targets that are configured by individual users. If you don't find the site you wish to ping in one of the common ping targets, you can configure your own custom ping target.

7.3 - Setting up Automated Pings

Once a ping target (either a common ping target or a custom ping target) has been configured for the site that you wish to ping, you can use the Weblog:Pings page (shown below) to enable automatic pings and send manual pings.

Illustration 22: Automatic ping configuration page

To enable automatic pings to a ping target, find the ping target on the page and click the Enable link in the Automatic column. The status indicator turns to ON and the link changes to Disable (as shown for some sites in the screenshot above). To disable automatic pings to a ping target click the Disable link in the Automatic column. The status indicator turns to OFF and the link changes to Enable.

Custom ping targets that you have configured are displayed on this page in a separate table below the common ping targets; they work in the same way. You may need to scroll down the page to see them

When you have enabled automatic pinging for a ping target, Roller will automatically send a ping to that site whenever you publish a new weblog entry or update a published weblog entry.

Note: In actuality, Roller queues a request to send the ping and processes this request in the background, so that you can get on with your blogging. The ping queue is processed at an interval configured by the site administrator; this interval is 5 minutes in a default configuration. In case the aggregator site is temporarily unreachable, Roller will requeue your ping request and retry on subsequent passes through the queue; in a default configuration the ping is requeued for up to 3 ping attempts.

7.4 - Sending a Manual Ping

You can also send a manual ping to a ping target using the Send Ping Now link listed for the target on the Weblog:Pings page. When you send a manual ping the ping is not queued, it is sent immediately and attempted only once. Roller shows you the response status (success or a failure message) that results from the ping. Using manual pings, you can test your custom ping targets to make sure that the URL you have entered is working properly.

You do not need to enable automatic pinging in order to send manual pings. You can send a manual ping whether or not you have enabled automatic pinging for that target.

You can use manual pings if you ping a site very rarely, or if you are feeling a bit impatient, and you don't want to wait for the next queue processing interval.

7.5 - Creating and Editing Custom Ping Targets

You should find that most popular ping targets are listed among the common ping targets and you can ping these without needing to create a new custom one. If you don't find a common target listed for the site you wish to ping, you have two options. You can request that your administrator add a new common ping target (directions in [21]); most likely, your friendly Roller administrator will be happy to add new common ping targets for aggregator sites that many other users will also be interested in using. Alternatively, you can add your own custom ping target using the Weblog:Custom Ping Targets page.

Note: Custom ping targets are a feature that the administrator can disable. If you do not see Weblog:Custom Ping Targets menu item, or any heading for Custom Ping Targets on the Weblog:Pings page, then an administrator has disabled it, and you will need to contact an administrator to get a new common ping target added.

Before adding a custom ping target, you must determine the proper ping URL for the site that you wish to ping. You must get this information from the aggregator's web site or from another knowledgeable source.

It can be hard to find the aggregator's documentation telling you the specific ping URL to use to notify their site. Commonly aggregators list this on their web site under a topic providing help about registering your feed, or under a topic providing information for developers. Keep in mind that some aggregators only use periodic polling and do not accept ping notifications at all. If you can't find any information about pinging on the aggregator's web site, the site may not support pinging.

Once you have found the proper ping URL, you can add your custom target using the Weblog:Custom Ping Targets page, which looks something like the following screen-shot.

Illustration 23: Custom ping targets page

Click the Add New button to add a new custom ping target. This will bring up a form with a Name field and a Ping URL field. Fill in both fields, and click the Save button.

Illustration 24: Edit ping target form

Once you have created a custom ping target, you will see it listed on the Weblog:Custom Ping Targets page. From this page, you can further edit it or delete it. To enable automatic pings or send manual using your custom ping targets, use the Weblog:Pings page.

The ping target's name must be unique among your own custom targets, and the Ping URL must be a properly formed URL with a known hostname (or a raw IP address). If any of these conditions are not met, the Save will fail, and you will get an error indication telling you what was wrong with your entry

7.6 - More on Registering with an Aggregator

When you register with an aggregator, you will usually need to provide two pieces of information as part of the registration, your blog's base (HTML) url and your RSS feed (XML) URL. Make sure to read the aggregator's documentation and help on registering.

For Roller weblogs, you get your weblog's base URL by viewing your weblog and taking the URL to the point just following your weblog's handle. (In other words it should end with page/handlenamehere).

The RSS feed URL for your whole feed can be obtained by substituting page in your weblog's URL with RSS. Most browsers will display this link in the status bar when you place your mouse over RSS badge (the little orange XML box) on your weblog page.

You also have category-specific feeds, which are useful for registering with topical aggregators like java.blogs. To get a category-specific feed URL, just append ?catname=/category/path where /category/path is the full path of the category. The "basic" theme has some category RSS feeds just below the RSS badge in the right-hand vertical bar.

Some aggregators can also scrape (read and parse the HTML of your weblog) to discover the feed URL automatically when provided with the HTML URL. The default Roller theme template pages include hints in the form of tags that many sites can use to determine the feed URL automatically.

          {{name}{url}}