dave's wiki

random notes

Looking for Roller? The Official Roller Wiki is now hosted by the Apache Software Foundation.

Welcome!

G’day (anonymous guest)

Log in My Prefs

Search

view edit clone find

Quick search (type ahead)

Recent Searches (Clear)

Page: UserGuide_2.x

Edit
More...

How to use Roller.

[#1] Introduction#

This user guide describes how to use Roller, a web application that can provide weblogs for one or thousands of authors. There are separate guides for installing, configuring and administering Roller. In this guide we cover:

How to register as a new Roller user and create a weblog
How to edit and post weblog entries
How to customize the appearance of your weblog
How to add a blogroll, a list of your favorite web links to your weblog
How to invite and manage other authors in 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 behaviour of the weblog.
Weblog entry: a weblog entry is an indivial entry within a weblog with a title, date and text.

[#2] Gettings 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] 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:

Start Roller and navigate to the main page (e.g. http://localhost:8080/roller).
Click the Register link in the top right corner of the page.
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.
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.
On the Main Menu page, click the create a weblog link to create a new weblog.
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:

Use your web browser to go to the main page of the Roller installation
Click the Register link in the top right corner of the page
Fill out the information for your new user. Once you've filled out the form. click the Register User button.
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:

Login to Roller by clicking the Login or the Main Menu link
On the Main Menu page, click the create a weblog link to create a new weblog.
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:

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

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

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.

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.

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.

[#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.

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 a new weblog entry #

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.

The above screenshow shows the default plain text weblog post editor. With this editor, you are entering raw HTML and if you don't know HTML you will not be able to do bold, italics, paragraph breaks, etc. Roller also support several other WYSIWYG editors and you can pick the one you want using your weblogs's Preferences:Settings page.

Let's cover the fields on the page:

Title: this is the optional title of your entry you don't have to include one, but we recommend that you do. If you don't some readers might see the first couple of words of your entry used as your title.

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: Roller will set the Pub Time of your entry to the time when you first click the Post to Weblog button. If you'd like your post to be published at a specific time in the future, you can set the Pub Time yourself. Your new entry won't appear on your weblog or in your newsfeed until the time you specify. You can also use Pub Time to publish entries in the past.

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

Your post: the big text box is the body of your blog entry. Normally, you enter the HTML for your post here. You don't have to enter a complete HTML document, just the text your post.

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:

- Plugin1
- Plugin2
- etc.

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.

[3.2] 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.

How to create a Podcast 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/myfirstpodcast.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/myfirstpodcast.mp3">myfirstpodcast.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:

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/myfirstpodcast.mp3" 
   type="audio/x-mpeg" length="3409127" />

That's all there is to it.

[3.3] Working with old weblog posts#

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.

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.

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

You can use the Create & Edit: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.

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.

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.4] Working with weblog comments#

If you have enabled comments in your Preferences:Settings page then visitors may leave comments on each of your weblog entries. Other bloggers can also use a feature called Trackback to add comments to your blog. Not all comments are acceptable, so Roller allows you to delete comments from your weblog entries.

Removing comments from a weblog entry

To remove comments from a weblog entry, first you must load that entry into the editor (i.e. the New Entry page). Once you've loaded an entry into the editor, scroll down to the bottom of the page and you see the comments left on that entry. Here's an example screenshot:

Figure: the comments list on the New Entry page

Click the Delete checkbox for any comments you wish to delete, then click the Update Comments button to delete the comments.

You can use the spam checkbox to mark comments as spam. Any comment marked as spam will not be displayed on your blog.

Dealing with comment spam

Currently Roller provides several ways to deal with comment spam:

You can limit the time allowed for comments. By using the Comment Settings box when you create a new entry, you can limit the number of days that users are allowed to leave comments. That may inconvenience some of your readers, but it will limit the number of places that spammers can leave spam.

You can monitor new comments via email. If your Roller site supports email notification of comments, then turn it on for your blog. You'll get a new email whenever a new comment arrives. That will enable you to delete spam comments as soon as they arrive.

You can disable comments. If comment spam gets to be too much, you can use the Preferences:Settings page to turn off comments in your weblog.

You can ask the site administrator to disable Trackbacks. Many spammers use Trackbacks to leave comments since Trackbacks can be easily automated. If spam gets to be too much, as your admin to disable recieving of Trackbacks.

Roller uses the MT-Blacklist. Whenever a new comment comes in, Roller checks it against the MT-Blacklist, a list that is kept up to date by Jay Allen and friends. Any comment that is recognized as spam is marked as spam and not displayed on your blog.

[3.5] 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 MT 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:

Figure: the Trackback URL 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:

Figure: successfull Trackback message:

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

[3.6] 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 Weblog:Edit 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.

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.

RSS Feed for Each Category

Your weblog's main RSS newfeed 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.

Adding, Renaming, and Removing Weblog Categories

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

[3.7] Referer rankings#

The Weblog:Referer referer 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 referer logs, you can get an idea of who is reading and commenting on your weblog.

[#4] Managing your weblog#

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:

Figure: The 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 screenshot below:

Figure: The Preferences:Settings page

Here is an explanation of each of those settings:

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

Default from address: Enter the email address that should be used as the from address for emails sent by Roller.

Page to be used as the homepage - Choose a page template to be used as the main page of your weblog.

Weblog editor page to be used - Choose a weblog editor page, some are WysiwygEditors
- editor-text.jsp: simple text editor
- editor-dhtml.jsp: rich text editor (works only in MSIE)
- editor-ekit.jsp: rich text editor (a Java applet)
- editor-rte.jsp: rich text editor (works in most browsers)
- editor-text-js.jsp: enhanced simple text editor

Comments

Allow commments for your weblog - Set this to true to allow visitors to leave comments on your weblog.

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 plugins to be enabled by default on a new weblog entry.

Spam pevention

Ignore incoming referer URLs that contain any of these (comma-separated) words - you can use this to filter out what referers are accepted. Somewhat useful if you start getting hit by referer spam, but not a complete solution to the referer spam problem.

[4.2] Weblog themes#

A Website Theme is a look-and-feel for your website, a skin, if you will. When you created your Roller weblog/user-account, you picked from one of the available Roller themes. You might have picked the Robot theme, or the Roller theme, or whatever. A theme determines how your Roller website looks.

If you want to change your theme, you can use the Roller Preferences:Themes page to switch to a different theme. This is really easy and does not require any knowledge of HTML. I'll illustrate this below with a screenshot, but first a word of warning. If you have customized your theme on your own by modifying the HTML, CSS, and/or JavaScript in the pages that comprise your Roller theme, then watch out. Switching themes using the Roller Theme Switcher will destroy the customizations that you have made.

Below is the Roller theme switcher. You can pick a new theme, preview it, and then either cancel or save the theme. If you don't hit the save button, your theme will not be switched.

If you were to pick the Moonshine theme in the "Select a theme" combo-box and then hit the preview button, you would see something like the screenshot below. If you want to select this new theme you will have to hit the Edit button to return to the Theme Switcher and then hit the Save button to save your theme selection.

If you're not happy with any of the built-in themes, see section [5.0] to learn how to customize your theme.

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

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 chaning 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 dn the Preferences tab of Roller.

Author: author permission allows users to create entries, edit entries and upload files. But authors cannot weblog settings, change the theme or manage users. Authors can see the weblog Create & Edit tab, but not the weblog Prefenences 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

Select '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 (see section [4.2]). If you're not happy with the set of themes built-into Roller, you can customize them.

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 weblogs's theme is defined by a set of templates. A page 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.

Velocity template language

Roller uses the powerful Velocity template language and this gives you a lot of power and flexibility in customizing the look and feel and layout of your weblog pages. For more information on the Velocity template language, refer to the Velocity website and to the Velocity Reference Guide. Roller user's refer to page templates as either pages or template, the words page and template are used interchangably.

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

Below is the Roller Website:Edit-Page 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.

[5.1] Weblog and day pages #

Every Roller theme is a little different, but all themes have a minmum of two page templates: a weblog page and a day page. Let's discuss the purposes of these two pages.

Your Weblog page

Your weblog page is the main page of your website, 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:

<!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>Referers</h2>
    #showReferers(30 20)
   </td>
</tr></tbody></table>
</body>
</html>

For a full listing of the Roller Macros refer to the Roller Macros and Variable Reference 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] Other pages and comments #

You can add as many pages as you like to your Roller website, you can choose which ones are to appear in your website's navigation bar, you can include pages in other pages using the #includePage macro, and you can include Roller macros in any of these pages. Use the Roller Editor UI's Website:Pages menu to add new pages and to edit your existing pages.

Your default page

You can define as many pages as you would like, but you must specify one page is to be your default Page, that is, the page that your readers first see when they visit your website. You can specify your default page in your website settings on the Website:Settings page of the Roller Editor UI.

Some pages are visible, some are not

Note that any page whose name begins with the underbar "_" character will not be visible to your readers, meaning that it will not appear in your website's navigation menu that is dislayed by the #showNavBar macros.

Pop-up comments, the comments page, and TwistyComments

The Basic theme example above also uses the #showCommentsPageLink macro to display a link to the comments page for the weblog entry. If, instead, you wanted to use a popup comment, you could use the #showCommentsLink macro. NOTE: comments will not work unless you check the Allow Comments check-box on the Website:Settings page.

[5.3] 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.4] 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.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. (?)

[5.6]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:

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

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 by MattRaible's x2 theme):

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.7] Enabling weblog search#

In order to enable search for your weblog, simply add a #showSearchForm() call in your weblog page. Note that this shows an undecorated form. It is not enclosed in any div tags, so you will need to add those yourself.

[#6] Using Roller for bookmark and blogroll management #

You probably already have a web bookmark (AKA links) collection stored in your web browser, so why do you need to enter bookmarks into Roller? There are a couple of reasons. Most bloggers like to display a blogroll of links to favorite blogs. Most bloggers also like to display lists of favorite websites. By entering your bookmarks into the Roller bookmark manager, you'll find that it is easier to display your bookmarks on the various pages that make up your website.

[6.1] Adding new bookmark folders #

Bookmarks are organized in to named folders. You can define any number of folders and each of these folders can hold any number of bookmarks. There is only one level of folders, so you cannot have a folder that contains other folders.

Your initial website contains two bookmark folders: one named "Blogrolling" that contains Weblogging related links and one named "News" that contains links to well known news sources. If you look at Figure 1 again, you can see that these two folder are displayed on the left side of the Weblog page. You can use Roller's bookmark management features to rename these folders if you wish, or you can delete them add add folders of your own choosing.

Figure: the Edit-Bookmark Folders page

[6.2] Adding bookmarks to folders #

Once you have defined one or more bookmark folders, you can start adding bookmarks to those folders. From the Edit-Bookmark Folders page, click the Edit link for the Folder you wish to edit. You will be taken to the Edit-Bookmark Folder page for that folder. From there you can edit the name of the folder and you can add and remove bookmarks in that folder.

Figure: the Edit-Bookmark Folder page

[6.3] Editing a bookmark#

After you use the Edit-Bookmark Folder to add a bookmark, you can edit the Bookmark itself. To edit a bookmark, click on the Edit link in the Edit-Bookmark Folder page. That will take you to the Edit-Bookmark page and from there you can change the name, description and display priority of the bookmark you have chosen to edit. You can also move the bookmark to another folder by changing the Bookmark Folder combo-box.

Figure: the Edit-Bookmark page

[6.4] Displaying 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.3] Importing Bookmarks in OPML format#

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. To import bookmarks via OPML, follow these steps:

download bookmarks in OPML format from a site such as Scripting.COM and save them as a file on your hard disk.
Login to Roller and choose the Bookmarks:Import menu option.
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.

NOTE: 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 Blogging Client with Roller #

You can use any Blogger API client to post and edit Roller weblog entries. Before you can do this, you must go to the Roller Website:Settings menu and check the box that reads Enable Blogger API for your weblog. You should also pick a category for posts made through the Blogger API because some blogging clients do no support categories.

Using w:bloggar#

w:bloggar is a full-featured blogging client that runs on Windows. If you want to take advantage of all of the cool w:bloggar features, like support for titles and categories, then you'll need to modify the w:bloggar configuration file. The configuration file is located in the CMS directory of the w:bloggar install, it is named CMS.ini.

To configure w:bloggar for Roller, you'll need to add a Roller section to CMS.ini. Near the start of CMS.ini, you find a line that reads Config= and then some number. That count is the number of sections in the CMS.ini file. Since we are adding a section, we need to increment that number by one. For example, below we have incremented it from 15 to 16.

[CMS]
Count=16

Next, add the following section at the end of the CMS.ini file. Make sure that the number at the end of CMS- matches the number that you entered for the count above. For example, below is what you would add for JRoller. NOTE: If you installed Roller on Tomcat yourself, following the InstallationGuide, then you will probably set Host to localhost, Page to /roller/xmlrpc, and Port to 8080.

[CMS-16]
Name=Roller

URL=http://www.rollerweblogger.org
Icon=rollerbadge.jpg
Service=0
Host=www.jroller.com
Page=/xmlrpc
Port=80
Https=0
MultiCateg=3
GetCategMethod=3
PostMethod=3
GetPostsMethod=3
TemplateMethod=1

Once you've doen this, start w:bloggar. To hook up to your Roller account, choose the File-Select-Account menu item. You'll see the dialog-box below, choose <<New>> in the account combo-box and enter your Roller user-name and password, as shown below.

Next, answer Yes to the Do you want to create this account? message-box and hit OK. Next, you'll see the Account Properties dialog-box, shown below. Choose the entry that you configured in CMS.ini, enter a name for this account in the Alias text-field, and check Ping Weblogs.com. Below is an example JRoller configuration. NOTE: If you installed Roller on Tomcat yourself, following the InstallationGuide, then you will probably set Host to localhost, Page to /roller/xmlrpc, and Port to 8080.

[#8] Using Pings to Announce Changes to your Weblog#

Weblog update pings provide a means for you to notify aggregation and indexing sites, (for example Weblogs.com, Technorati, and java.blogs) 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.

[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. (See [1.7] for more information on providing these URLs to aggregators.)

Aggegation sites that accept ping notifications generally publish the ping url to use to ping their site on their (human-readable) website.

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. For instructions on configuring custom ping targets, see Section [1.6]).

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

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 website or from another knowledgable 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 website 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 website, 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 screenshot.

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.

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.

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.

[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 blogs, you get your blog's base url by viewing your weblog and taking the URL to the point just following your username. (In other words it should end with page/yourusernamehere).

The RSS feed URL for your whole feed can be obtained by substituting page in your blog'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.

Add new attachment

« This page (revision-13) was last changed on 17-Jan-2009 08:48 by DaveJohnson

In order to upload a new attachment to this page, please use the following box to find the file, then click on “Upload”.
Select file:
Change Note: