User Guide

Apache Roller

Version 2.3-incubating

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

To create a new weblog entry, go to your weblog's New Entry page, enter a title in the Title field, enter the your post in the Content text area, choose a category from the Category combo, and hit the Post to Weblog button. As soon as you do that, your weblog entry is posted to your weblog for the world to see. Here is the relevant part of the New Entry page.

Illustration 7: Weblog editor

The above screenshow shows the RTE weblog entry editor (editor-rte.jsp), a rich text editor that creates the HTML for you. If you prefer to edit the HTML yourself, you can switch to the plain text editor (editor-text.jsp). Use the Preferences:Settings page to pick the weblog editor page you'd like to use.

Let's cover the fields on the page:

• Title: this is the title for your post, it is required.

• Category: You must pick a category for your entry. You can change the list of categories available in your weblog by using the Create & Edit:Categories page.

• Pub Time: You don't need to set this unless you want to post at a specific time in the past or in the future. The best thing to do is to leave it blank. Roller will set it for you when you click the Post to Weblog button to publish your new weblog entry.

• Status: This field displays the status of your weblog entry. The possible values are Not saved, Draft and Published.

• Summary (optional): For long posts, you might want to enter a sentence or two as summary in addition to the content. If you do, your short summary will appear on the front page of your weblog and the content will appear on the single-entry view. Your summary will also be included in your newsfeed in an <atom:summary> element.

• Content: This is where you put the body of your weblog entry.

Below the weblog entry fields are the Other Settings

• Comment Settings: Click on the little plus-sign plus (+) to expand the Comment Settings control, where you can enable/disable comments on your blog entry.

• Plugins to Apply: This control allows you to pick which plugins are to be applied to this entry. For example, if you want ;-) smilies in your text to be replaced with smiley-face images, choose the emoticons plugin. You can set which plugins are to be applied by default on your weblog's Preferences:Settings page. Note that your Roller site administator controls the list of available plugins. Here's the current list of plugins included in Roller:

• Convert Line Breaks

• Topic Tags

• Textile Formatter

• Acronyms

• Bookmark Linker

• Email Scrambler

• Emoticons

• Read More Summary – deprecated: use a summary instead

• Misc settings: Here you can control misc. settings like text right-to-left and, if you're an administaror, you can "pin" an entry to the top of the front-page of the site.

• MediaCast settings: This control allows you to specify the URL of a file to be included in your blog entry as an RSS enclosure, also known as a podcast. See the next section for more information on podcasting with Roller.

Below that is a row of buttons.

• Post To Weblog: Don't click this button until ABSOLUTELY SURE you're ready to publish your weblog entry for the entire world to see.

• Submit for Review: If you only have limited blogger rights in the weblog, you won' t see the Post to Weblog button because limited bloggers are not allowed to publish directly. Instead, you'll see a Submit for Review button. Click this button when you are ready for the authors of the blog you are working in to review your work and either publish or save it as a draft and ask you to revise it.

• Save as Draft: Click this button to save your post as a draft entry for editing later.

• Preview: Click this button to see what your post will look like when displayed in a browser. Not that preview is not exactly like what you'll see because you weblog may have different font and style settings than the edit weblog page, but it will be pretty close.

• Spell Check: Click this button to spell check your post. Be forewarned that Roller's spell checker is far from perfect. It catches HTML tags as spelling errors and its user interface is clunky. We're investigating alternatives.

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 Weblog Category Chooser (displayed by the #showWeblogCategoryChooser() macro) 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. All of the stock Roller weblog templates display a list of your RSS feeds (displayed by the #showRSSLinks() macro), 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 - 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.4.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/resources/nina/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 
	by clicking on this file name:

	<a href="http://example.com/roller/resources/nina/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/resources/nina/mycast.mp3" 
		type="audio/x-mpeg" length="3409127" />

That's all there is to podcasting with Roller.

3.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.

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.

3.6 - 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.

3.7 - 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.

3.8 - 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.

3.8.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.

3.8.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.

3.9 - 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 - 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 website 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 Prefences 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.

4.1 - Weblog settings

The Preferences:Settings page allows you to set the configuration parameters for your weblog. You can see all of the settings on the screen-shot below (which needs to be updated to Roller 2.1):

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.

• Locale: Choose the language and country for this weblog. (Which is used how?) (See section x.x for setting the locale for your user account.)

• Timezone: Choose the timezone for this weblog. (Which is used when displaying entries?)

• Default from address: Enter the email address that should be used as the from address for emails sent by Roller. (Removed from Roller 2.1?)

• Page to be used as the homepage - Choose a page template to be used as the main page of your weblog. (Removed from Roller 2.1?)

• Weblog is active

• 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)

