docs/roller-user-guide.adoc

= User Guide
Apache Roller Weblogger
:toc:
:sectnums:
:imagesdir: ./images

== Overview

This document is a user guide to the Apache Roller Weblogger, the
Java-based and open source weblog server that is produced by the Apache
Roller project of the Apache Software Foundation.

There are separate guides available on other topics; a Template Guide
for those who wish to customize the layout and design of their weblog
pages and an Installation Guide for those installing the Roller software
on a web server.

=== Copyright and trademark information

The contents of this document are subject to the terms of the Apache
Software License.

All trademarks within this document belong to legitimate owners.

=== Feedback

Please direct any comments or suggestions about this document to:
dev@roller.apache.org

== Introduction

This user guide describes how to use the Apache Roller Weblogger or
Roller for short, 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. You’ll learn how to create
one or more weblogs for yourself or a group of your friends. You’ll
learn how to create, edit and post weblog entries. We will also cover
more advanced topics such as adjusting your weblog’s settings, how to
customize your blogroller, how to manage weblog pings and more.

First, let’s get some terminology out of the way because there’s a lot
of jargon in weblogging. Here’s a list of some of the terms we use in
this manual without a whole lot of background.

* *Weblog*: A set of web pages and RSS/Atom feeds that display weblog
entries written by one or more authors, uploaded images, bookmarks and
comments posted by visitors. Weblog entries are displayed on the main
page of the weblog and in the weblog’s feeds in reverse chronological
order.
* *Weblog entry*. A single weblog entry with a title, publication
timestamp, summary, content and some settings that indicate if and when
comments are allowed.
* *Comment*. A comment posted by a visitor to a weblog and regarding one
specific weblog post. A comment has an email address, a publication
timestamp and some content.
* *Templates*. Each Roller weblog is defined by a set of HTML and CSS
templates that provide the layout and styles for the weblog. Normally
templates are authored using Velocity template language, but other
languages are possible via plugins (i.e. Groovy Server Pages, JRuby,
etc.)
* *Feed*. A feed is an XML representation of the most recent entries,
comments or other data. Folks can subscribe to your feed to be alerted
of new weblog entries and comments posted. Roller supports both RSS and
Atom formats for feeds.
* *Feed reader*. Software that makes it easy to subscribe to and read
feeds, e.g. Google Reader, Net News Wire, Feed Demon, etc.
* *Blog client*. Software that makes it easy to post to your weblog,
e.g. Ecto and Mars Edit.

With that out of the way, let’s get started blogging with Roller.

== Getting started with Roller

Getting started with Roller means different things to different people.
If you are using an existing Roller server, then getting started means
registering a new user and creating or joining a weblog. If that’s the
case for you, skip ahead to section 3.2. If you just finished setting up
your own Roller installation on your own web server, then getting
started means a little bit more. You’ve got a little post installation
work to do.

=== Getting started with a new Roller installation

Once you’ve got Roller up and running you will see a screen like the one
below, which explains exactly what you’ve got to do to get started with
Roller. First, create a new user so you can login. Second, login and
create a weblog for yourself or one to server as the front page of the
site or both. Third, designate which weblog is the front page weblog.

image::user-guide-1-welcome.png[]

**Creating the first user. **Your first step is to create a new user.
Remember, the first user you create will be given administrative
privileges. You might want to use the username "admin" or something
similar. Later, you can login as the admin user when you need to change
site-wide settings. If you wish, you can grant other users admin
privileges so they can help out with admin duties. Let’s take a look at
the user registration page. You can see the new user registration form
in the next section.

**Create the first weblog(s). **Next you should create at least one
weblog. See section 3.2 below for some more information the create
weblog page. If you are running a personal blog site, then you might
want your weblog to serve as the front page of your site. In that case,
create a weblog, use a normal weblog theme (i.e. not the Roller Homepage
theme) and assign your weblog as the front page weblog of the site.

If you are running a community weblog site with multiple weblogs, then
you will probably want to create a weblog to serve as the front page of
the site. Create a new weblog, name it "main" or "community" or
something suitable because its name will appear in URLs. And we
recommend that you use the Roller Homepage theme because it is specially
designed to serve as a weblog community front page, aggregating all of
the site’s weblogs together but having no content of its own.

**Designate a front page weblog. **Once you’ve created a front page
weblog, whether it be a personal weblog or a community aggregator, you
need to tell Roller. So, select your front page weblog and, if you are
running a community site then set the _Enable aggregated site-wide
frontpage_ checkbox before you click Save.

If you’ve read this far, you’ve probably created your own user and
weblog and if so you can skip the next section.

=== Creating a new user and weblog

To create a new user use the Register link, which can be found in the
top right of the Roller login page. That link will take you to the New
User Registration page shown below.

image::user-guide-2-registration.png[]

The New User Registration form is pretty self-explanatory, but keep in
mind that your username cannot be changed; it is your unique identifier
in the system. But that’s OK because your screen name is the name that
will be displayed on your weblog and in your feeds and you _can_ change
it later if you wish.