• Number of entries to display on weblog: Enter the maximum number of entries to be displayed on 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.

Illustration 15: Weblog settings page part 2

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 recieved 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.

4.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 section 5 - Customizing your weblog's them for more information on theme customization.

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.

4.3 - Uploading Files

Roller includes a file-upload feature that allows you to upload images and other files for use in your weblog.

Here are the steps to upload an image to Roller and to use it in a blog entry:

• Upload the file: Use the Ceate & Edit:File Uploads page to upload your image file. Once it is loaded, locate it in the list of file uploads, right-click on it and copy the link.

• Create a weblog entry: Use the Create & Edit:New Entry page to add or edit a weblog entry.

• Include the image: Place an HTML <img> tag where you want the image in your blog entry.

If you don't know HTML, you might need help with that last step. Here is what an <img> tag looks like.

<img src="http://jroller.com/resources/mrroller/leo.gif" alt="one happy baby" />

You need to include the src attribute and it's also good form to include an alt attribute that describes the image (for those who cannot see the image).

4.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 17: 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'.

5 - Customizing your weblog's theme

When you create a weblog, you must select a theme. The theme defines how your weblog will look in terms of page layout, fonts, colors and images. If you don't like your theme, you can use the Preferences:Theme page to switch to a different one.

If you're not happy with the set of themes built-into Roller, you can create a custom theme by changing the templates used to display your weblog. To customize your theme, go to the Preferences:Theme page and click the customize button. That will copy the templates that define your theme into your weblog where you can edit them. After you click customize, go to the Preferences:Templates page to view a list of the templates that define your weblog's appearance.

Weblog templates

Your weblog's theme is defined by a set of templates. A template is a file with some special macros that indicate where Roller is supposed to put your weblog entries, weblog calendar, and other dynamically created content. See the Roller Macro Reference for a complete listing of the Roller macros. A template can be an HTML file, an HTML fragment, a CSS page, or just about anything else you can enter into Roller as text.

Roller uses the powerful Velocity template language to define templates and this gives you a lot of power and flexibility in customizing the look and feel and layout of your weblog pages. You can set and use variables, use if-then-else statements and specially designed macros to control your weblog's appearance. For more information on the Velocity template language, refer to the Velocity web site and the Velocity Reference Guide.

Below is the Roller Preferences:Templates page. Use this page to add, remove, and to select pages for editing.

Illustration 18: Weblog templates page

Editing a weblog template

Below is the Preferences:Edit Tempate page which you use for editing of your page templates. Note that if the page name begins with an underbar "_" then the page will not appear in your weblog's navigation menu.

Illustration 19: Edit template page

5.1 - Weblog and day templates

Every Roller theme is a little different, but all themes have a minimum of two templates: a Weblog template, which defines the main page of your blog, and a _day page, which defines how each day of entries are displayed on your weblog. Let's discuss each of these templates.

Your Weblog page

Your weblog page is the main page of your web site, the one that is specified as the default page in your Preferences:Settings page. This page is the page that displays the entries in your weblog, your weblog calendar, etc. This page can be very complex, or very simple, depending on your page design.

To understand the weblog template, let's take a look at a simple example. Below is the weblog page template from Roller's Basic theme. This is a good example because it is so basic and because it uses most, if not all, of the Roller macros that you'd want to use on a weblog page. Roller macros and Velocity expressions are shown in bold.

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>    
  <title>#showWebsiteTitle()</title>    
  <style type="text/css">#includePage("_css")</style>
  #showRSSAutodiscoveryLink()
<script type="text/javascript" src="$ctxPath/theme/scripts/roller.js">
</script>
</head>  
<body>  
<table border="0" align="center" width="95%"><tbody><tr>        
  <td class="entries" width="80%" valign="top" bgcolor="#ffffff">
    <center>
      <h1>#showWebsiteTitle()</h1> 
      <p class="descrip">#showWebsiteDescription()</p> 
      #showWeblogCategoryChooser()<br>
    </center>            
    #showWeblogEntries("_day" 15)
  </td>        
  <td width="20%" valign="top" bgcolor="#ffffff" width="20%">
    <h2>Calendar</h2> 
    #showWeblogCalendar()<br>            
    <h2>RSS Feeds</h2> 
    #showRSSBadge()<br>
    #showRSSLinks()
    <h2>Links</h2>
    #showBookmarks("Blogroll" true false)<br>            
    #showBookmarks("News" true false)
    <h2>Navigation</h2>
    #showBasicNavBar(true)<br>            
    #showEditorNavBar(true)<br>
    <h2>referrers</h2>
    #showreferrers(30 20)
   </td>
</tr></tbody></table>
</body>
</html>

For a listing of key Roller macros and variables, refer to the section below. The most important macro on the page is the #showWeblogEntries macro. As you can see, it takes two arguments, the first is the name of the day page to use in the display of the weblog entries and the second is the number of weblog entries to be displayed on the page.

Your Day Page

Your Day page is used by the #showWeblogEntries macro to display your weblog entries. This is where you customize the display of each day and of each weblog entry. Returning to our example, below is the day page from the Basic theme:

<div class="box">
<div class="entry">
   #showDayPermalink( $day )
   #showEntryDate( $day )
</div>
#foreach( $entry in $entries )
   <p>
   <b>$entry.title</b> $entry.text
   <span class="dateStamp">($entry.pubTime)</span>
   #showEntryPermalink( $entry )
   #showCommentsPageLink( $entry )
</p>
#end   
#showLinkbacks( $day )
</div>

Note that there are two variables $day and $entries available for use in the day template that are not available in other templates. The $day variable refers to a date object (java.util.date) that contains the date of the day that is being rendered by the day page. The $entries variable contains a collection of weblog entry objects (org.roller.model.WeblogEntryData). The example above uses a Velocity #foreach loop to iterate through the individual entries in the entries collection and to display the title, text, and publish time of each.

5.2 - Define standard headers and footers with a decorator

Some themes use a decorator, a special page that serves as a sort of Master Template for a website (i.e. for your blog). A decorator allows you to define a standard header and footer for all of your pages so that you don't have to repeat the same header and footer on every page. If your website defines a page named _decorator (and all new Roller themes do), then Roller will use that _decorator to display all of your pages.

Here is an example of a decorator page. At page display time, Roller will insert the contents of the page being displayed where you see the $decorator_body marker below:

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- decorator began with line above -->
<html>
<head>
    #showContentType("text/html; charset=utf-8")
    #showContentLanguage($locale.language)
    #includePage("_css")
    #showRSSAutodiscoveryLink()
    <script type="text/javascript" src="$ctxPath/theme/scripts/roller.js">
    </script>
    <title>#showWebsiteTitle() : #showPageName()</title>
</head>
<body>
<!-- next print \$decorator_body -->

$decorator_body

<!-- now print decorator footer/close html -->
</body>
</html>

If you have a decorator like the above, then you don't need to include <html> and <body> tags on your individual pages.

5.3 - Roller Macros and Variables

For a complete list of the Roller Macros, see the Roller Macro Reference.

There are also a host of variables and objects that are available for your use in page templates:

$now	The current time (a java.util.Date object).
$ctxPath	The path under which Roller is running (see Webapp context).
$baseURL	Base URL for your Roller website
$absBaseURL	Absolute base URL for your Roller website.
$uploadPath	The location where uploaded files are placed.
$user	The current user object for the page/entry being viewed.
$userName	The current user's username.

$fullName	The current user's full name.
$emailAddress	The current user's email address.
$website	The website for the current user.
$page	The current page being viewed.
$requestParameters	A map of the request parameters
$rollerVersion	Version number of Roller software
$utilities	A utilities object
$stringUtils	A string utilities object