Instead of username and password, the Roller administrator may provide
(or require) OpenID (http://openid.net/[http://openid.net])
authentication. With OpenID you will not provide a password (as you will
be logging into another system to authenticate) but just your OpenID
account name, whose format will vary based on the OpenID provider. For
example, using Google+ as your OpenID provider will result in an account
name similar to https://profiles.google.com/<numeric-ID >, where the
numeric identifier can be determined simply by Googling your name along
with "google plus". (Note the OpenID string does _not_ use the
plus.google.com domain returned by this query.)

**Picking your language and timezone. **You can set your language of
choice and timezone too, but these values don’t do much in Roller. The
locale and timezone of your weblog are really what matter. The values
you set here will be used as your defaults when you create your weblog.

**Creating a weblog . **Once you’ve created a user, then log in and
you’ll see the Roller Main Menu page and a greeting that reads:

You’ve got a user account, but no weblog. Would you like to _create
one_?

Follow that link to create your first weblog. You’ll see the form below.

image::user-guide-3-webblog.png[]

The form is designed to be self-explanatory. Note that you can change
everything later, except for the weblog handle, which is the unique
identifier for your weblog.

Now that you’ve got a user and a weblog, let’s discuss how to get around
in the Roller interface.

=== Getting around in Roller

Once you’ve logged into Roller’s editor pages you should be able to find
your way around using Roller’s tabbed menu. To provide a little extra
assistance, Roller displays a status bar at the top of each editor page.

For example, the status bar below indicates that you are logged in as
user 'admin' and you are not editing a weblog. You can go directly to
the front page of the site by clicking the first link on the right (it
might not be labelled Front Page on your site), to the main menu with
the second link and you can log out entirely by using the Logout.

image::user-guide-4-statusbar.png[]

For example, the status bar below indicates that you are logged in as
user 'admin' and you are editing a weblog with the handle 'adminblog'.

image::user-guide-5-statusbar-webblog.png[]

If you are not logged into Roller then you can either access the login
link directly or use a Login link from one of the weblogs on the site.
The login link is of this form:

_http://hostname/roller-ui/login-redirect.rol_

Or this form if Roller is installed under its own context:

_http://hostname/roller/roller-ui/login-redirect.rol_

You probably won’t need to cut-and-paste that link because most weblogs
display an author menu like so:

image::user-guide-6-navigation.png[]

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.

== Creating and editing your weblog

First, you log in 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.

image::user-guide-7-main-menu.png[]

The main menu page lists all of your weblogs and for each, shows you
links to its New Entry, Entries, Comments, Theme and Settings pages. You
can also create a new weblog, edit your user profile.

If you are logged in as a Global Administrator, you will also see a
Server Admin link in the actions side-bar. And if you have Roller’s
Planet aggregator enabled, then you will also see a Planet Admin link
there as well.

=== Creating and editing a weblog entry

Use the *Create & Edit -> New Entry* page (also known as the Weblog
editor page) to create, edit and publish weblog entries. Using this
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.

image::user-guide-8-editor.png[]

==== 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 permalink (URL) for your weblog
entry (up to the first five words of the blog title, separated by
hyphens). 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.
+
To generate a permalink different from the actual blog title, first type
in the desired permalink, then hit Save As Draft which will create the
permalink. Then change the blog title to whatever desired for the blog
entry prior to publishing it—the permalink won’t change.
* *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 been 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 (see Title section above), and it cannot
be changed later. As a workaround for getting a new permalink, the text
of a blog entry can be copied to a new blog entry with the desired
permalink and the published date set back to that of the original blog
entry (Advanced settings). Once the new blog entry is published, then
just delete the old blog entry with the undesired URL. However, be
cautious about changing a permalink in this manner because all external
links to original blog entry will be broken as a result.
* *Category* – You can pick one category for your weblog entry.
Categories are for folks who want to organize their weblog entries by
subject. You can add and remove categories via the Categories page.
* *Tags* – (optional) In addition to assigning each of your weblog
entries to a category you can also tag them. You can assign a list of
tags to each entry. You can use any tag name you want. Separate your
tags with spaces. Currently, the only way to do multi-word tags is to
use an underbar, for example to tag something with "apache roller" you
would use the tag apache_roller. 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 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.

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

==== 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 Settings page.

image::user-guide-plugin.png[]

==== Weblog editor advanced settings

If you expand the _Advanced Settings_ control, you’ll see what’s below.

image::user-guide-settings.png[]

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 p__odcast__ in your weblog’s RSS feed, then enter the URL of that
file here.

=== Finding and editing weblog entries

All of your weblog entries are saved in a database. Once your entries
scroll off the front page or off the recent entries list of the weblog
editor page, they are still available via next and previous links
displayed on your weblog and via the weblog calendar that is included in
most weblog themes.

You can also access your entries via the Edit Entries page, which allows
you to search entries via keyword, category, tags, date and status.

image::user-guide-9-entries.png[]

=== Managing categories

Each weblog can define its own unique list of categories to be used for
categorizing weblog entries, using the Categories page shown below. When
you or another author of your weblog creates a new entry you _must_
choose one of the categories you have defined.

image::user-guide-10-categories.png[]

You can use the Categories page to add new categories and to edit your
existing ones. You can change category names if you wish. And you can
also delete categories and if a category is in use you will be asked to
re-categorize the entries in that category.

You can also define icons for each category, but support for icon images
has not been coded in most Roller themes, requiring you to do template
customization if you wish to display them.

=== 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. Individual blogroll items are known as _bookmarks_. Use the *Create &
Edit:Blogroll* page to add, edit and delete bookmarks and bookmark
folders in your blogroll.

image::user-guide-11-blogroll.png[]

=== Uploading images and other files to your weblog

When you paste or drag a local PNG, JPEG or GIF image into the rich text
editor, Roller stores it as a media file when uploads are available to you.
If uploads are unavailable, Roller keeps the image in the entry. By default,
a content or summary field with inline images is limited to 60,000 UTF-8
bytes, including the surrounding text. If an older entry contains embedded
images, saving it again applies the same rule. An administrator can set
`weblog.inlineImages.preferInline=true` in `roller-custom.properties` to
prefer inline images even when uploads are available, and can change the
limit with `weblog.inlineImages.maxFieldBytes`. On MySQL, alter the
`weblogentry.text` and `weblogentry.summary` columns to `MEDIUMTEXT` before
raising the limit, because a `TEXT` column holds only 65,535 bytes. Custom themes with a
Content Security Policy must allow `data:` in `img-src` to show inline images.

A pasted image is sent with the entry form as base64 text, about 4/3 of the
image's size. Servlet containers limit the size of a form POST; Tomcat's
`maxPostSize` defaults to 2 MB, so a pasted image larger than about 1.5 MB is
refused with a "form is too large" message even when it is within the upload
limit. To accept larger pasted images, set `maxPostSize` on the Tomcat
`Connector` to at least 4/3 of `uploads.file.maxsize`, plus room for the
entry text.

If you’d like to upload images or other files for use in your weblog, go
to your weblog’s *Create & Edit -> Media Files* page, the media library.
From there you can upload, find and organize files, and post them to your
weblog.

The library shows one folder at a time. The folders are listed on the left;
on a narrow screen, choose the folder from the list at the top instead. Files
show as a grid of previews, or as a list with name, type, size and upload
date; use the two buttons at the right above the files to switch. Your choice
is kept in your browser. The library shows 48 files a page, newest first. Use
the menu next to those buttons to sort by oldest first, name or type, and the
buttons below the files to move between pages.

==== How to upload files

Click *Upload files*. Choose the folder for the files, then choose files with
the file picker or drag them onto the page. You can upload up to 20 files at
a time; the page shows this limit and the size limits your site allows. Each
file is listed with its name and size, and you can remove a file from the
list before you upload.

Under *Apply to these files* you can enter a description, tags and a
copyright statement for all the files, and choose whether to include them in
the Gallery, which makes them available in the Media File Feed for your
blog. Each file keeps its own name; you can rename a file later on its
details page.

The description of an image is its _alt text_: Roller uses it when you insert
the image in an entry, for readers who cannot see the image. Describe what the
image shows.

Click *Upload*. Each file in the list shows whether it was uploaded or why it
failed. If some files fail, *Retry failed files* sends only those files again;
files that were uploaded are never sent twice. If the connection is lost
after the files were sent, Roller cannot tell which files were saved. Open
the folder to check before you upload them again.

When the files are uploaded, Roller shows the *Upload Complete* page with the
files that you uploaded and offers to include them in a new weblog post for
you. You can choose any or all of the images, or skip this step and return to
the library.

==== How to find files

Enter the start of a file name in the search box and click *Search*. Upper
and lower case do not matter. Next to the box, choose whether to search the
current folder or all folders. To show only one type of file, click *Image*,
*Video*, *Audio* or *Others* above the files; *All* shows every type.
*Filters* has more criteria: file size and tags. The line above the results shows what you
searched for and how many files match; *Clear search* returns to the folder.

==== How to see and edit a file

Click a file’s preview or name to open its details page. It shows a larger
preview, the file’s type, size, image dimensions, upload date and folder, and
its URL. *Copy URL* copies the URL for use elsewhere, *Open original* opens
the file, *Create entry* starts a new weblog entry with the file, and
*Delete* deletes it.

Below that you can edit the name, description, tags, copyright statement,
folder and Gallery setting, and click *Save*. *Back to the media library*
returns you to the same folder, search, sort and page that you came from.

==== How to use folders

You can use folders to organize your files. You can move files around and not
worry about breaking any links because folder and file names are not part of
file URLs.

To create a folder, click *New folder* above the folder list, enter a name
and click *Create*.

To select a file, point at its preview and click the checkbox that appears
in the corner; on a touch screen the checkboxes are always shown. While files
are selected, the bar above the files shows how many are selected and what
you can do with them. *Select all on this page* selects every file on the
current page, and the *X* clears the selection.

To move the selected files, click *Move to* and choose the folder.

==== How to delete files and folders

To delete files, select them and click *Delete* in the bar above the files, or click *Delete* on a file’s details page. You will
have to confirm the delete before it executes. Deleting a file cannot be
undone, and links to it stop working.

To delete a folder, open it and click *Delete folder* below the files. This
deletes the folder and all the files in it. You cannot delete the default
folder.

==== How to post media files to your weblog

We explained above how to post images during the upload process. From the
Blog entry edit page, click on the "Add Media File" link located above and to
the right of the Content field. Choose a folder, or search for the file by
name, and click the file. Roller inserts an image as a thumbnail that links to
the full image, with the image’s description as its alt text, and inserts any
other file as a link. Roller inserts the media file at the cursor location in
the content field. If there’s a problem with the insertion location, hit
Ctrl-Z to undo the action and try again.

==== How to post a podcast to your weblog

Upon uploading a non-image media file, such as a podcast, Roller
provides you an option to create a new blog entry with that media file
(podcast). If chosen, Roller will include the media file in the post
content and in the Enclosure URL field in the Advanced Settings section
of the Blog Edit Entry page. The Enclosure URL field is used just for
your blog’s RSS and Atom feeds, it will include the podcast as a feed
enclosure (http://en.wikipedia.org/wiki/RSS_enclosure) to make it easy
for podcast readers to fetch it.

Alternatively, you can select an podcast from the Add Media File link
referenced in the previous section, which will add its URL to the post
content, and then copy that URL to the Enclosure URL field in the
Advanced Settings section if you wish to add it to your blog’s RSS
and/or Atom feeds.

=== Podcasting with Roller

Roller 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 downloads the audio
files that are referenced in your newsfeed and copies them to an music
player, such as an MP3 player.

This section assumes that you want to upload your podcasts to some other
server, one with lots of space and bandwidth, and not to Roller. If you
want to upload your podcasts to Roller, then see *Section 4.5.7* for an
explanation of posting a Media File to your weblog as a podcast.

==== *How to create a podcast feed with Roller*

In Roller a Podcast is like an attachment to a weblog entry. Here are
the steps involved in Podcasting with Roller:

* Record an interesting Podcast (that’s the hard part, by the way) and
save your Podcast in MP3 format or whatever format you prefer.

* Upload your Podcast to a web server somewhere and take note of your
Podcast’s URL. For example, if you were to upload a file to Roller, then
the URL might look something like this:

_http://hostname/roller/yourname/resource/mycast.mp3_

* Create a new Roller weblog entry announcing 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. For example:

Hey now! I just created my first Podcast you can download it here: <a
href="http://hostname/roller/yourname/resource/mycast.mp3">mycast.mp3</a>

* And the most important step: in the lower-half of the weblog editor
page, you’ll see an expandable control labelled _Advanced Settings_.
Click on that to expand the control and paste in 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 Advanced Settings control has
picked up 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:

image::user-guide-podcast.png[]

* Roller will add the podcast to your RSS newsfeed as an _<enclosure>_.
You can check this by looking at your RSS newsfeed and any podcast
software that is subscribed to your feed will pick it up automatically.

<enclosure url="http://example.com/roller/nina/resource/mycast.mp3"

type="audio/x-mpeg" length="3409127" />

=== Using a weblog client with Roller

Using a nice weblog client like Ecto or MarsEdit can make it easier for
you to post to your Roller weblog. You can also post to your weblog
remotely from services like Flickr.com and del.icio.us. This is possible
because Roller supports a standard publishing protocols such as the
MetaWeblog API and the Atom Publishing Protocol. Here’s how to set up a
weblog client to post to Roller.

Configuring a weblog client for use with Roller

First, make sure to enable weblog client API support in your weblog via
your weblog’s Weblog Settings page.

image::user-guide-17-api.png[]

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 web services end-point

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
parameters 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 parameters would be:

* *Username*: fred
* *Password*: (your password)
* *BlogID*: fredsblog
* *URL*: http://jroller.com/roller-services/xmlrpc

==== Managing templates and categories with AtomPub

Roller's AtomPub service can also manage a weblog's templates and categories. The AtomPub Guide (`roller-atompub-guide`) documents every URI,
permission and XML element, with examples.

== Working with comments

Roller supports weblog comments, which are enabled by default. You can
turn them off on your weblog’s Weblog Settings page.

=== 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 Weblog
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.

=== Comment management

You can use the Comments page to manage your weblog comments. You can
mark comments as spam or delete them entirely. You can search comments
by keyword, date and status. If you’ve got comment moderation turned on,
you will use the Comments page to approve new comments.

image::user-guide-18-comments.png[]

*A word about status*

You can’t edit comments, but you can mark them as spam or dis-approve
them. Someday, Roller may provide some spam filtering based on data
collected from comments marked as spam but currently, marking as spam
and dis-approving of a comment do the same thing – they prevent the
comment from being displayed on your weblog.

*How to get to the Comments page*

There are a couple of ways to get to the Comments page. You can use
Roller’s tabbed menu to go there and manage comment across your entire
weblog. If you’ve got email notification of new comments turned on, the
you might arrive at the Comments page via a link sent to you in your
email.

You can also manage comments for just one weblog. When you are editing a
weblog entry with comments you’ll see a link in the top-right corner of
the weblog editor page like the one below, which you can use to access
the entry’s comments.

=== Comment 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
Weblog Settings page. 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 Comments page 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.

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.

=== Global comment management

If your user has global administration privileges, then you can manage
comments across the entire Roller site, including every weblog. To do
this, go to the *Server Administration: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.

=== *Preventing weblog spam*

Comment spam 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._

Fortunately, there are counter-measures. Here are
Roller’s built in spam prevention measures:

* _Pluggable comment authentication_. By default, Roller asks each
commenter a simple math question to ensure that they are a person and
not a spam robot. Your site administrator can turn this off or replace
it with another form of authentication.
* _Pluggable comment validation_. Roller includes four comment
validators below. Your site administrator can adjust the settings for
these validators and can enable/disable them as needed by overriding
Roller’s configuration properties (see the Installation Guide for more
information).
** Excess links validator will mark comments with more than three links
as spam (default: on)
** Excess size validator marks any comment with more than 1000
characters as spam (default: on)
** Bannedwordslist validator marks comments containing any of your site’s
designated bad words as spam (default: on)
** Akismet validator allows you to use the Akismet.com spam prevention
service.
* _Comment throttling_. If your site is being abused by a spam robot
your site administrator can set up throttling, which will watch for
abusers and ban IP addresses that are posting too many comments too
quickly.

But nothing beats comment moderation

Even if you’ve got all of those measures enabled you should still enable
email notification of comments so that you are constantly aware of new
comments on your weblog. None of the measures are 100% effective. If you
are really concerned about displaying offensive content on your weblog
even for a short time, then enable comment moderation on your weblog.

Roller uses a _bannedwordslist_, a list of words used to check incoming
comments and requestors for spam URLs. If the name, URL or content of a
comment includes one of the bannedwordslist words or matches one of the
expressions, then that comment 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 bannedwordslist:

** Level 1 bannedwordslist: This is the built-in bannedwordslist, the one that comes
with Roller. This can only be changed by somebody with root access to
the Roller server itself.
** Level 2 bannedwordslist: This is the site wide bannedwordslist, which can only be
edited by a global administrator via the Server Admin page.
** Level 3 bannedwordslist: Weblog specific bannedwordslist, which you control in
the Weblog Settings page of your weblog.

Incoming comments are checked against all three levels of bannedwordslist.
Incoming web page requests, however, are only checked against
the levels 2 and 3 bannedwordslist and will receive a 403 (forbidden) message
if found.

If you have a spam problem on your weblog and you’d like to add words to
the bannedwordslist, it’s probably better for you to ask your administrator to
add the words to the level 2 bannedwordslist 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 Weblog Settings page and scroll down to the bannedwordslist
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.

== Choosing your weblog theme

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. You can pick from one of a
number of predefined themes. Some themes will allow you to control
design by using a stylesheet. Other themes require you to edit the
templates that define the theme if you want to customize them.

You can access Roller’s theme and template features for your weblog via
the Design menu, shown below:

image::user-guide-20-design-menu.png[]

The Theme menu leads you to the theme chooser page, shown below. Using
this page you can pick from one or more different themes for your
weblog. If none of the themes are appealing to you, then speak to your
site administrator about obtaining or developing some additional themes.
The Roller Support project is one place where you can obtain additional
themes (_http://roller.dev.java.net_, _not_ an Apache site).

image::user-guide-design-theme.png[]

For more information on customizing Roller themes refer to the Template
Guide.

== Managing your weblog preferences

As a Roller user, you are free to customize the settings 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.

=== Weblog settings

The *Preferences:Settings* page allows you to set the configuration
parameters for your weblog.

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

==== *General settings*

image::user-guide-settings.png[]

* *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()_

* *Tagline* – Short description or sub title of your weblog. May include
HTML, but the HTML will be stripped out in your RSS feed. You can access
your tagline in a page template with the expression
_#showWebsiteDescription()_.
* *Icon* - The image file name (ex: thumbnail.jpg) or image url (ex:
http://yoursite/thumbnail.com) that shows on some of the default themes.
You’ll need to upload the image via the *Create & Edit:File Uploads* tab
first.
* About your blog – A more detailed description of the blog or blog
author(s) that shows on some of the default themes.

* *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. Your weblog will still be publicly available, but not
shown in the main community page of your site (if there is one).
* *Number of entries to display on weblog*: Enter the maximum number of
entries to be displayed on your weblog.

==== Internationalization Settings

image::user-guide-internationalization.png[]

* 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 and default comment settings

image::user-guide-comments.png[]

* *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).

Note the next two options are visible only if the Roller Administrator
has enabled email notifications for user blogs (See Section 9.2, Roller
Administration):

* *Email notification of 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.
* *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.

==== *Weblog client API*

image::user-guide-17-api.png[]

* *Enable Blogger API for your weblog* - Set to true to enable
weblogging via the MetaWeblog API. This will allow you to use handy
blogging clients like Ecto 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*

image::user-guide-formatting.png[]

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

==== *Spam prevention*

image::user-guide-spam.png[]

* **Ignore incoming URLs that contain any of these words - **you can use
this to filter out what commenters and referrers (web page
requestors) are accepted. See Section
[link:#5.5.Preventing%20weblog%20spam%20%7Coutline[5.5]]for more
information on spam prevention.

==== Web Analytics

If you wish to use Web Analytics software tools such as Google Analytics
(a fuller list of services is here:
http://en.wikipedia.org/wiki/List_of_web_analytics_software) to track
blog readers you can place your tracking code (usually a JavaScript
snippet including the <script> element that contains it) in this field.
Then, add the “#showAnalyticsTrackingCode($model.weblog)” macro to an
appropriate area in your blog’s template (the HTML <head/> section is
a good place) and this tracking code will be active for your blog.
(Most if not all of the blog templates pre-packaged with Roller
will already have this macro present; it will not output anything
if no tracking code is provided.)

This option will be available only if it has been activated by the blog
server administrator; alternatively, the tracking code can be directly
placed within the blog template if your administrator has enabled
template customization for blog owners. The blog server administrator
may configure a blog server-level default tracking key that will hold
for all blogs or alternatively just for blogs which haven’t overwritten
this default key.

=== Weblog members: managing 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
http://www.rollerweblogger.org/wiki/Wiki.jsp?page=UserGuide_2.x#ref-UserGuide_2.x-3[[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.

image::user-guide-21-member.png[]

You can use the *Invite new member* link to invite any Roller user to
join your 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 message
show in the screenshot below asking them to accept or decline your
invitation.

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 yourself from the
weblog.

*Accept or Decline a Group Blog Invitation*

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

image::user-guide-22-invite-member.png[]

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 privileges 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'.

== 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 the conventional XML-RPC weblog update ping mechanism
used by many sites for such notifications.

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

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

=== 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 comes pre-shipped with multiple
ping targets and the Roller administrator can configure additional ones
as desired.

=== Setting up Automated Pings

Once a 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.

image::user-guide-23-ping.png[]

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

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

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

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.

If you don’t find a ping target listed for the site you wish to ping,
you can request that your administrator add a a new one for all blogs to
have available. See Chapter 10 for more information on adding ping
targets.

=== 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=/categoryname_ substituting _name_ for
the category name. 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.

== Roller administration

This section of the Roller user guide is for users with the global admin
role. How do you get the admin role? The first user created in a Roller
system gets that role and then can grant it to other users via the
*Global Admin->User Admin* page, which just happens to be the first
topic we’ll cover in the section.

We’ll also describe how to configure Roller via the **Global
Admin->Configuration **page and how to configure Roller’s custom ping
facility via the *Global Admin->Ping Targets* page.

=== Managing users

The *Global Admin->User Admin* page, shown below, allows you to find
users, edit users and create new users.

image::user-guide-24-user-admin.png[]

To find a user, just enter the user’s username in the username in the
the Username field and click the edit button. If you don’t know the
user’s username, then start typing what you think might be the first
letters of her username or email address and the list-box will be
populated with all users whose usernames or email addresses match. When
you see the user you want in the list box, click her and then click the
Edit button to edit her user information.

You can also create a new user by clicking the *create a new user link*.

When a user is loaded into the *Global Admin->User Admin* page, or when
you create a new user, you’ll see the form shown below. You can set the
user’s full name, email address, locale and timezone. You can also reset
the user’s password, if you enter both a password and password
confirmation fields.

image::user-guide-25-user-admin.png[]

You can also disable a user, which will prevent the user from logging
into Roller.

Or you can check the Administrator checkbox to grant grant the user
Global Admin privileges.

At the bottom of the page, there’s a *Users Weblogs* section, which you
can use to edit any of the user’s weblogs. This feature is here to make
it easy for Global Admin’s to help users who are having trouble with any
of Roller’s features, so please use it for that reason only; don’t use
it to invade your user’s privacy.

NOTE: you can disable a user but there is no way to remove a user from
Roller.

=== Configuring Roller

The *Global Admin->Configuration* page allows you to set Roller’s
runtime configuration properties. It is a big page, so we will discuss
each section separately below.

image::user-guide-26-site-setting.png[]

* *Site name*: name of the site, to be included in site-wide newsfeeds
(RSS and Atom) and on the default front page of the Roller.
* *Short name*: short name of the site, to be included as the link in
the banner that appears at the top of every page in the Roller
editor/admin UI.
* *Site description*: description of site, to be included in site-wide
newsfeeds (RSS and Atom) and on the default front page of the site.
* *Site Administrator’s emailConfiguring Roller Address*: admin’s email address, to be
include in side-side newsfeeds (RSS and Atom)
* *Handle of weblog to serve as frontpage blog*: specify the weblog that
is to be displayed as the frontpage of this Roller site.
* *Enable aggregated frontpage feeds*: Set this to true if you would
like the frontpage weblog’s RSS and Atom feeds to be an aggregation of
all weblogs on the Roller site.
* *Absolute URL to this site*: to be used as basis for creating absolute
URLs. Required for Roller’s Planet aggregator feature.
* *Suspend all ping processing*: Allows you to turn off all (outgoing)
weblogs pings for all weblogs in the system.
* *Enable debug mode*: currently not used.

image::user-guide-27-comments.png[]

* *Allow New Users*: Set this to enable the _register as new user_ link
on the main page. If you turnoff user creation, you’ll only be able to
create new users via the *Global Admin->User Admin* page.

* *External registration URL*: Controls the URL of Roller’s "Register
as new users" link. If you use an external system to create Roller
users and blogs, set the URL of that system here.
* Editor pages: this is the list of weblog editors to be provided to
users.

* *Allow weblog comments*: By un-setting this you can turn off weblog
comments on all weblogs in the system.
* *Autoformat comments*: If this is on, Roller will auto-format comments
by adding in line-breaks where appropriate.
* *Escape comment HTML*: By setting this, you can disallow HTML in
comments and thereby protect your site from malicious JavaScript and
some forms of cross-site scripting.
* *E-mail notification of comments*: set this to enable email
notification of new comments. This won’t work unless you configured
Roller properly for sending email as described in the Roller
installation guide.
image::user-guide-28-feed.png[]

* *Default number of entries*: default number of entries to appear in
each newsfeed (RSS and Atom).
* *Maximum number of entries*: maximum number of entries to be allowed
in each newsfeed (RSS and Atom).
* *Display styled newsfeeds for browsers*: Set to true to enable
user-friendly RSS and Atom feed display, so that users don’t see raw XML
when they load the feed in their browsers.

image::user-guide-29-fileupload.png[]

* *Maximum AtomPub entry size (bytes)*: Maximum size of the XML body of one
AtomPub entry, set under Web Services Settings. The default is 1048576 bytes
(1 MiB). The `webservices.atomPubMaxEntrySize` setting takes effect on the next
request without a restart and must be between 1 and 2147483646 bytes. An entry
over the limit returns HTTP 413. A missing or invalid setting uses the default.
This limit does not apply to AtomPub media uploads, which use the file upload
settings below. Raising it does not increase the capacity of the database's
entry content columns.

* *Enable File Uploads*: Are users allowed to upload files?
* *Allowed Extensions*: Comma-separated list of file extensions that
users are allowed to upload.
* *Forbidden Extensions*: Comma-separated list of file extensions that
users are NOT allowed to upload.
* *Max File Size (MB)*: Maximum size of file that users are allowed to
upload.
* *Max Directory Size (MB)*: Total upload directory size per user.

The We Analytics section allows you to provide a JavaScript snippet if
you wish to activate Google Analytics or other tracking services. The
value you place here will hold for all blogs, unless you enable the
individual blog overriding option in this section; in the latter case
the default key will be used only for blogs which don’t have their own
defined. Note that even if individual overrides are disallowed bloggers
can still place their own tracking code within their blog templates if
you enable custom themes (in the "Theme Settings" section on this
configuration page.)

== Weblog update ping administration

This section, intended for Roller administrators, describes how the
Roller weblog update ping feature works and how to configure and
administer it.

=== Creating and editing common ping targets

Common ping targets are ping targets that are shared by all users. You
can create and edit common ping targets using the *Global Admin->Ping
Targets* page.

image::user-guide-30-ping.png[]

You can create and edit common ping in the same way that regular users
create and edit custom ping targets, but keep in mind that common ping
targets are shared amongst all users, and that your changes affect all
users using the ping target. Administrators should make sure to test new
common ping targets after creating them.

Before adding a ping target, the administrator must determine the proper
ping URL for the site that you wish to ping. This information can be
obtained from the aggregator’s web site or from another knowledgeable
source.

It can be hard to find the aggregator’s documentation for 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.

Click the *Add New* button to add a new 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.

image::user-guide-31-add-ping.png[]

Once the new ping target has been created, it will be listed for all
blogs on their *Weblog:Pings* page with the default activation status
defined by the administrator. From this page, individual users can
override the ping target’s enable status for their own blog as well as
send manual pings to the new target.

=== How Roller Processes Weblog Update Pings

Roller processes weblog update pings in the background. When a user
updates his or her weblog, Roller automatically queues any required
automated pings on a queue. Roller only keeps one ping queue entry for a
given user weblog and ping target. Subsequent updates to a weblog
occurring before the ping is processed will not cause additional pings
to be queued.

Roller makes a full pass through the ping queue at regular intervals.
(Configuration of this interval is discussed below) In each pass, Roller
will attempt to send every queued ping request once. If any send fails
(and provided the failure appears to be a transient one), the ping
request will be re-queued, until the ping succeeds or a configured
number of attempts has been made. Note that when a ping request fails
and is re-queued, it is processed again only on subsequent ping passes.
If the number of attempts to reach a given ping target reaches the
maximum without succeeding, then an error message is logged and the ping
request is dropped.

There is currently no mechanism for alerting users of failing ping
targets (though we plan some improvements in subsequent releases to
provide condition information on the weblog *Preferences->Pings* page,
as well as a failure policy to deactivate persistently failing ping
targets).

=== Configuration Properties Controlling Ping Processing

These properties control processing of the ping queue. They are
configured in the __roller.properties __file.

**pings.queueProcessingIntervalMins **The interval in minutes between
ping queue processing runs. This must be a value in the range 0 to 120.
The default value is 5 minutes. We think the default value should work
for most sites, and is tolerable for most users. The number of users
publishing or updating entries in a given interval determines the length
of the queue, and Roller requires enough time in an interval to process
the queue once. We think that for all but the largest and most active
sites, it can probably be lowered as low as 1 minute if desired.
*IMPORTANT*: The value 0 (zero) has a special meaning. If the processing
interval is set to 0, ping queue processing is disabled on the server.
This can be used to exclude all but one host from sending pings in a
clustered environment where multiple Roller servers are sharing one
database schema. *Make sure to retain one host in the cluster that does
process the ping queue!* If multiple hosts in a cluster process the ping
queue, you may send duplicate pings and failing ping requests may drop
out of the queue sooner than the expected maximum (configured by the
next parameter). If no hosts in a cluster process the ping queue, auto
ping requests will accumulate in the queue and this will eventually
cause the database to run out of space, so don’t try to use this as a
way to disable ping features. You can use the properties described in
the following sections to disable ping features.

**pings.maxPingAttempts **The maximum number of ping attempts made
before the ping request will no longer be requeued and will instead be
dropped from the queue. The default value is 3. We think this value is
fine for most sites.

=== Suspending all ping processing

Administrators can suspend all ping processing at runtime by checking
the *Suspend ping processing?* checkbox under the *Site Settings*
heading on the *Global Admin->Configuration* page and saving that form.

When this checkbox is set, all ping processing is suspended. New
automatic ping requests are not added to the queue, and existing entries
on the queue are not processed. Manual pings are not sent either; they
result in a message telling the user that ping processing has been
suspended. Suspending ping processing is appropriate to temporarily stop
all ping processing if problems are encountered.

Unchecking the checkbox and saving allows normal ping processing to
resume. Note, however, that autopings for weblogs that are updated while
ping processing is suspended will never be queued and hence never sent,
but pings queued before the suspension are sent once the suspension is
lifted.

=== Controlling and disabling ping usage

Since use of a ping target causes an outbound network connection to the
ping site, some administrators may not want to allow users to create
their own custom ping targets. It is possible to enable or disable the
use of custom ping targets across the whole site and also to disable all
ping usage. The following two properties are used to control this.

**pings.disallowCustomTargets. **This property controls whether users
are allowed to create custom ping targets. If set to true, all existing
custom ping targets are _removed_, and the *Weblog:Custom Ping Targets*
page and the associated actions are disabled preventing any
configuration of custom ping targets. *Note:* __Setting this to true
this will cause the Roller server to __remove _any custom ping targets
that users have created when Roller is next started._

Administrators may also wish to disable ping functionality entirely. The
following property, used in conjunction with the above property, can be
used to do this.

**pings.disablePingUsage. **This property controls whether users are
allowed to set up automatic pings or send manual pings. If set to true,
all existing autoping configurations are removed (i.e. disabled), the
weblog *Preferences->Pings* page and associated actions are disabled,
preventing any use of the ping features by regular users. *Note:*
__Setting this to true will cause the Roller server to __remove _any
autopings that users have configured when Roller is next started._

If both of the above properties are set to true, all ping functionality
is effectively disabled for regular users. The *Global Admin:Ping
Targets* page is still accessible (to administrators); you can use that
page to clear out any common targets if you wish. No user (including
administrators) will be able to configure automatic pings or send pings.
Ping queue processing continues but the queue will always be empty; you
can safely disable ping queue processing (by setting the processing
interval to zero) in this situation.

=== Initialization of common ping targets

The initial set of common ping targets is determined by the following
configuration property.

**pings.initialCommonTargets. **This value is used to initialize the set
of common ping targets. The value consists of a comma-separated list of
ping targets, where each ping target is specified in the form

{{name}{url}}

This value is used every time Roller starts _and finds an empty list of
common ping targets._ Normally, this is only the first time Roller is
started on a fresh or upgraded database; note, however, that if you
really want to maintain an empty list of common ping targets, you will
need to comment out this value or set it to an empty string.

== Weblog Export

Roller includes an optional weblog export feature that allows you to
export your weblog entries and uploaded Media Files to a format that is
compatible with both Wordpress and MovableType. You can use the *Create
& Edit -> Export* menu to do this. When you click one of the Export
buttons, you will be prompted to download the resulting file.

*Enabling Weblog Export*

Export is an optional feature that is disabled by default.

If you do not see it in Roller, as your Roller admin to enable it by
setting the _weblog.export.enabled_ property to _true_ in the
**roller-custom.properties **file.

== Planet Roller administration

Roller includes an aggregator known as Planet Roller, which makes it
possible for you to aggregate together weblogs from a Roller server with
weblogs that are hosted elsewhere. You can create multiple aggregation
groups each with its own set of feeds, you can display aggregation
groups on your weblog pages and Roller provides an RSS feed for each
group you create.

Roller’s aggregator is not enabled by default. If you want to use it,
you’ll have to ask your site administrator to enable and configure it
for you. Please refer to the Roller Installation Guide for more
information on that topic.

=== Configuring Planet Roller

If you’ve got Planet enabled, when you login as a global admin you’ll
see a Planet Administration link on the Roller Main Menu page. Click
that link to view the *Planet Admin->Configuration* page, shown below.

image::user-guide-32-planet-config.png[]

To configure Planet Roller, you must:

* Ensure that your site has an absolute URL in the *Global
Admin->Configuration* page in the Site Settings section.

* If you are behind a proxy, you must enter proxy settings in the
*Planet Admin->Configuration* page.

=== Adding external weblogs to Planet Roller

Planet Roller allows you to create multiple aggregation groups each
containing a different set of feeds, but there is also a special group
known the _external_ group that is managed by Roller. The external group
includes all weblogs on your Roller server plus any externally hosted
weblogs you choose to add. The RSS feed for the external group is
available at /planetrss, so on a default Roller install its URL will be:

http://localhost:8080/roller/planetrss

This section describes how to add and remove weblogs using the *Planet
Admin->Subscriptions* page, shown below.

image::user-guide-33-subscription.png[]

*Adding an external weblog to Planet Roller*

To add an externally hosted weblog to the Planet, use the *Planet
Admin->Subscriptions* page. Enter its title, newsfeed URL and website
URL and click the Save button.

NOTE: Planet Roller only supports Atom and RSS newsfeeds that include
entry level date information. If you enter a subscription that does not
include dates, Planet Roller will accept it, but you may not see entries
from the feed because Roller will assume that its entries are at least
one day old.

Removing an external weblog from Planet Roller

You can select an existing subscription and edit it or delete it. The
change will not be evident on the front page until the next scheduled
Refresh Entries task runs.

=== Adding custom groups to Planet Roller

You can also add custom aggregation groups and Planet Roller will
provide an RSS newsfeed for each group you add. For example, if you add
groups with the handles _music_ and _politics_, then you’ll get two
feeds at URLs like this:

http://localhost:8080/roller/planetrss?group=music

http://localhost:8080/roller/planetrss?group=politics

To add new custom groups just use the *Planet Admin->Custom Groups*
page, shown below.

To create a custom group

Go to the *Planet Admin->Custom Groups* page and enter the title and
enter a title for the group, one that is appropriate for display in the
group’s RSS feed. Enter a handle a one word name for the group, which
you’ll use to refer to the group in your page templates. When you’re
done click the Save button

You’ll see your new group appear in the Existing Custom Aggregation
Groups table. Click on the Subscriptions icons for your new group and
you’ll be taken to the *Planet Admin->Subscriptions* page so you can add
feed subscriptions to the group.

Enter the title, newsfeed URL and website URL for the feed you’d like to
add and click the Save button to add it to the feeds list. Repeat once
for each subscription you’d like to add to the group.