Date formatting variables and objects:

$dateFormatter	Date formatter object
$toStringFormat	A date format to be used with the macro formatDate( $dateFormat $date ) : EEEE MMMM dd, yyyy
$plainFormat	Another date format for use with the formatDate() macro: yyyyMMdd

If the page is a day page template, then these variables are available too:

$day	Date object holding date being displayed
$entries	Collection of entries for date being displayed

If the page is a comments page, then these variables are available:

$isCommentPage	will be set to true
$entry	weblog entry containing collection of comments
$autoFormat	True if comments should be autoformatted
$escapeHtml	True if HTML should be escaped

5.4 - Creating and packaging your own Roller theme

A Roller theme is, at a minimum, a subdirectory in the Roller themes directory with a page template named Weblog.vm in it. How does Roller determine what themes are available? Roller considers every subdirectory in the themes directory to be a theme.

How does Roller create a theme?

When you create a new user or switch themes for an existing user, Roller will read in a new theme for that user. When Roller reads in a theme for a user, all it is does is to create or replace the user's page templates. Roller follows these steps to read in a theme:

1. For each file in the theme's subdirectory that ends with .vm Roller creates a page template with the same name as the file, minus the .vm extension

1. The page template that is named Weblog is set to be the website's default page.

Including images, Javascript and CSS style sheets in a theme

If you want to create a more sophisticated theme, one that takes advantage of the Roller theme macros, you can use the following directory structure for your theme (as illustrated in the x2 theme):

Illustration 20: Theme directory structure

The page templates go in the root directory of the theme, images in the images directory, Javascript files in the scripts directory, and CSS style sheets in the styles directory. Then, you can make your theme distributable by using relative paths to get to all of your themes images, scripts, and style sheets. You do this by using the Roller theme macros, listed below, whenever you refer to a file in your theme:

• #showThemeScript( themeName, scriptFileName )

• #showThemeScriptPath( themeName )

• #showThemeStyleImport( themeName, scriptFileName )

• #showThemeStyle( themeName, styleFileName )

• #showThemeStylePath( themeName, styleFileName )

• #showThemeImage( themeName, imageFileName )

• #showThemeImagePath( themeName, imageFileName )

• #showThemePath( themeName )

5.5 - Overriding Roller Macros

When creating your custom theme, you may find that a Roller macro, such as #showEntryDate( $day) does not produce the output that you want. You should first check the Roller Macro Reference to see if there is another macro that does what you want. If not, you can replace the call to the macro with a modified version of the code that makes up the macro.

For example, if you have the following fragment in your _day template:

   <div class="entry">
      #showDayPermalink( $day )
      #showEntryDate( $day )
   </div>

and you don't like the default output generated by #showEntryDate().

   Thursday January 05, 2006

You can look at the definition of #showEntryDate in weblog.vm:

   #**
    * Display the default Date.toString for date using the    
    * 'macro.weblog.date.toStringFormat'
    * format as defined in the resource bundle.
    * @param toStringFormat Format string (see java.text.SimpleDateFormat).
    * @param day Date object that specifies day (type java.util.Date).
    *#
   #macro( showEntryDate $day )
       #set( $format=$text.get("macro.weblog.date.toStringFormat") )
       #formatDate( $format $day )
       ##formatDate( $toStringFormat $day )
   #end

You could then modify the "entry" div in your _day template as follows:

   <div class="entry">
      #showDayPermalink( $day )
      #formatDate( "MM/dd/yyyy" $day )
   </div>

Now the generated date will look like this:

   01/05/2006

Warning: This is for advanced users only. If you make an error your web page may not display correctly, or display at all.

You can find the source for the various Roller macro .vm files in the Roller distribution that matches your installation. Todo: add links to on-line versions of the latest .vm files. (?)

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 21: 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 22: 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 23: 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 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/roller/fredsblog), then your paramters would be:

Username: fred

Password: (your password)

BlogID: fredsblog

URL: http://blogs.sun.com/roller/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/xmlrpc

8 - 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.

8.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.

8.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.

8.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 24: 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.

8.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.

8.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 25: 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 26: 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

8.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}}