| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <HTML> |
| <HEAD> |
| <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1"> |
| <TITLE></TITLE> |
| <META NAME="GENERATOR" CONTENT="StarOffice 8 (Solaris x86)"> |
| <META NAME="AUTHOR" CONTENT="Dave Johnson"> |
| <META NAME="CREATED" CONTENT="20051209;11500200"> |
| <META NAME="CHANGEDBY" CONTENT="Dave Johnson"> |
| <META NAME="CHANGED" CONTENT="20060512;18113300"> |
| <META NAME="SDFOOTNOTE" CONTENT=";;;;P"> |
| <META NAME="SDENDNOTE" CONTENT="ARABIC"> |
| <STYLE> |
| <!-- |
| @page { size: 8.5in 11in; margin: 0.79in } |
| P { margin-bottom: 0.08in } |
| H1.cjk { font-family: "Andale Sans UI" } |
| H1.ctl { font-family: "Lucidasans" } |
| TD P { margin-bottom: 0in } |
| --> |
| </STYLE> |
| </HEAD> |
| <BODY LANG="en-US" DIR="LTR"> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <DIV ID="wrapper" DIR="LTR"> |
| <DIV ID="banner" DIR="LTR"> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><FONT SIZE=7 STYLE="font-size: 40pt"><B>User |
| Guide</B></FONT></P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><FONT SIZE=7 STYLE="font-size: 32pt"><B>Apache |
| Roller</B></FONT></P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><FONT SIZE=5 STYLE="font-size: 20pt"><B>Version |
| 2.3-incubating</B></FONT></P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=CENTER STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P ALIGN=LEFT><FONT FACE="Courier New"><FONT SIZE=1 STYLE="font-size: 8pt"><I>Licensed |
| to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. The ASF licenses this file to You |
| under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at</I></FONT></FONT></P> |
| <P ALIGN=LEFT> <FONT FACE="Courier New"><FONT SIZE=1 STYLE="font-size: 8pt"><I>http://www.apache.org/licenses/LICENSE-2.0</I></FONT></FONT></P> |
| <P ALIGN=LEFT><FONT FACE="Courier New"><FONT SIZE=1 STYLE="font-size: 8pt"><I>Unless |
| required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" |
| BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express |
| or implied. See the License for the specific language governing |
| permissions and limitations under the License. For additional |
| information regarding copyright in this work, please see the NOTICE |
| file in the top level directory of this distribution.</I></FONT></FONT></P> |
| </DIV> |
| <DIV ID="centercontent" DIR="LTR"> |
| <P STYLE="page-break-before: always"><BR><BR> |
| </P> |
| <DIV ID="Table of Contents1" DIR="LTR"> |
| <DIV ID="Table of Contents2_Head" DIR="LTR"> |
| <P STYLE="margin-top: 0.17in; margin-bottom: 0.2in; page-break-after: avoid"> |
| <FONT FACE="Albany, sans-serif"><FONT SIZE=4 STYLE="font-size: 16pt"><B>Table |
| of Contents</B></FONT></FONT></P> |
| </DIV> |
| <P STYLE="margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>1 |
| - Introduction 5</B></FONT></P> |
| <P STYLE="margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>2 |
| - Getting started with Roller 5</B></FONT></P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>2.1 - |
| Getting started with a new Roller installation 5</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>2.2 - |
| Getting started with an existing Roller installation 5</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>2.3 - |
| Accepting an invitation to join a weblog 6</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>2.4 - |
| Getting around in Roller 6</P> |
| <P STYLE="margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>3 |
| - Creating and editing your weblog 9</B></FONT></P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>3.1 - |
| Creating and editing a weblog entries 10</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>3.2 - |
| Finding and editing weblog entries 12</P> |
| <P STYLE="margin-left: 0.39in; margin-bottom: 0in">3.2.1 - Finding |
| old entries with the Create & Edit:New Entry page 12</P> |
| <P STYLE="margin-left: 0.39in; margin-bottom: 0in">3.2.2 - Finding |
| old entries with the Create & Edit:Edit Entries page 13</P> |
| <P STYLE="margin-left: 0.39in; margin-bottom: 0in">3.2.3 - Finding |
| old entries using the pages of your weblog 13</P> |
| <P STYLE="margin-left: 0.39in; margin-bottom: 0in">3.2.4 - Finding |
| old entries with Roller's built-in search engine 13</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>3.3 - |
| Weblog categories 14</P> |
| <P STYLE="margin-left: 0.39in; margin-bottom: 0in">3.3.1 - The |
| Weblog Category Chooser 14</P> |
| <P STYLE="margin-left: 0.39in; margin-bottom: 0in">3.3.2 - RSS |
| Feed for Each Category 14</P> |
| <P STYLE="margin-left: 0.39in; margin-bottom: 0in">3.3.3 - Adding, |
| Renaming, and Removing Weblog Categories 14</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>3.4 - |
| Podcasting with Roller 15</P> |
| <P STYLE="margin-left: 0.39in; margin-bottom: 0in">3.4.1 - How to |
| create a podcast feed with Roller 15</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>3.5 - |
| Referrer rankings 17</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>3.6 - |
| Comment notification via email 17</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>3.7 - |
| Comment management and moderation 17</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>3.8 - |
| Preventing weblog spam 19</P> |
| <P STYLE="margin-left: 0.39in; margin-bottom: 0in">3.8.1 - Three |
| levels of blacklisting 19</P> |
| <P STYLE="margin-left: 0.39in; margin-bottom: 0in">3.8.2 - How to |
| add words and expressions to the blacklist 19</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>3.9 - |
| Sending trackbacks 20</P> |
| <P STYLE="margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>4 |
| - Managing your weblog settings 21</B></FONT></P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>4.1 - |
| Weblog settings 22</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>4.2 - |
| Weblog themes 25</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>4.3 - |
| Uploading Files 26</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>4.4 - |
| Setting up a group blog 27</P> |
| <P STYLE="margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>5 |
| - Customizing your weblog's theme 29</B></FONT></P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>5.1 - |
| Weblog and day templates 31</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>5.2 - |
| Define standard headers and footers with a decorator 33</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>5.3 - |
| Roller Macros and Variables 34</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>5.4 - |
| Creating and packaging your own Roller theme 35</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>5.5 - |
| Overriding Roller Macros 36</P> |
| <P STYLE="margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>6 |
| - Managing your weblog's blogroll 37</B></FONT></P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>6.1 - |
| Adding new links to your blogroll 37</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>6.2 - |
| Adding new links to your blogroll 38</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>6.3 - |
| Adding new bookmark folders 39</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>6.4 - |
| Bookmark import and export via OPML 40</P> |
| <P STYLE="margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>7 |
| - Using a blog client with Roller 41</B></FONT></P> |
| <P STYLE="margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>8 |
| - Using weblog pings 42</B></FONT></P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>8.1 - |
| Registering with an Aggregator 42</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>8.2 - |
| Ping Targets, Common and Custom 42</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>8.3 - |
| Setting up Automated Pings 42</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>8.4 - |
| Sending a Manual Ping 44</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>8.5 - |
| Creating and Editing Custom Ping Targets 44</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>8.6 - |
| More on Registering with an Aggregator 46</P> |
| <P STYLE="margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>9 |
| - Roller administration 47</B></FONT></P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>9.1 - |
| Managing users 47</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>9.2 - |
| Configuring Roller 49</P> |
| <P STYLE="margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>10 |
| - Weblog update ping administration 52</B></FONT></P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>10.1 - |
| Creating and editing common ping targets 52</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>10.2 - |
| How Roller Processes Weblog Update Pings 52</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>10.3 - |
| Configuration Properties Controlling Ping Processing 53</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>10.4 - |
| Suspending all ping processing 53</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>10.5 - |
| Controlling and disabling ping usage 53</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>10.6 - |
| Initialization of common ping targets 54</P> |
| <P STYLE="margin-bottom: 0in"><FONT SIZE=4 STYLE="font-size: 16pt"><B>11 |
| - Planet Roller administration 55</B></FONT></P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>11.1 - |
| Setting up the Planet aggregator 55</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>11.2 - |
| Configuring Planet Roller 56</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>11.3 - |
| Adding external subscriptions to Planet Roller 57</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>11.4 - |
| The Planet Roller main page 58</P> |
| <P STYLE="margin-left: 0.2in; margin-bottom: 0in"></SPAN>11.5 - |
| Adding custom groups to Planet 59</P> |
| </DIV> |
| <P><BR><BR> |
| </P> |
| <DIV ID="Illustration Index1" DIR="LTR"> |
| <DIV ID="Illustration Index1_Head" DIR="LTR"> |
| <P STYLE="margin-top: 0.17in; margin-bottom: 0.2in; page-break-before: always; page-break-after: avoid"> |
| <FONT FACE="Albany, sans-serif"><FONT SIZE=4 STYLE="font-size: 16pt"><B>Illustration |
| Index</B></FONT></FONT></P> |
| </DIV> |
| <P STYLE="margin-bottom: 0in">Illustration 1: Main Menu with |
| invitation to join a group blog 6</P> |
| <P STYLE="margin-bottom: 0in">Illustration 2: Status bar, no |
| weblog 7</P> |
| <P STYLE="margin-bottom: 0in">Illustration 3: Status bar within |
| weblog 7</P> |
| <P STYLE="margin-bottom: 0in">Illustration 4: Weblog navigation |
| bar 7</P> |
| <P STYLE="margin-bottom: 0in">Illustration 5: Weblog editor |
| navbar 8</P> |
| <P STYLE="margin-bottom: 0in">Illustration 6: Main menu 9</P> |
| <P STYLE="margin-bottom: 0in">Illustration 7: Weblog editor 10</P> |
| <P STYLE="margin-bottom: 0in">Illustration 8: Edit entries page 12</P> |
| <P STYLE="margin-bottom: 0in">Illustration 9: Podcast URL field 16</P> |
| <P STYLE="margin-bottom: 0in">Illustration 10Comment (and |
| trackback) management page 18</P> |
| <P STYLE="margin-bottom: 0in">Illustration 11: Send trackback |
| control 20</P> |
| <P STYLE="margin-bottom: 0in">Illustration 12: Result of sending |
| trackback 20</P> |
| <P STYLE="margin-bottom: 0in">Illustration 13: Weblog preferences |
| menu 21</P> |
| <P STYLE="margin-bottom: 0in">Illustration 14: Weblog settings |
| page part 1 22</P> |
| <P STYLE="margin-bottom: 0in">Illustration 15: Weblog settings |
| page part 2 24</P> |
| <P STYLE="margin-bottom: 0in">Illustration 16: Theme selection |
| page 25</P> |
| <P STYLE="margin-bottom: 0in">Illustration 17: Weblog permissions |
| page 27</P> |
| <P STYLE="margin-bottom: 0in">Illustration 18: Weblog templates |
| page 29</P> |
| <P STYLE="margin-bottom: 0in">Illustration 19: Edit template |
| page 30</P> |
| <P STYLE="margin-bottom: 0in">Illustration 20: Theme directory |
| structure 35</P> |
| <P STYLE="margin-bottom: 0in">Illustration 21: Bookmarks |
| management page 37</P> |
| <P STYLE="margin-bottom: 0in">Illustration 22: Add and edit |
| bookmark form 38</P> |
| <P STYLE="margin-bottom: 0in">Illustration 23: Add folder form 39</P> |
| <P STYLE="margin-bottom: 0in">Illustration 24: Automatic ping |
| configuration page 43</P> |
| <P STYLE="margin-bottom: 0in">Illustration 25: Custom ping targets |
| page 45</P> |
| <P STYLE="margin-bottom: 0in">Illustration 26: Edit ping target |
| form 45</P> |
| <P STYLE="margin-bottom: 0in">Illustration 27: User admin page 47</P> |
| <P STYLE="margin-bottom: 0in">Illustration 28: User admin form 48</P> |
| <P STYLE="margin-bottom: 0in">Illustration 29: Config page: site |
| settings 49</P> |
| <P STYLE="margin-bottom: 0in">Illustration 30: Config page: user |
| settings 49</P> |
| <P STYLE="margin-bottom: 0in">Illustration 31: Config page: file |
| upload settings 50</P> |
| <P STYLE="margin-bottom: 0in">Illustration 32: Config page: |
| newsfeed settings 50</P> |
| <P STYLE="margin-bottom: 0in">Illustration 33: Common weblog ping |
| targets 51</P> |
| <P STYLE="margin-bottom: 0in">Illustration 34: Planet config |
| page 55</P> |
| <P STYLE="margin-bottom: 0in">Illustration 35: Planet |
| subscriptions page 56</P> |
| <P STYLE="margin-bottom: 0in">Illustration 36: Planet front |
| page 57</P> |
| </DIV> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <H1 CLASS="western" STYLE="page-break-before: always">1 - Introduction</H1> |
| <P>This user guide describes how to use Roller, a web application |
| that can support a single user weblog, thousands of weblogs and/or |
| group weblogs. You'll learn how to register as a new user, create |
| weblogs, edit and post weblog entries and manage your weblog. |
| You'll also learn how to customize your weblog's <I>blogroll</I>, a |
| list of links to your favorite web sites,and how to change the |
| look-and-feel or <I>theme</I> of your weblog.</P> |
| <P>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: |
| </P> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0in"><I>Weblog</I>: a weblog or blog |
| is an online journal written by one or more authors. In Roller a |
| weblog consists of weblog entries, weblog categories, favorite |
| bookmarks and settings that define the appearance and behavior of |
| the weblog. |
| </P> |
| <LI><P><I>Weblog entry</I>: a weblog entry is an individual entry |
| within a weblog with a title, date and text. |
| </P> |
| </UL> |
| <H1 CLASS="western">2 - Getting started with Roller</H1> |
| <P>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 <A HREF="#2.2.Getting%20started%20with%20an%20existing%20Roller%20installation%7Coutline">2.2 |
| - Getting started with an existing Roller installation</A> where we |
| discuss how to register for an ordinary Roller user account. |
| </P> |
| <H2>2.1 - Getting started with a new Roller installation</H2> |
| <P>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: |
| </P> |
| <P><B>How to create the first user and weblog on a fresh Roller |
| site:</B> |
| </P> |
| <OL> |
| <LI><P STYLE="margin-bottom: 0in">Start Roller and navigate to the |
| main page (e.g. <A HREF="http://localhost:8080/roller%29.">http://localhost:8080/roller). |
| </A> |
| </P> |
| <LI><P STYLE="margin-bottom: 0in">Click the <B>Register</B> link |
| in the top right corner of the page. |
| </P> |
| <LI><P STYLE="margin-bottom: 0in">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 |
| <B>Register User</B> button. |
| </P> |
| <LI><P STYLE="margin-bottom: 0in">On the Welcome to Roller page, |
| choose the <B>Click here</B> link to login as your new user. |
| You'll be taken to the Roller Main Menu page. |
| </P> |
| <LI><P STYLE="margin-bottom: 0in">On the Main Menu page, click the |
| <B>create a weblog</B> link to create a new weblog. |
| </P> |
| <LI><P>Fill out the Create Weblog page and when you're done click |
| the <B>Create Weblog</B> button. |
| </P> |
| </OL> |
| <H2><A NAME="2.2.Getting%20started%20with%20an%20existing%20Roller%20installation|outline"></A> |
| 2.2 - Getting started with an existing Roller installation</H2> |
| <P>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. |
| </P> |
| <P><B>How to create a user account</B> |
| </P> |
| <P>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. |
| </P> |
| <P>With a stock Roller installation, here's how you register a new |
| user: |
| </P> |
| <OL> |
| <LI><P STYLE="margin-bottom: 0in">Use your web browser to go to |
| the main page of the Roller installation |
| </P> |
| <LI><P STYLE="margin-bottom: 0in">Click the <B>Register</B> link |
| in the top right corner of the page |
| </P> |
| <LI><P STYLE="margin-bottom: 0in">Fill out the information for |
| your new user. Once you've filled out the form. click the <B>Register |
| User</B> button. |
| </P> |
| <LI><P>On the Welcome to Roller page, choose the <B>Click here</B> |
| link to login as your new user. You'll be taken to the Roller Main |
| Menu page. |
| </P> |
| </OL> |
| <P><B>How to create a weblog for your user</B> |
| </P> |
| <P>Here's how you create a new Roller weblog for your user: |
| </P> |
| <OL> |
| <LI><P STYLE="margin-bottom: 0in">Login to Roller by clicking the |
| <B>Login</B> or the <B>Main Menu</B> link |
| </P> |
| <LI><P STYLE="margin-bottom: 0in">On the Main Menu page, click the |
| <B>create a weblog</B> link to create a new weblog. |
| </P> |
| <LI><P>Fill out the Create Weblog page and when you're done click |
| the <B>Create Weblog</B> button. |
| </P> |
| </OL> |
| <H2>2.3 - Accepting an invitation to join a weblog</H2> |
| <P>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.</P> |
| <P><SPAN ID="Frame1" DIR="LTR" STYLE="float: left; width: 5.61in; height: 1.84in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_5c796a10.png" NAME="graphics1" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 1: Main Menu with invitation to join a group blog</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT> |
| </P> |
| <P>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. |
| </P> |
| <H2>2.4 - Getting around in Roller</H2> |
| <P>When you log into Roller, Roller sends you to the Roller <I>editor |
| interface</I> -- a set of web pages for editing and managing your |
| weblog and (if you have global admin privileges) the Roller |
| installation itself. |
| </P> |
| <P><B>Find your way around the editor interface</B> |
| </P> |
| <P>No matter where you go in the Roller <I>editor interface</I>, |
| you'll always see a <I>status bar</I> across the top of the page |
| with convenient links to the Roller front page and main menu. |
| </P> |
| <P><SPAN ID="Frame2" DIR="LTR" STYLE="float: left; width: 6.78in; height: 0.43in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_5e921c9f.png" NAME="graphics3" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 2: Status bar, no weblog</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT> |
| </P> |
| <P><BR><BR> |
| </P> |
| <P>That's what the status bar looks like when you are logged in |
| (assuming your username is 'admin'), but you haven't chosen a |
| specific weblog in which to work. What's going on here? |
| </P> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0in">The text on the left indicates |
| that you are logged in as user admin. |
| </P> |
| <LI><P STYLE="margin-bottom: 0in">On the right, the words <B>Front |
| Page</B> 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. |
| </P> |
| <LI><P>Also on the right, the words <B>Main Menu</B> 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. |
| </P> |
| </UL> |
| <P>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.' |
| </P> |
| <P><SPAN ID="Frame3" DIR="LTR" STYLE="float: left; width: 6.78in; height: 0.44in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_406a562a.png" NAME="graphics4" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 3: Status bar within weblog</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT> |
| </P> |
| <P><BR><BR> |
| </P> |
| <P><B>Going from your weblog back to the editor interface</B> |
| </P> |
| <P>When you're on your weblog page and you need a way to get back |
| to the Roller editor interface, look for the <I>weblog navbar</I>. |
| 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. |
| </P> |
| <P> |
| </P> |
| <P><SPAN ID="Frame4" DIR="LTR" STYLE="float: left; width: 2.16in; height: 1.47in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_3fb97cd5.png" NAME="graphics5" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 4: Weblog navigation bar</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P>That's what weblog navbar looks like this when you are <I>not</I> |
| logged in (note that the exact appearance varies in each theme). |
| The words <B>Front Page</B> 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 <B>Weblog</B> and <B>About</B>. Finally, there is a |
| link to <B>Login</B>. |
| </P> |
| <P> |
| </P> |
| <P><BR><BR> |
| </P> |
| <P><SPAN ID="Frame5" DIR="LTR" STYLE="float: left; width: 2.4in; height: 3.5in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_6e5d8126.png" NAME="graphics6" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 5: Weblog editor navbar</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P>That's what weblog navbar looks like this when you are <I>are</I> |
| 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 <B>Logout</B> link. |
| </P> |
| <P>After the logout link is the <I>editor navbar</I>, 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. |
| </P> |
| <P>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. |
| </P> |
| <H2>2.5 Changing the Language of the editor interface</H2> |
| <P>The Roller editor interface uses the locale (language and |
| country) User Profile setting to select the text to display in the |
| editor navbar and in each editor page. You can select your |
| preferred locale when registering or, if you have already |
| registered, on the Your Profile page. If a translation for your |
| preferred language is available on your Roller installation, the |
| editor interface will use this language for all the editor pages. |
| If you have selected your preferred language and the pages are |
| still displayed in English (or the default language of your Roller |
| installation?) there may not be a translation available for your |
| language. (If you or the person(s) responsible for your Roller |
| installation would like to translate Roller to an additional |
| language, please visit the Roller project website...) |
| (Translations are currently available for...)</P> |
| <H1 CLASS="western" STYLE="page-break-before: always">3 - Creating |
| and editing your weblog</H1> |
| <P>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 <B>New Entry</B> page for that weblog. If you |
| have more than one weblog or none at all, then you'll be taken to |
| the <B>Main Menu</B> page, shown below, so you can pick which |
| weblog to edit and/or create new weblogs. |
| </P> |
| <P><SPAN ID="Frame6" DIR="LTR" STYLE="float: left; width: 6.33in; height: 4.34in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m37111dbc.png" NAME="graphics7" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 6: Main menu</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P>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). |
| </P> |
| <H2 STYLE="page-break-before: always">3.1 - Creating and editing a |
| weblog entries</H2> |
| <P>To create a new weblog entry, go to your weblog's <B>New Entry</B> |
| 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 <B>Post to Weblog</B> 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. |
| </P> |
| <P> |
| </P> |
| <P><SPAN ID="Frame7" DIR="LTR" STYLE="float: left; width: 6.71in; height: 7.54in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><FONT SIZE=2><I>Illustration 7: |
| Weblog editor</I></FONT></P> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_27fdfebe.png" NAME="graphics8" ALIGN=LEFT WIDTH=613 HEIGHT=686 BORDER=0><BR CLEAR=LEFT><BR><BR> |
| </P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P>The above screenshow shows the RTE weblog entry editor |
| (editor-rte.jsp), a rich text editor that creates the HTML for you. |
| If you prefer to edit the HTML yourself, you can switch to the |
| plain text editor (editor-text.jsp). Use the Preferences:Settings |
| page to pick the weblog editor page you'd like to use.</P> |
| <P>Let's cover the fields on the page: |
| </P> |
| <UL> |
| <LI><P><B>Title</B>: this is the title for your post, it is |
| required.</P> |
| </UL> |
| <UL> |
| <LI><P><B>Category</B>: You must pick a category for your entry. |
| You can change the list of categories available in your weblog by |
| using the <B>Create & Edit:Categories</B> page. |
| </P> |
| </UL> |
| <UL> |
| <LI><P><B>Pub Time</B>: You don't need to set this unless you want |
| to post at a specific time in the past or in the future. The best |
| thing to do is to leave it blank. Roller will set it for you when |
| you click the Post to Weblog button to publish your new weblog |
| entry.</P> |
| </UL> |
| <UL> |
| <LI><P><B>Status</B>: This field displays the status of your |
| weblog entry. The possible values are Not saved, Draft and |
| Published. |
| </P> |
| </UL> |
| <UL> |
| <LI><P><B>Summary (optional)</B>: For long posts, you might want |
| to enter a sentence or two as summary in addition to the content. |
| If you do, your short summary will appear on the front page of |
| your weblog and the content will appear on the single-entry view. |
| Your summary will also be included in your newsfeed in an |
| <FONT FACE="Courier New"><atom:summary></FONT> element.</P> |
| <LI><P><B>Content</B>: This is where you put the body of your |
| weblog entry.</P> |
| </UL> |
| <P><BR><BR> |
| </P> |
| <P>Below the weblog entry fields are the Other Settings |
| </P> |
| <UL> |
| <LI><P><B>Comment Settings</B>: Click on the little plus-sign plus |
| (+) to expand the Comment Settings control, where you can |
| enable/disable comments on your blog entry. |
| </P> |
| </UL> |
| <UL> |
| <LI><P><B>Plugins to Apply</B>: 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 <B>Preferences:Settings</B> |
| page. Note that your Roller site administator controls the list of |
| available plugins. Here's the current list of plugins included in |
| Roller: |
| </P> |
| </UL> |
| <UL> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0in">Convert Line Breaks</P> |
| </UL> |
| </UL> |
| <UL> |
| <UL> |
| <LI><P>Topic Tags</P> |
| <LI><P>Textile Formatter</P> |
| <LI><P>Acronyms</P> |
| <LI><P>Bookmark Linker</P> |
| <LI><P>Email Scrambler</P> |
| <LI><P>Emoticons</P> |
| <LI><P>Read More Summary – <I>deprecated: use a summary |
| instead</I></P> |
| </UL> |
| </UL> |
| <UL> |
| <LI><P><B>Misc settings</B>: 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. |
| </P> |
| </UL> |
| <UL> |
| <LI><P><B>MediaCast settings</B>: 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 <I>podcast</I>. See the next |
| section for more information on podcasting with Roller. |
| </P> |
| </UL> |
| <P>Below that is a row of buttons. |
| </P> |
| <UL> |
| <LI><P><B>Post To Weblog</B>: Don't click this button until |
| ABSOLUTELY SURE you're ready to publish your weblog entry for the |
| entire world to see. |
| </P> |
| </UL> |
| <UL> |
| <LI><P><B>Submit for Review</B>: 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. |
| </P> |
| </UL> |
| <UL> |
| <LI><P><B>Save as Draft</B>: Click this button to save your post |
| as a draft entry for editing later. |
| </P> |
| </UL> |
| <UL> |
| <LI><P><B>Preview</B>: 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. |
| </P> |
| </UL> |
| <UL> |
| <LI><P><B>Spell Check</B>: Click this button to spell check your |
| post. Be forewarned that Roller's spell checker is far from |
| perfect. It catches HTML tags as spelling errors and its user |
| interface is clunky. We're investigating alternatives.</P> |
| </UL> |
| <H2>3.2 - Finding and editing weblog entries</H2> |
| <P>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 <B>Create & Edit:New Entry</B> page, they are still |
| available to your readers on your weblog pages. They're available |
| to you too. |
| </P> |
| <H3>3.2.1 - <B>Finding old entries with the Create & Edit:New |
| Entry page</B> |
| </H3> |
| <P>If you go to the <B>Create & Edit:New Entry</B> 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. |
| </P> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0in"><I>Pending Entries</I> 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. |
| </P> |
| <LI><P STYLE="margin-bottom: 0in"><I>Draft Entries</I> 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. |
| </P> |
| <LI><P><I>Recent Entries</I> 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. |
| </P> |
| </UL> |
| <P><BR><BR> |
| </P> |
| <P><SPAN ID="Frame28" DIR="LTR" STYLE="float: left; width: 6.85in; height: 5.23in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m199b047d.png" NAME="graphics11" ALIGN=LEFT WIDTH=658 HEIGHT=485 BORDER=0><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P STYLE="margin-top: 0.08in"><FONT SIZE=2><I>Illustration 8: Edit |
| entries page</I></FONT></P> |
| <P STYLE="margin-top: 0.08in"><BR><BR> |
| </P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <H3>3.2.2 - <B>Finding old entries with the Create & |
| Edit:Entries page</B> |
| </H3> |
| <P STYLE="font-weight: medium">You can use the Create & |
| Edit:Entries to find and edit your old posts. That includes posts |
| that have scrolled-off the bottom of the Pending, Draft and Recent |
| Entries lists we discussed above. When you first arrive on the page |
| it will show you most recent entries, as shown in the screenshot |
| below. If you want to find an old post you can use the start and |
| end date calendars to look for posts in a specific time period. You |
| can edit any of the entries in the Weblog Entries list by simply |
| clicking on its title. |
| </P> |
| <H3>3.2.3 - <B>Finding old entries using the pages of your weblog</B> |
| </H3> |
| <P>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 <B>Edit</B> link on each weblog entry, which |
| will load that entry into the weblog editor (i.e. the New Entry |
| page). |
| </P> |
| <P>There are several ways to do this: |
| </P> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0in"><B>Using the calendar</B>: most |
| weblog themes include a calendar, which you can use to navigate |
| back and forwards in time. |
| </P> |
| <LI><P STYLE="margin-bottom: 0in"><B>Using the next/prev links</B>: |
| most weblog themes include next/previous links, which allow you to |
| navigate back and forwards in time. |
| </P> |
| <LI><P><B>Using URLs</B>: 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. |
| </P> |
| </UL> |
| <H3>3.2.4 - <B>Finding old entries with Roller's built-in search |
| engine</B> |
| </H3> |
| <P>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 <B>Edit</B> link. |
| </P> |
| <H2 STYLE="page-break-before: always">3.3 - Weblog categories</H2> |
| <P>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. |
| </P> |
| <P>When you write a new weblog post you must decide which category |
| to place it in. On the <B>Create & Edit:New Entry</B> 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. |
| </P> |
| <H3>3.3.1 - <B>The Weblog Category Chooser</B> |
| </H3> |
| <P>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 <FONT FACE="Courier New">#showWeblogCategoryChooser()</FONT> |
| 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. |
| </P> |
| <H3>3.3.2 - <B>RSS Feed for Each Category</B> |
| </H3> |
| <P>Your weblog's main RSS newsfeed includes all categories, but |
| users can choose to subscribe to specific categories. All of the |
| stock Roller weblog templates display a list of your RSS feeds |
| (displayed by the <FONT FACE="Courier New">#showRSSLinks()</FONT> |
| macro), one for all categories and one for each separate category. |
| </P> |
| <H3>3.3.3 - <B>Adding, Renaming, and Removing Weblog Categories</B> |
| </H3> |
| <P>You can change the names of your categories, add new categories, |
| and delete categories using the <B>Create & Edit:Categories</B> |
| page of the Roller Editor UI. |
| </P> |
| <H2 STYLE="page-break-before: always">3.4 - Podcasting with Roller</H2> |
| <P>Roller now includes support for <I>podcasting</I>, 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 <A HREF="http://ipodderx.com/">iPodderX</A><IMG SRC="http://www.rollerweblogger.org/wiki/images/out.png" NAME="graphics10" ALIGN=BOTTOM WIDTH=6 HEIGHT=6 BORDER=0>) |
| downloads the audio files that are referenced in your newsfeed and |
| copies them to an music player, such as an MP3 player. |
| </P> |
| <H3>3.4.1 - <B>How to create a podcast feed with Roller</B> |
| </H3> |
| <P>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: |
| </P> |
| <UL> |
| <LI><P>Record an interesting Podcast (that's the hard part, by the |
| way) |
| </P> |
| </UL> |
| <UL> |
| <LI><P>Save your Podcast in MP3 format (or whatever you prefer). |
| </P> |
| </UL> |
| <UL> |
| <LI><P>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 <B>Create & |
| Edit: File Uploads</B> 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: |
| </P> |
| </UL> |
| <PRE STYLE="margin-bottom: 0.2in"> <FONT FACE="Courier New">http://example.com/roller/resources/nina/mycast.mp3</FONT></PRE> |
| <UL> |
| <LI><P>Create a new Roller Weblog entry via <B>Create & |
| Edit:New Entry</B> 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: |
| </P> |
| </UL> |
| <PRE> Hey now! I just created my first Podcast you can download it |
| by clicking on this file name: |
| |
| <FONT FACE="Courier New"> <a href="http://example.com/roller/resources/nina/mycast.mp3">mycast.mp3</a></FONT></PRE> |
| <UL> |
| <LI><P>And the most important step: in the lower-half of the Edit |
| Weblog page, you'll see an expandable control labelled <I>+MediaCast |
| Settings</I>. Click on that to expand the MediaCast control and |
| paste into the URL field the URL of your Podcast. |
| </P> |
| </UL> |
| <UL> |
| <LI><P>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: |
| </P> |
| </UL> |
| <P> |
| </P> |
| <P><SPAN ID="Frame8" DIR="LTR" STYLE="float: left; width: 6.37in; height: 1.37in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_33edbb94.png" NAME="graphics9" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 9: Podcast URL field</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P><BR><BR> |
| </P> |
| <UL> |
| <LI><P>Roller will add the Podcast to your RSS newsfeed as an |
| <TT><enclosure></TT>. 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: |
| </P> |
| </UL> |
| <PRE><FONT FACE="Courier New"> <enclosure url="http://example.com/roller/resources/nina/mycast.mp3" </FONT> |
| <FONT FACE="Courier New"> type="audio/x-mpeg" length="3409127" /></FONT></PRE><P> |
| That's all there is to podcasting with Roller.</P> |
| <P><BR><BR> |
| </P> |
| <P><BR><BR> |
| </P> |
| <P><BR><BR> |
| </P> |
| <H2 STYLE="page-break-before: always">3.5 - Referrer rankings</H2> |
| <P>The <B>Weblog:referrer</B> referrer rankings page shows the hits |
| that are coming in from other websites and weblogs that have links |
| to your weblog and to specific entries in your weblog. By looking |
| at your referrer logs, you can get an idea of who is reading and |
| commenting on your weblog. |
| </P> |
| <P>Working with comments and trackbacks</P> |
| <P>Roller supports weblog comments and <I>trackbacks</I><SPAN STYLE="font-style: normal">, |
| which provide a way for other bloggers to add comments to your blog |
| remotely.</SPAN> By default comments and trackbacks are enabled, |
| but you can turn them off on your weblog's <B>Preferences:Settings</B> |
| page of your weblog. Note that turning off comments, disables both |
| comments and trackbacks. |
| </P> |
| <H2>3.6 - Comment notification via email</H2> |
| <P>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 <B>Preferences:Settings</B> page. |
| </P> |
| <P>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. |
| </P> |
| <H2>3.7 - Comment management and moderation</H2> |
| <P STYLE="font-style: normal; font-weight: medium">If you'd like to |
| preview and approve comments before they are displayed on your |
| weblog, then you'll want to turn on <I>comment moderation</I> via |
| <B>Preferences:Settings</B>. 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 <B>Create & Edit:Comments</B> 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.</P> |
| <P STYLE="font-style: normal"><B>The comment management page</B></P> |
| <P><SPAN STYLE="font-weight: medium"><SPAN STYLE="font-style: normal">The |
| comment management page, shown in illustration 10, allows you to |
| manage comments for your weblog. If you arrive on the page from the |
| link in a comment notification email, then you'll see only the |
| comments for the one entry that was commented upon. If you arrive |
| via the menu, you'll see all recent comments in reverse |
| chronological order.</SPAN></SPAN></P> |
| <P STYLE="font-style: normal; font-weight: medium">Comments that |
| are suspected to be spam are shown with a light red background, |
| with the spam check-box checked. Comments that are new and pending |
| your review are shown with a light yellow background. |
| </P> |
| <P STYLE="margin-left: -0.01in; font-weight: medium"><I>How to |
| moderate comments</I></P> |
| <UL> |
| <LI><P STYLE="font-style: normal; font-weight: medium">Review each |
| new comment and decide if it is to be approved for display, marked |
| as spam and hidden or deleted entirely. |
| </P> |
| <LI><P><SPAN STYLE="font-weight: medium"><SPAN STYLE="font-style: normal">Only |
| comments that are marked as approved and are not spam will be |
| displayed on your weblog. So set (or unset) the corresponding |
| chec</SPAN></SPAN>kboxes for each comment, or leave them the way |
| they are. |
| </P> |
| <LI><P>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.</P> |
| </UL> |
| <P STYLE="margin-left: -0.01in; font-weight: medium"><I>How to |
| search weblog comments</I></P> |
| <P STYLE="margin-left: -0.01in"><SPAN STYLE="font-weight: medium">You |
| can also use the comment management page to search for comments |
| across all entries in your weblog by keyword, status and date. Use |
| the Filter comments area of the page to set the fields you want to |
| search and click the Query button. If there are more comments than |
| can be displayed on one page, then a next page link will be |
| displayed at the top of the list of comments so that you can |
| navigate into the past<SPAN STYLE="font-style: normal">.</SPAN></SPAN></P> |
| <P STYLE="font-style: normal; font-weight: medium"><BR><BR> |
| </P> |
| <P><SPAN ID="Frame10" DIR="LTR" STYLE="float: left; width: 6.93in; height: 4.24in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_276ad74f.png" NAME="graphics15" ALIGN=LEFT WIDTH=98% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 10Comment (and trackback) management page</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P><B>Global comment management</B></P> |
| <P STYLE="font-weight: medium">If your user has global |
| adminstration privileges, then you can manage comments across the |
| entire Roller site, including every weblog. To do this, go to the |
| <B>Server Adminstation:Comments</B> page and you'll see a page that |
| is almost identical to the weblog-specific comment management page. |
| </P> |
| <P STYLE="font-weight: medium"><I>Limitations of global comment |
| management</I></P> |
| <P STYLE="font-weight: medium">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.</P> |
| <P><B>A word about receiving trackbacks</B></P> |
| <P STYLE="font-weight: medium">Incoming trackbacks are treated |
| differently, depending on how your Roller site is setup. Your site |
| adminstrator may choose to disable incoming trackbacks entirely. In |
| that case, anybody who tries to send a comment to your weblog via |
| trackback will receive and error messae and no comment will be |
| added.</P> |
| <P STYLE="margin-bottom: 0in"><SPAN STYLE="font-weight: medium">Your |
| site administrator may choose to enable a spam prevention measure |
| known as <I>trackback verification. </I>If that's the case, then |
| each incoming trackback will be verified. If the weblog that sent |
| you the trackback does not link to your weblog entry, then that |
| trackback will be marked as un-approved and pending. You'll have to |
| visit the comment management page to approve that trackback before |
| it is displayed as a comment on your weblog.</SPAN></P> |
| <H2>3.8 - <B>Preventing weblog spam</B> |
| </H2> |
| <P>There are three forms of comment spam that can affect your |
| weblog:</P> |
| <UL> |
| <UL> |
| <LI><P><I>Comment spam</I>: 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 <I>spambot.</I><SPAN STYLE="font-style: normal"> |
| </SPAN> |
| </P> |
| <LI><P><I>Trackback spam</I>: spam that arrives via trackbacks |
| sent by a spambot.</P> |
| <LI><P><I>Referrer spam</I>: spam that arrives in web requests |
| and appears on the <B>Create & Edit:Referrers</B> page of |
| your Roller blog or on your blog (but only if your blog theme |
| uses the <FONT FACE="Courier, sans-serif">#showReferrers()</FONT> |
| macro).</P> |
| </UL> |
| </UL> |
| <P>Fortunately, there are counter-measures for each type of spam. |
| For comment and trackback spam, you can use email notification of |
| comments, comment moderation and trackback verification (described |
| in the previous section) to manage spam. That's not all. Roller |
| also includes a blacklisting feature, which can be used to fight |
| all three forms of spam.</P> |
| <H3>3.8.1 - Three levels of blacklisting</H3> |
| <P><SPAN STYLE="font-weight: medium">Roller uses a <I>blacklist</I>, |
| a lists of words which are used to check incoming comments, |
| trackbacks and referrers for spam. The blacklist includes several |
| thousand words and regular expressions which which are used to |
| check incoming comments and trackbacks. If the name, URL or content |
| of a comment or trackback includes one of the blacklist words or |
| matches one of the expressons then that comment or trackback is |
| marked as spam and is not displayed on your weblog, unless you use |
| the comment management page to unmark it.</SPAN></P> |
| <P STYLE="font-weight: medium">Actually, there are three levels of |
| blacklist:</P> |
| <UL> |
| <UL> |
| <LI><P STYLE="font-weight: medium">Level 1 blacklist: This is the |
| built-in blacklist, the one that comes with Roller. This can only |
| be changed by somebody with root access to the Roller server |
| itself.</P> |
| <LI><P><SPAN STYLE="font-weight: medium">Level 2 blacklist: This |
| is the site wide blacklist, which can only be edited by a global |
| administrator via the </SPAN><B>Server Admin:Configuration</B><SPAN STYLE="font-weight: medium"> |
| page.</SPAN></P> |
| <LI><P STYLE="font-weight: medium">Level 3 blacklist: Weblog |
| specific blacklist, which you control in the <B>Preferences:Settings</B> |
| page of your weblog.</P> |
| </UL> |
| </UL> |
| <P STYLE="font-weight: medium">Incoming comments and trackbacks are |
| checked against all three levels of blacklist. Incoming referrers, |
| however, are only checked against the levels 2 and 3 blacklist.</P> |
| <H3>3.8.2 - How to add words and expressions to the blacklist</H3> |
| <P STYLE="font-weight: medium">If you have a spam problem on your |
| weblog and you'd like to add words to the blacklist, it's probably |
| better for you to ask your administrator to add the words to the |
| level 2 blacklist for you. That way, every blogger on the site will |
| benefit from the addition. If you must do it yourself, here's how |
| you do it:</P> |
| <UL> |
| <UL> |
| <LI><P STYLE="font-weight: medium">Go to the <B>Preferences:Settings</B> |
| page and scroll down to the blacklist fields</P> |
| <LI><P STYLE="font-weight: medium">Enter your spam words, one per |
| line</P> |
| <LI><P><SPAN STYLE="font-weight: medium">Lines that begin with a |
| left parenthesis will be treated as regular expressions (see the |
| Java API documentation for <FONT FACE="Courier New">javax.util.regex.Pattern</FONT> |
| for a guide to regular expressions). Don't try to use a regular |
| expression unless you really know what you're doing.</SPAN></P> |
| </UL> |
| </UL> |
| <H2>3.9 - Sending trackbacks</H2> |
| <P>If you are writing about something you read on another weblog, |
| you want to let the author and readers of that weblog know that you |
| are doing so, and that other weblog is trackback enabled, then you |
| should send that weblog a trackback ping. Here's a story that |
| illustrates how trackback works: |
| </P> |
| <UL> |
| <LI><P>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. |
| </P> |
| </UL> |
| <UL> |
| <LI><P>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: <BR> |
| </P> |
| </UL> |
| <P><SPAN ID="Frame11" DIR="LTR" STYLE="float: left; width: 6.79in; height: 1.33in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m71a6a7f9.png" NAME="graphics13" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 11: Send trackback control</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <UL> |
| <LI><P>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: |
| </P> |
| </UL> |
| <P><SPAN ID="Frame12" DIR="LTR" STYLE="float: left; width: 6.35in; height: 2.78in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_5ce1ba58.png" NAME="graphics16" ALIGN=LEFT WIDTH=91% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 12: Result of sending trackback</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <UL> |
| <LI><P>You should now see your trackback listed among the comments |
| on Otto's blog entry. |
| </P> |
| </UL> |
| <H1 CLASS="western" STYLE="page-break-before: always">4 - Managing |
| your weblog settings</H1> |
| <P>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. |
| </P> |
| <P>To manage your weblog, use the Prefences menu. You can get there |
| from the Main Menu page, by clicking the <B>Settings</B> link for |
| your blog. Or, if you're already editing your weblog, you can just |
| click on the <B>Preferences</B> menu in the tabs. Once you're |
| there, the tabbed menu should look like this: |
| </P> |
| <P><SPAN ID="Frame13" DIR="LTR" STYLE="float: left; width: 4.92in; height: 1.15in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_18eef266.png" NAME="graphics17" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 13: Weblog preferences menu</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P>In the rest of this section we'll cover each of the items on the |
| Preferences menu. |
| </P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <H2 STYLE="page-break-before: always">4.1 - Weblog settings</H2> |
| <P>The <B>Preferences:Settings</B> page allows you to set the |
| configuration parameters for your weblog. You can see all of the |
| settings on the screen-shot below (which needs to be updated to |
| Roller 2.1): |
| </P> |
| <P><SPAN ID="Frame14" DIR="LTR" STYLE="float: left; width: 6.78in; height: 5.95in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><FONT SIZE=2><I>Illustration 14: |
| Weblog settings page part 1</I></FONT></P> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_27e86c29.png" NAME="graphics2" ALIGN=LEFT WIDTH=651 HEIGHT=549 BORDER=0><BR CLEAR=LEFT><BR><BR> |
| </P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P>Here is an explanation of each of the settings on the weblog |
| <B>Preferences:Settings</B> page: |
| </P> |
| <P><B>General settings</B> |
| </P> |
| <UL> |
| <LI><P><B>Title</B> - 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 |
| <TT>#showWebsiteTitle()</TT> |
| </P> |
| </UL> |
| <UL> |
| <LI><P><B>Description</B> - 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 <TT>#showWebsiteDescription()</TT>. |
| </P> |
| </UL> |
| <UL> |
| <LI><P><B>Email address of weblog owner</B>: 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.</P> |
| <LI><P><B>Locale</B>: Choose the language and country for this |
| weblog. (Which is used how?) (See section x.x for setting the |
| locale for your user account.)</P> |
| <LI><P><B>Timezone</B>: Choose the timezone for this weblog. |
| (Which is used when displaying entries?)</P> |
| </UL> |
| <UL> |
| <LI><P><B>Default from address</B>: Enter the email address that |
| should be used as the <I>from address</I> for emails sent by |
| Roller. (Removed from Roller 2.1?)</P> |
| </UL> |
| <UL> |
| <LI><P><B>Page to be used as the homepage</B> - Choose a page |
| template to be used as the main page of your weblog. (Removed |
| from Roller 2.1?)</P> |
| <LI><P>Weblog is active</P> |
| </UL> |
| <UL> |
| <LI><P><B>Weblog editor page to be used</B> - Choose a weblog |
| editor page, some are rich-text editors: |
| </P> |
| </UL> |
| <UL> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0in">editor-text.jsp: Simple text |
| editor, you must enter HTML</P> |
| <LI><P STYLE="margin-bottom: 0in">editor-rte.jsp: Rich text |
| editor (works in Firefox and IE but not Safari)</P> |
| </UL> |
| </UL> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <UL> |
| <LI><P><B>Number of entries to display on weblog</B>: Enter the |
| maximum number of entries to be displayed on your weblog.</P> |
| </UL> |
| <P><B>Comments</B> |
| </P> |
| <UL> |
| <LI><P><B>Allow comments for your weblog?</B> – Check this |
| box to allow visitors to leave comments on your weblog. |
| </P> |
| <LI><P><B>Moderate comments</B> – Check this box to enable |
| comment moderation (i.e. you must approve each comment before it |
| is displayed).</P> |
| <LI><P><B>Email comments</B> – Check this box to receive an |
| email notification of each new comments. |
| </P> |
| <LI><P><B>Default from e-mail address for comments</B> – |
| This will be used as the from address in comment emails sent by |
| Roller.</P> |
| </UL> |
| <P><B>Default comment settings</B></P> |
| <UL> |
| <LI><P><B>By default, allow comments for new entries</B> – |
| Check this box to enable comments on your weblog. You can also |
| control comments on each individual weblog entry.</P> |
| <LI><P><B>Default time to allow comments for new entries </B><SPAN STYLE="font-weight: medium">– |
| 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.</SPAN></P> |
| <LI><P STYLE="font-weight: medium"><B>Apply comment defaults to |
| all existing entries? </B>- If you check this box, when you click |
| the Save button the comment defaults you have set will be applied |
| to all existing comments.</P> |
| </UL> |
| <P STYLE="font-weight: medium"><BR><BR> |
| </P> |
| <P><BR><BR> |
| </P> |
| <P><BR><BR> |
| </P> |
| <P><BR><BR> |
| </P> |
| <P><SPAN ID="Frame27" DIR="LTR" STYLE="float: left; width: 6.93in; height: 3.59in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><FONT SIZE=2><I>Illustration 15: |
| Weblog settings page part 2</I></FONT></P> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m48711925.png" NAME="graphics14" ALIGN=LEFT WIDTH=650 HEIGHT=522 BORDER=0><BR CLEAR=LEFT><BR><BR> |
| </P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P><BR><BR> |
| </P> |
| <P><B>Weblog client API</B> |
| </P> |
| <UL> |
| <LI><P><B>Enable Blogger API for your weblog</B> - 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. |
| </P> |
| </UL> |
| <UL> |
| <LI><P><B>Category for posts recieved via Blogger API</B> - Choose |
| the category for incoming posts made via the Blogger API. This |
| only applies if you blogging client does not support categories. |
| </P> |
| </UL> |
| <P><B>Formatting</B> |
| </P> |
| <UL> |
| <LI><P><B>Default entry formatters: </B><SPAN STYLE="font-weight: medium">this |
| is the list of plug-ins to be enabled by default on a new weblog |
| entry. </SPAN> |
| </P> |
| </UL> |
| <P><B>Spam pevention</B> |
| </P> |
| <UL> |
| <LI><P><B>Ignore incoming referrer URLs that contain any of these |
| (comma-separated) words</B> - you can use this to filter out what |
| referrers are accepted. Somewhat useful if you start getting hit |
| by referrer spam, but not a complete solution to the referrer spam |
| problem. See section for more information on spam prevention.</P> |
| </UL> |
| <H2 STYLE="page-break-before: always">4.2 - Weblog themes</H2> |
| <P>A weblog theme is a set of templates, style-sheets and image |
| that determine how your weblog will be displayed. A theme can |
| define both the layout and color-scheme of your weblog. When you |
| start a Roller weblog, you choose from one of the built-in themes. |
| You can change your weblog's theme at any time by going to the |
| <B>Preferences:Theme</B> page, show below.</P> |
| <P><BR><BR> |
| </P> |
| <P><SPAN ID="Frame15" DIR="LTR" STYLE="float: left; width: 6.38in; height: 5.22in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_3bfac83.png" NAME="graphics19" ALIGN=LEFT WIDTH=97% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 16: Theme selection page</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P>You can also choose to customize your theme. If you click the |
| <I>Customize</I> button the templates that define your current |
| theme will be copied into your blog where you can edit theme. See |
| section <A HREF="#5.Customizing%20your%20weblog's%20theme%7Coutline">5 |
| - Customizing your weblog's them</A> for more information on theme |
| customization.</P> |
| <P><B>WARNING</B>: if you <I>have</I> customized your theme, then |
| watch out. Switching themes using the <B>Preferences:Theme</B> page |
| will destroy the custom changes you've made. |
| </P> |
| <H2>4.3 - Uploading Files</H2> |
| <P>Roller includes a file-upload feature that allows you to upload |
| images and other files for use in your weblog. |
| </P> |
| <P>Here are the steps to upload an image to Roller and to use it in |
| a blog entry: |
| </P> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0in"><B>Upload the file</B>: Use the |
| <B>Ceate & Edit:File Uploads</B> 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. |
| </P> |
| <LI><P STYLE="margin-bottom: 0in"><B>Create a weblog entry</B>: |
| Use the <B>Create & Edit:New Entry</B> page to add or edit a |
| weblog entry. |
| </P> |
| <LI><P><B>Include the image</B>: Place an HTML <img> tag |
| where you want the image in your blog entry. |
| </P> |
| </UL> |
| <P>If you don't know HTML, you might need help with that last step. |
| Here is what an <img> tag looks like. |
| </P> |
| <PRE STYLE="margin-bottom: 0.2in"><img src="http://jroller.com/resources/mrroller/leo.gif" alt="one happy baby" /></PRE><P> |
| You need to include the <TT>src</TT> attribute and it's also good |
| form to include an <TT>alt</TT> attribute that describes the image |
| (for those who cannot see the image). |
| </P> |
| <H2 STYLE="page-break-before: always">4.4 - Setting up a group blog</H2> |
| <P>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 <A HREF="http://www.rollerweblogger.org/wiki/Wiki.jsp?page=UserGuide_2.x#ref-UserGuide_2.x-3">[3]</A> |
| for instructions). Navigate to the <B>Members</B> menu item in the |
| <B>Preferences</B> tab. The <B>Preferences:Members</B> page enables |
| weblog admins to invite members to a group blog and manage the |
| group blog user access. |
| </P> |
| <P><SPAN ID="Frame16" DIR="LTR" STYLE="float: left; width: 6.67in; height: 4.19in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_796ebdaa.png" NAME="graphics21" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 17: Weblog permissions page</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P>You can use the <B>Invite new member</B> 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: |
| </P> |
| <UL> |
| <LI><P><B>Admin</B>: 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. |
| </P> |
| <LI><P><B>Author</B>: 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. |
| </P> |
| </UL> |
| <UL> |
| <LI><P><B>Limited</B>: limited bloggers can create and edit blog |
| entries and save them as drafts, but cannot publish them to the |
| web. |
| </P> |
| </UL> |
| <P>Select <B>Invite new member</B> 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 <B>Send |
| Invitation</B>. If roller is not configured to talk to the mail |
| server, you may get the following messages: |
| </P> |
| <PRE>User successfully invited. |
| ERROR: Notification email(s) not sent, due to Roller configuration <BR>or mail server problem.</PRE><P> |
| 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: |
| </P> |
| <PRE STYLE="margin-bottom: 0.2in">You are invited to join weblog [weblog name will appear here] – accept | decline</PRE><P> |
| 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 <B>Save</B> button. You can also remove users from |
| the site, but note that you cannot reduce your own permissions or |
| remove youself from the weblog. |
| </P> |
| <P><B>Accept or Decline a Group Blog Invitation</B> |
| </P> |
| <P>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: |
| </P> |
| <PRE>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</PRE><P> |
| Click 'accept' to become a member of the group blog or 'decline' to |
| turn down the invitation. |
| </P> |
| <P><B>Contribute to a group blog</B> |
| </P> |
| <P>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 <B>Main Menu</B> 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). |
| </P> |
| <P>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. |
| </P> |
| <P><B>Resign from a Group Blog</B> |
| </P> |
| <P>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'. |
| </P> |
| <P><BR><BR> |
| </P> |
| <H1 CLASS="western" STYLE="page-break-before: always"><A NAME="5.Customizing%20your%20weblog's%20theme|outline"></A> |
| 5 - Customizing your weblog's theme</H1> |
| <P>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 |
| <B>Preferences:Theme</B> page to switch to a different one. |
| </P> |
| <P>If you're not happy with the set of themes built-into Roller, |
| you can create a custom theme by changing the templates used to |
| display your weblog. To customize your theme, go to the |
| <B>Preferences:Theme</B> 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 |
| <B>Preferences:Templates</B> page to view a list of the templates |
| that define your weblog's appearance. |
| </P> |
| <P><B>Weblog templates</B></P> |
| <P>Your weblog's theme is defined by a set of templates. A template |
| is a file with some special macros that indicate where Roller is |
| supposed to put your weblog entries, weblog calendar, and other |
| dynamically created content. See the <B>Roller Macro Reference</B> |
| 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. |
| </P> |
| <P>Roller uses the powerful Velocity template language to define |
| templates and this gives you a lot of power and flexibility in |
| customizing the look and feel and layout of your weblog pages. You |
| can set and use variables, use if-then-else statements and |
| specially designed macros to control your weblog's appearance. For |
| more information on the Velocity template language, refer to the |
| Velocity web site and the <B>Velocity Reference Guide</B>. |
| </P> |
| <P>Below is the Roller <B>Preferences:Templates</B> page. Use this |
| page to add, remove, and to select pages for editing. |
| </P> |
| <P> |
| </P> |
| <P><SPAN ID="Frame17" DIR="LTR" STYLE="float: left; width: 6.74in; height: 3.87in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m66b60ed6.png" NAME="graphics22" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 18: Weblog templates page</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P><B>Editing a weblog template</B></P> |
| <P>Below is the <B>Preferences:Edit Tempate</B> 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. |
| </P> |
| <P><SPAN ID="Frame18" DIR="LTR" STYLE="float: left; width: 6.42in; height: 6.65in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_65a662dd.png" NAME="graphics26" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 19: Edit template page</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT> |
| </P> |
| <P><BR><BR> |
| </P> |
| <H2 STYLE="page-break-before: always">5.1 - Weblog and day |
| templates |
| </H2> |
| <P>Every Roller theme is a little different, but all themes have a |
| minimum of two templates: a <B>Weblog</B> template, which defines |
| the main page of your blog, and a <B>_day</B> page, which defines |
| how each day of entries are displayed on your weblog. Let's discuss |
| each of these templates.</P> |
| <P><B>Your Weblog page</B> |
| </P> |
| <P>Your weblog page is the main page of your web site, the one that |
| is specified as the default page in your <B>Preferences:Settings</B> |
| 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. |
| </P> |
| <P>To understand the weblog template, let's take a look at a simple |
| example. Below is the weblog page template from Roller's Basic |
| theme. This is a good example because it is so basic and because it |
| uses most, if not all, of the Roller macros that you'd want to use |
| on a weblog page. Roller macros and Velocity expressions are shown |
| in bold.</P> |
| <P><BR><BR> |
| </P> |
| <PRE STYLE="margin-left: 0.5in"><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <title><B>#showWebsiteTitle()</B></title> |
| <style type="text/css"><B>#includePage("_css")</B></style> |
| <B>#showRSSAutodiscoveryLink()</B> |
| <script type="text/javascript" src="<B>$ctxPath</B>/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><B>#showWebsiteTitle()</B></h1> |
| <p class="descrip"><B>#showWebsiteDescription()</B></p> |
| <B>#showWeblogCategoryChooser()</B><br> |
| </center> |
| <B>#showWeblogEntries("_day" 15)</B> |
| </td> |
| <td width="20%" valign="top" bgcolor="#ffffff" width="20%"> |
| <h2>Calendar</h2> |
| <B>#showWeblogCalendar()</B><br> |
| <h2>RSS Feeds</h2> |
| <B>#showRSSBadge()</B><br> |
| <B>#showRSSLinks()</B> |
| <h2>Links</h2> |
| <B>#showBookmarks("Blogroll" true false)</B><br> |
| <B>#showBookmarks("News" true false)</B> |
| <h2>Navigation</h2> |
| <B>#showBasicNavBar(true)</B><br> |
| <B>#showEditorNavBar(true)</B><br> |
| <h2>referrers</h2> |
| #<B>showreferrers(30 20)</B> |
| </td> |
| </tr></tbody></table> |
| </body> |
| </html></PRE><P> |
| For a listing of key Roller macros and variables, refer to the |
| section below. The most important macro on the page is the |
| <B>#showWeblogEntries</B> 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. |
| </P> |
| <P><B>Your Day Page</B> |
| </P> |
| <P>Your Day page is used by the <B>#showWeblogEntries</B> 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: |
| </P> |
| <PRE STYLE="margin-left: 0.49in"><div class="box"> |
| <div class="entry"> |
| <B>#showDayPermalink( $day )</B> |
| <B>#showEntryDate( $day )</B> |
| </div> |
| <B>#foreach( $entry in $entries )</B> |
| <p> |
| <b><B>$entry.title</B></b> <B>$entry.text</B> |
| <span class="dateStamp">(<B>$entry.pubTime</B>)</span> |
| <B>#showEntryPermalink( $entry )</B> |
| <B>#showCommentsPageLink( $entry )</B> |
| </p> |
| <B>#end </B> |
| <B>#showLinkbacks( $day )</B> |
| </div></PRE><P> |
| Note that there are two variables <B>$day</B> and <B>$entries</B> |
| available for use in the day template that are not available in |
| other templates. The <B>$day</B> variable refers to a date object |
| (<FONT FACE="Courier New">java.util.date</FONT>) that contains the |
| date of the day that is being rendered by the day page. The |
| <B>$entries</B> variable contains a collection of weblog entry |
| objects (<FONT FACE="Courier New">org.roller.model.WeblogEntryData</FONT>). |
| The example above uses a Velocity <B>#foreach</B> loop to iterate |
| through the individual entries in the entries collection and to |
| display the title, text, and publish time of each. |
| </P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <H2 STYLE="page-break-before: always">5.2 - Define standard headers |
| and footers with a decorator</H2> |
| <P>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. |
| </P> |
| <P>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 <B>$decorator_body</B> marker below: |
| </P> |
| <PRE STYLE="margin-left: 0.51in"><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <!-- decorator began with line above --> |
| <html> |
| <head> |
| <B>#showContentType("text/html; charset=utf-8")</B> |
| <B>#showContentLanguage($locale.language)</B> |
| <B>#includePage("_css")</B> |
| <B>#showRSSAutodiscoveryLink()</B> |
| <script type="text/javascript" src="<B>$ctxPath</B>/theme/scripts/roller.js"> |
| </script> |
| <title><B>#showWebsiteTitle()</B> : <B>#showPageName()</B></title> |
| </head> |
| <body> |
| <!-- next print \$decorator_body --> |
| |
| <B>$decorator_body</B> |
| |
| <!-- now print decorator footer/close html --> |
| </body> |
| </html></PRE><P> |
| If you have a decorator like the above, then you don't need to |
| include <html> and <body> tags on your individual |
| pages. |
| </P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <H2 STYLE="page-break-before: always">5.3 - Roller Macros and |
| Variables |
| </H2> |
| <P>For a complete list of the Roller Macros, see the Roller Macro |
| Reference. |
| </P> |
| <P>There are also a host of variables and objects that are |
| available for your use in page templates: |
| </P> |
| <DL> |
| <DD> |
| <TABLE WIDTH=610 BORDER=1 CELLPADDING=2 CELLSPACING=3> |
| <COL WIDTH=119> |
| <COL WIDTH=472> |
| <TR> |
| <TD WIDTH=119> |
| <P><FONT SIZE=2><B>$now</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=472> |
| <P><FONT SIZE=2>The current time (a java.util.Date object).</FONT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=119> |
| <P><FONT SIZE=2><B>$ctxPath</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=472> |
| <P><FONT SIZE=2>The path under which Roller is running (see |
| Webapp context).</FONT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=119> |
| <P><FONT SIZE=2><B>$baseURL</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=472> |
| <P><FONT SIZE=2>Base URL for your Roller website </FONT> |
| </P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=119> |
| <P><FONT SIZE=2><B>$absBaseURL</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=472> |
| <P><FONT SIZE=2>Absolute base URL for your Roller website.</FONT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=119> |
| <P><FONT SIZE=2><B>$uploadPath</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=472> |
| <P><FONT SIZE=2>The location where uploaded files are placed.</FONT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=119> |
| <P><FONT SIZE=2><B>$user</B></FONT></P> |
| </TD> |
| <TD WIDTH=472> |
| <P><FONT SIZE=2>The current user object for the page/entry |
| being viewed.</FONT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=119> |
| <P><FONT SIZE=2><B>$userName</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=472> |
| <P><FONT SIZE=2>The current user's username.</FONT></P> |
| </TD> |
| </TR> |
| </TABLE> |
| </DL> |
| <P><BR><BR> |
| </P> |
| <DL> |
| <DD> |
| <TABLE WIDTH=608 BORDER=1 CELLPADDING=2 CELLSPACING=3> |
| <COL WIDTH=118> |
| <COL WIDTH=471> |
| <TR> |
| <TD WIDTH=118> |
| <P><FONT SIZE=2><B>$fullName</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=471> |
| <P><FONT SIZE=2>The current user's full name.</FONT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=118> |
| <P><FONT SIZE=2><B>$emailAddress</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=471> |
| <P><FONT SIZE=2>The current user's email address.</FONT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=118> |
| <P><FONT SIZE=2><B>$website</B></FONT></P> |
| </TD> |
| <TD WIDTH=471> |
| <P><FONT SIZE=2>The website for the current user.</FONT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=118> |
| <P><FONT SIZE=2><B>$page</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=471> |
| <P><FONT SIZE=2>The current page being viewed.</FONT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=118> |
| <P><FONT SIZE=2><B>$requestParameters</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=471> |
| <P><FONT SIZE=2>A map of the request parameters </FONT> |
| </P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=118> |
| <P><FONT SIZE=2><B>$rollerVersion</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=471> |
| <P><FONT SIZE=2>Version number of Roller software</FONT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=118> |
| <P><FONT SIZE=2><B>$utilities</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=471> |
| <P><FONT SIZE=2>A utilities object </FONT> |
| </P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=118> |
| <P><FONT SIZE=2><B>$stringUtils</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=471> |
| <P><FONT SIZE=2>A string utilities object</FONT></P> |
| </TD> |
| </TR> |
| </TABLE> |
| </DL> |
| <P><BR><BR> |
| </P> |
| <P>Date formatting variables and objects: |
| </P> |
| <DL> |
| <DD> |
| <TABLE WIDTH=607 BORDER=1 CELLPADDING=2 CELLSPACING=3> |
| <COL WIDTH=120> |
| <COL WIDTH=468> |
| <TR> |
| <TD WIDTH=120> |
| <P><FONT SIZE=2><B>$dateFormatter</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=468> |
| <P><FONT SIZE=2>Date formatter object </FONT> |
| </P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=120> |
| <P><FONT SIZE=2><B>$toStringFormat</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=468> |
| <P><FONT SIZE=2>A date format to be used with the macro |
| formatDate( $dateFormat $date ) :<BR>EEEE MMMM dd, yyyy</FONT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=120> |
| <P><FONT SIZE=2><B>$plainFormat</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=468> |
| <P><FONT SIZE=2>Another date format for use with the |
| formatDate() macro:<BR>yyyyMMdd</FONT></P> |
| </TD> |
| </TR> |
| </TABLE> |
| </DL> |
| <P><BR><BR> |
| </P> |
| <P>If the page is a day page template, then these variables are |
| available too: |
| </P> |
| <DL> |
| <DD> |
| <TABLE WIDTH=608 BORDER=1 CELLPADDING=2 CELLSPACING=3> |
| <COL WIDTH=123> |
| <COL WIDTH=466> |
| <TR> |
| <TD WIDTH=123> |
| <P><FONT SIZE=2><B>$day</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=466> |
| <P><FONT SIZE=2>Date object holding date being displayed</FONT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=123> |
| <P><FONT SIZE=2><B>$entries</B></FONT></P> |
| </TD> |
| <TD WIDTH=466> |
| <P><FONT SIZE=2>Collection of entries for date being displayed</FONT></P> |
| </TD> |
| </TR> |
| </TABLE> |
| </DL> |
| <P><BR><BR> |
| </P> |
| <P>If the page is a comments page, then these variables are |
| available: |
| </P> |
| <DL> |
| <DD> |
| <TABLE WIDTH=607 BORDER=1 CELLPADDING=2 CELLSPACING=3> |
| <COL WIDTH=125> |
| <COL WIDTH=463> |
| <TR> |
| <TD WIDTH=125> |
| <P><FONT SIZE=2><B>$isCommentPage</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=463> |
| <P><FONT SIZE=2>will be set to true</FONT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=125> |
| <P><FONT SIZE=2><B>$entry</B></FONT></P> |
| </TD> |
| <TD WIDTH=463> |
| <P><FONT SIZE=2>weblog entry containing collection of comments</FONT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=125> |
| <P><FONT SIZE=2><B>$autoFormat</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=463> |
| <P><FONT SIZE=2>True if comments should be autoformatted</FONT></P> |
| </TD> |
| </TR> |
| <TR> |
| <TD WIDTH=125> |
| <P><FONT SIZE=2><B>$escapeHtml</B> </FONT> |
| </P> |
| </TD> |
| <TD WIDTH=463> |
| <P><FONT SIZE=2>True if HTML should be escaped </FONT> |
| </P> |
| </TD> |
| </TR> |
| </TABLE> |
| </DL> |
| <P><BR><BR> |
| </P> |
| <H2>5.4 - Creating and packaging your own Roller theme |
| </H2> |
| <P>A Roller theme is, at a minimum, a subdirectory in the Roller |
| <I>themes</I> 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. |
| </P> |
| <P><B>How does Roller create a theme?</B> |
| </P> |
| <P>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: |
| </P> |
| <OL> |
| <LI><P>For each file in the theme's subdirectory that ends with |
| <I>.vm</I> Roller creates a page template with the same name as |
| the file, minus the <I>.vm</I> extension |
| </P> |
| </OL> |
| <OL> |
| <LI><P>The page template that is named <I>Weblog</I> is set to be |
| the website's default page. |
| </P> |
| </OL> |
| <P><B>Including images, Javascript and CSS style sheets in a theme</B> |
| </P> |
| <P>If you want to create a more sophisticated theme, one that takes |
| advantage of the Roller theme macros, you can use the following |
| directory structure for your theme (as illustrated in the x2 |
| theme): |
| </P> |
| <P> |
| </P> |
| <P><SPAN ID="Frame19" DIR="LTR" STYLE="float: left; width: 1.74in; height: 1.31in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m641d153f.png" NAME="graphics27" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 20: Theme directory structure</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P>The page templates go in the root directory of the theme, images |
| in the <I>images</I> directory, Javascript files in the <I>scripts</I> |
| directory, and CSS style sheets in the <I>styles</I> directory. |
| Then, you can make your theme <I>distributable</I> 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: |
| </P> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0in">#showThemeScript( themeName, |
| scriptFileName ) |
| </P> |
| <LI><P STYLE="margin-bottom: 0in">#showThemeScriptPath( themeName |
| ) |
| </P> |
| <LI><P STYLE="margin-bottom: 0in">#showThemeStyleImport( |
| themeName, scriptFileName ) |
| </P> |
| <LI><P>#showThemeStyle( themeName, styleFileName ) |
| </P> |
| </UL> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0in">#showThemeStylePath( themeName, |
| styleFileName ) |
| </P> |
| <LI><P STYLE="margin-bottom: 0in">#showThemeImage( themeName, |
| imageFileName ) |
| </P> |
| <LI><P STYLE="margin-bottom: 0in">#showThemeImagePath( themeName, |
| imageFileName ) |
| </P> |
| <LI><P>#showThemePath( themeName ) |
| </P> |
| </UL> |
| <P><BR><BR> |
| </P> |
| <H2 STYLE="page-break-before: always">5.5 - Overriding Roller |
| Macros |
| </H2> |
| <P>When creating your custom theme, you may find that a Roller |
| macro, such as <TT>#showEntryDate( $day)</TT> does not produce the |
| output that you want. You should first check the Roller Macro |
| Reference<A HREF="http://www.rollerweblogger.org/velocidoc"> </A>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. |
| </P> |
| <P>For example, if you have the following fragment in your <TT>_day</TT> |
| template: |
| </P> |
| <PRE> <div class="entry"> |
| #showDayPermalink( $day ) |
| #showEntryDate( $day ) |
| </div></PRE><P> |
| and you don't like the default output generated by |
| #showEntryDate().</P> |
| <PRE STYLE="margin-bottom: 0.2in"> Thursday January 05, 2006</PRE><P> |
| You can look at the definition of <TT>#showEntryDate</TT> in |
| <TT>weblog.vm</TT>: |
| </P> |
| <PRE> #** |
| * 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</PRE><P> |
| You could then modify the "entry" <TT>div</TT> in your |
| <TT>_day</TT> template as follows: |
| </P> |
| <PRE> <div class="entry"> |
| #showDayPermalink( $day ) |
| #formatDate( "MM/dd/yyyy" $day ) |
| </div> |
| </PRE><P> |
| Now the generated date will look like this: |
| </P> |
| <PRE STYLE="margin-bottom: 0.2in"> 01/05/2006</PRE><P> |
| Warning: This is for advanced users only. If you make an error your |
| web page may not display correctly, or display at all. |
| </P> |
| <P>You can find the source for the various Roller macro <TT>.vm</TT> |
| files in the Roller distribution that matches your installation. |
| Todo: add links to on-line versions of the latest <TT>.vm</TT> |
| files. (?) |
| </P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <H1 CLASS="western" STYLE="page-break-before: always">6 - Managing |
| your weblog's blogroll</H1> |
| <P>Roller makes it easy to maintain a <I>blogroll</I>, that is, a |
| list of your favorite weblogs and web sites that is displayed in |
| the sidebar of your weblog. |
| </P> |
| <H2>6.1 - Adding new links to your blogroll</H2> |
| <P><SPAN STYLE="font-weight: medium">Individual blogroll items are |
| known as <I>bookmarks</I>. </SPAN>Use the <B>Create & |
| Edit:Bookmarks</B> page to add, edit and delete bookmarks and |
| bookmark folders in your blogroll. |
| </P> |
| <P><SPAN ID="Frame20" DIR="LTR" STYLE="float: left; width: 5.73in; height: 5.07in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m1965909a.png" NAME="graphics33" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 21: Bookmarks management page</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P STYLE="margin-bottom: 0in">Here are some notes about the |
| bookmarks page:</P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0in">The Add bookmark link takes you |
| to the Add bookmark form, see below.</P> |
| <LI><P STYLE="margin-bottom: 0in">The Add folder link talks you to |
| the Add folder form, see below.</P> |
| <LI><P STYLE="margin-bottom: 0in">The check-box allows you to |
| select a bookmark for deletion or for moving to another folder.</P> |
| <LI><P STYLE="margin-bottom: 0in">The Edit icon allows you to edit |
| a bookmark using the Edit bookmark form, see below.</P> |
| <LI><P STYLE="margin-bottom: 0in">The Visit icon allows you to |
| visit the link.</P> |
| </UL> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <H2><B>6.2 - Adding new links to your blogroll</B></H2> |
| <P STYLE="margin-bottom: 0in">The Add/Edit bookmark form, shown |
| below, allows you to enter information about one bookmark.</P> |
| <P STYLE="margin-bottom: 0in">Here's an explanation of the fields:</P> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0in"><SPAN ID="Frame23" DIR="LTR" STYLE="float: left; width: 79%; height: 255%; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m5f34e5af.png" NAME="graphics35" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 22: Add and edit bookmark form</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT>Name: Text to be displayed on the link |
| </P> |
| </UL> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0in">Description: Description, |
| displayed when viewer hovers over link</P> |
| <LI><P STYLE="margin-bottom: 0in">Bookmark URL: The URL of the |
| bookmark</P> |
| <LI><P STYLE="margin-bottom: 0in">Newsfeed URL: The URL of the |
| newsfeed associated with the bookmark (if any)</P> |
| <LI><P STYLE="margin-bottom: 0in">Sort priority: Lower numbered |
| bookmarks displayed first in blogroll</P> |
| <LI><P STYLE="margin-bottom: 0in">Display weight: Higher numbered |
| bookmarks displayed bolder/larger</P> |
| </UL> |
| <H2 STYLE="page-break-before: always">6.3 - Adding new bookmark |
| folders</H2> |
| <P>If you'd like to display a separate list of links somewhere on |
| your weblog, or you'd like to store links in Roller for some other |
| reason, you can use the Add folder form, shown below, to do that.</P> |
| <P><BR><BR> |
| </P> |
| <P><SPAN ID="Frame21" DIR="LTR" STYLE="float: left; width: 5.48in; height: 2.78in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_f21d9b9.png" NAME="graphics34" ALIGN=LEFT WIDTH=99% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 23: Add folder form</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P STYLE="margin-bottom: 0in"><B>Displaying new bookmark folders</B></P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P>You can use the <B>#showBookmarks()</B> 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 <I>String |
| folderName</I>, <I>boolean showFolderName</I>, and <I>boolean |
| expandingFolder</I>. 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. |
| </P> |
| <P>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: |
| </P> |
| <PRE STYLE="margin-left: 0.49in">... |
| <html> |
| <head> |
| <title>My badass blog</title> |
| <script type="text/javascript" src="/theme/scripts/roller.js"></script> |
| </head> |
| <body> |
| ...</PRE><P STYLE="margin-left: -0.01in"> |
| Later in your page, include the <B>#showBookmarks</B> macro to |
| display your bookmarks: |
| </P> |
| <PRE STYLE="margin-left: 0.49in">... |
| #showBookmarks( "News" true true ) |
| ...</PRE><P STYLE="margin-bottom: 0in"> |
| <BR> |
| </P> |
| <H2 STYLE="page-break-before: always">6.4 - Bookmark import and |
| export via OPML</H2> |
| <P>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. |
| </P> |
| <P><I>How to import OPML into Roller</I></P> |
| <OL> |
| <LI><P STYLE="margin-bottom: 0in">download bookmarks in OPML |
| format from a site such as Scripting.COM and save them as a file |
| on your hard disk. |
| </P> |
| <LI><P STYLE="margin-bottom: 0in">Login to Roller and choose the |
| Bookmarks:Import menu option. |
| </P> |
| <LI><P>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. |
| </P> |
| </OL> |
| <P><I>How to export OPML from Roller</I></P> |
| <P STYLE="font-style: normal">Your bookmarks are automatically made |
| available in OPML form via a URL of the form:</P> |
| <P STYLE="font-style: normal"> http://<I>serverhostname</I>/flavor/<I>webloghandle</I>?flavor=opml</P> |
| <P>You can also export one specific folder by using the path |
| paramter. For example, if you have a folder called Solaris, export |
| it like so:</P> |
| <P> http://<I>serverhostname</I>/flavor/<I>webloghandle</I>?flavor=opml&path=/Solaris |
| </P> |
| <P><I><B>NOTE:</B> For OPML export, Roller bookmarks must have at |
| least a name and an HTML url; the name is taken from the text |
| attribute (or if that is absent, the title attribute) of the OPML |
| element, and the HTML url is taken from the htmlUrl attribute (or |
| if that is absent, the url attribute) of the OPML element; if this |
| forms a bookmark lacking a name or HTML URL then that entry will be |
| silently skipped during import. </I> |
| </P> |
| <H1 CLASS="western" STYLE="page-break-before: always">7 - Using a |
| blog client with Roller |
| </H1> |
| <P>A blog client allows you to post to Roller remotely, from your |
| desktop or from some other web site. For example, desktop |
| applications such as Ecto and MarsEdit can post to Roller and so |
| can the photo-sharing web site Flickr.com. This is possible because |
| Roller supports the standard Blogger and MetaWeblog APIs. |
| </P> |
| <P><B>Configuring a blog client for use with Roller</B></P> |
| <P>First, make sure to enable Blogger API support in your weblog |
| via the <B>Preferences:Settings</B> page. Next, start your blogging |
| client, find the preferences or account setup dialog. You'll need |
| to set the following parameters:</P> |
| <P> Username: your Roller username</P> |
| <P> Password: your Roller password</P> |
| <P> BlogID: the handle of your Roller weblog</P> |
| <P> URL: the URL of Roller's XML-RPC endpoint</P> |
| <P STYLE="font-weight: medium">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. |
| </P> |
| <P><B>A blogs.sun.com example</B></P> |
| <P>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 <I>http://blogs.sun.com/roller/fredsblog</I>), then |
| your paramters would be:</P> |
| <P> Username: fred</P> |
| <P> Password: (your password)</P> |
| <P> BlogID: fredsblog</P> |
| <P> URL: http://blogs.sun.com/roller/xmlrpc |
| </P> |
| <P>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. |
| </P> |
| <P><B>A jroller.com example</B></P> |
| <P>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 |
| <I>http://jroller.com/fredsblog</I>), then your paramters would be:</P> |
| <P> Username: fred</P> |
| <P> Password: (your password)</P> |
| <P> BlogID: fredsblog</P> |
| <P> URL: http://jroller.com/xmlrpc |
| </P> |
| <P><BR><BR> |
| </P> |
| <H1 CLASS="western" STYLE="page-break-before: always">8 - Using |
| weblog pings</H1> |
| <P>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. |
| </P> |
| <P>Roller supports conventional XML-RPC weblog update ping |
| mechanism used by many sites for such notifications. |
| </P> |
| <H2>8.1 - Registering with an Aggregator</H2> |
| <P>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. |
| </P> |
| <P>Aggegation sites that accept ping notifications generally |
| publish the ping URL to use to ping their site on their |
| (human-readable) web site. Once you have registered your site with |
| an aggregator, you can set up your weblog to deliver pings to that |
| site. |
| </P> |
| <H2>8.2 - Ping Targets, Common and Custom</H2> |
| <P>You can set up the Roller server to ping sites of your choice |
| automatically whenever you post published updates to your weblog. |
| </P> |
| <P>Roller uses the term <B>ping target</B> 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: |
| </P> |
| <DL> |
| <DT><B>common ping targets</B></DT><DD STYLE="margin-bottom: 0.2in"> |
| 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. |
| </DD><DT> |
| <B>custom ping targets</B></DT><DD STYLE="margin-bottom: 0.2in"> |
| 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. |
| </DD></DL> |
| <H2> |
| 8.3 - Setting up Automated Pings</H2> |
| <P>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 <B>Weblog:Pings</B> page (shown below) to enable |
| automatic pings and send manual pings. |
| </P> |
| <P> |
| </P> |
| <P><SPAN ID="Frame24" DIR="LTR" STYLE="float: left; width: 6.45in; height: 5.49in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m31cb7c1f.png" NAME="graphics40" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 24: Automatic ping configuration page</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P><BR><BR> |
| </P> |
| <P>To enable automatic pings to a ping target, find the ping target |
| on the page and click the <B>Enable</B> link in the Automatic |
| column. The status indicator turns to <B>ON</B> and the link |
| changes to <B>Disable</B> (as shown for some sites in the |
| screenshot above). To disable automatic pings to a ping target |
| click the <B>Disable</B> link in the Automatic column. The status |
| indicator turns to <B>OFF</B> and the link changes to <B>Enable</B>. |
| </P> |
| <P>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 |
| </P> |
| <P>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. |
| </P> |
| <P STYLE="margin-left: 0.5in"><I><B>Note:</B> 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.</I> |
| </P> |
| <P><BR><BR> |
| </P> |
| <H2>8.4 - Sending a Manual Ping</H2> |
| <P>You can also send a manual ping to a ping target using the <B>Send |
| Ping Now</B> link listed for the target on the <B>Weblog:Pings</B> |
| 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. |
| </P> |
| <P>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. |
| </P> |
| <P>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. |
| </P> |
| <H2>8.5 - Creating and Editing Custom Ping Targets</H2> |
| <P>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 <A HREF="http://www.rollerweblogger.org/wiki/Wiki.jsp?page=UserGuide_2.x#ref-UserGuide_2.x-21">[21]</A>); |
| 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 <B>Weblog:Custom Ping Targets</B> |
| page. |
| </P> |
| <P STYLE="margin-left: 0.49in"><I><B>Note:</B> Custom ping targets |
| are a feature that the administrator can disable. If you do not see |
| <B>Weblog:Custom Ping Targets</B> menu item, or any heading for |
| Custom Ping Targets on the <B>Weblog:Pings</B> page, then an |
| administrator has disabled it, and you will need to contact an |
| administrator to get a new common ping target added.</I> |
| </P> |
| <P>Before adding a custom ping target, you must determine the |
| proper ping URL for the site that you wish to ping. You must get |
| this information from the aggregator's web site or from another |
| knowledgeable source. |
| </P> |
| <P>It can be hard to find the aggregator's documentation telling |
| you the specific ping URL to use to notify their site. Commonly |
| aggregators list this on their web site under a topic providing |
| help about registering your feed, or under a topic providing |
| information for developers. Keep in mind that some aggregators only |
| use periodic polling and do not accept ping notifications at all. |
| If you can't find any information about pinging on the aggregator's |
| web site, the site may not support pinging. |
| </P> |
| <P>Once you have found the proper ping URL, you can add your custom |
| target using the <B>Weblog:Custom Ping Targets</B> page, which |
| looks something like the following screen-shot. |
| </P> |
| <P> |
| </P> |
| <P><BR><BR> |
| </P> |
| <P><BR><BR> |
| </P> |
| <P><SPAN ID="Frame25" DIR="LTR" STYLE="float: left; width: 6.44in; height: 3.25in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_5393469f.png" NAME="graphics45" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 25: Custom ping targets page</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P><BR><BR> |
| </P> |
| <P>Click the <B>Add New</B> button to add a new custom ping target. |
| This will bring up a form with a <B>Name</B> field and a <B>Ping |
| URL</B> field. Fill in both fields, and click the <B>Save</B> |
| button. |
| </P> |
| <P><SPAN ID="Frame26" DIR="LTR" STYLE="float: left; width: 5.17in; height: 1.89in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m600d3053.png" NAME="graphics46" ALIGN=LEFT WIDTH=88% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 26: Edit ping target form</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P>Once you have created a custom ping target, you will see it |
| listed on the <B>Weblog:Custom Ping Targets</B> 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 |
| <B>Weblog:Pings</B> page. |
| </P> |
| <P><BR><BR> |
| </P> |
| <P>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 <B>Save</B> will fail, and you will get an error |
| indication telling you what was wrong with your entry</P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <H2 STYLE="page-break-before: always">8.6 - More on Registering |
| with an Aggregator</H2> |
| <P>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. |
| </P> |
| <P>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 |
| <TT>page</TT>/<I>handlenamehere</I>). |
| </P> |
| <P>The RSS feed URL for your whole feed can be obtained by |
| substituting <TT>page</TT> in your weblog's URL with <TT>RSS</TT>. |
| 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. |
| </P> |
| <P>You also have category-specific feeds, which are useful for |
| registering with topical aggregators like <B>java.blogs</B>. To get |
| a category-specific feed URL, just append <TT>?catname=</TT><I>/category/path</I> |
| where <I>/category/path</I> 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. |
| </P> |
| <P>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. |
| </P> |
| <P><BR><BR> |
| </P> |
| <DIV ID="Section1" DIR="LTR"> |
| <DIV ID="Section3" DIR="LTR"> |
| <H1 CLASS="western" STYLE="page-break-before: always">9 - Roller |
| administration</H1> |
| <P>The 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 <B>Global Admin->User Admin</B> page, |
| which just happens to be the first topic we'll cover in the |
| section.</P> |
| <P>We'll also describe how to configure Roller via the <B>Global |
| Admin->Configuration </B>page and how to configure Roller's |
| custom ping facility via the <B>Global Admin->Ping Targets</B> |
| page.</P> |
| <H2>9.1 - Managing users</H2> |
| <P>The <B>Global Admin->User Admin</B> page, shown below, |
| allows you to find users, edit users and create new users. |
| </P> |
| <P> |
| </P> |
| <P><SPAN ID="Frame22" DIR="LTR" STYLE="float: left; width: 6.48in; height: 4.17in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m4b577c06.png" NAME="graphics12" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 27: User admin page</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P>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.</P> |
| <P>You can also create a new user by clicking the <B>create a new |
| user link</B>.</P> |
| <P><BR><BR> |
| </P> |
| <P>When a user is loaded into the <B>Global Admin->User Admin</B> |
| 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.</P> |
| <P><BR><BR> |
| </P> |
| <P STYLE="margin-bottom: 0in"><SPAN ID="Frame9" DIR="LTR" STYLE="float: left; width: 6.56in; height: 5.51in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m54dbe4ad.png" NAME="graphics18" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 28: User admin form</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR> |
| </P> |
| <P STYLE="margin-bottom: 0in">You can also <SPAN STYLE="font-weight: medium">disable |
| a user</SPAN>, which will prevent the user from logging into |
| Roller.</P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P STYLE="margin-bottom: 0in">Or you can check the Administrator |
| checkbox to grant grant the user Global Admin privileges.</P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P STYLE="margin-bottom: 0in">At the bottom of the page, there's |
| a <B>Users Weblogs</B> 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.</P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P STYLE="margin-bottom: 0in"><B>There's one important |
| limitation: currently there is currently no way to delete a user.</B></P> |
| <H2 STYLE="page-break-before: always">9.2 - Configuring Roller</H2> |
| <P>The <B>Global Admin->Configuration</B> page allows you to |
| set Roller's runtime configuration properties. It is a big page, |
| so we will discuss each section separately below. |
| </P> |
| <P> |
| </P> |
| <P><SPAN ID="Frame29" DIR="LTR" STYLE="float: left; width: 6.44in; height: 2.3in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m4fe3f61b.png" NAME="graphics20" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 29: Config page: site settings</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0in"><B>Site name</B>: name of the |
| site, to be included in site-wide newsfeeds (RSS and Atom) and |
| on the default front page of the Roller.</P> |
| <LI><P STYLE="margin-bottom: 0in"><B>Short name</B>: 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.</P> |
| <LI><P STYLE="margin-bottom: 0in"><B>Site description</B>: |
| description of site, to be included in site-wide newsfeeds (RSS |
| and Atom) and on the default front page of the site.</P> |
| <LI><P STYLE="margin-bottom: 0in"><B>Site Administrator's email |
| Address</B>: admin's email address, to be include in side-side |
| newsfeeds (RSS and Atom)</P> |
| <LI><P STYLE="margin-bottom: 0in"><B>Absolute URL to this site</B>: |
| to be used as basis for creating absolute URLs. Required for |
| Roller's Planet aggregator feature.</P> |
| <LI><P STYLE="margin-bottom: 0in"><B>Suspend all ping |
| processing</B>: Allows you to turn off all (outgoing) weblogs |
| pings for all weblogs in the system.</P> |
| <LI><P STYLE="margin-bottom: 0in"><B>Enable debug mode</B>: |
| currently not used.</P> |
| <P></P> |
| </UL> |
| <P><SPAN ID="Frame30" DIR="LTR" STYLE="float: left; width: 6.49in; height: 1.86in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m3a18f583.png" NAME="graphics23" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 30: Config page: user settings</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT> |
| </P> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0in"><B>Allow New Users</B>: Set |
| this to enable the <I>register as new user</I> link on the main |
| page. If you turnoff user creation, you'll only be able to |
| create new users via the <B>Global Admin->User Admin</B> |
| page.</P> |
| <LI><P STYLE="margin-bottom: 0in"><B>External registration URL</B>: |
| 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. |
| </P> |
| <LI><P STYLE="margin-bottom: 0in"><B>Editor pages</B>: this is |
| the list of weblog editors to be provided to users.</P> |
| </UL> |
| <P><BR><BR> |
| </P> |
| <P><SPAN ID="Frame37" DIR="LTR" STYLE="float: left; width: 6.33in; height: 2.4in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_6aedbe24.png" NAME="graphics39" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 31: Config: comments</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <UL> |
| <LI><P><B>Allow weblog comments</B>: By un-setting this you can |
| turn off weblog comments on all weblogs in the system.</P> |
| <LI><P><B>Allow trackbacks</B>: By un-setting this you can turn |
| off incoming trackbacks on all weblogs in the system.</P> |
| <LI><P><B>Autoformat comments</B>: If this is on, Roller will |
| auto-format comments by adding in line-breaks where appropriate.</P> |
| <LI><P><B>Escape comment HTML</B>: By setting this, you can |
| disallow HTML in comments and thereby protect your site from |
| malicious JavaScript and some forms of cross-site scripting.</P> |
| <LI><P><B>E-mail notification of comments</B>: 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.</P> |
| <LI><P><B>Enable verification of trackback links</B>: Trackback |
| verification checks each incoming trackback to verify that the |
| site sending the trackback actually links to the specific weblog |
| entry that is the target of the trackback.</P> |
| <LI><P><B>Enable referrer linkback extraction</B>: NOT |
| RECOMMENDED. This is an experimental feature and it is not known |
| to be working correctly.</P> |
| </UL> |
| <P><BR><BR> |
| </P> |
| <P><SPAN ID="Frame31" DIR="LTR" STYLE="float: left; width: 6.38in; height: 1.94in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m5eead6e8.png" NAME="graphics24" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 32: Config page: file upload settings</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0in"><B>Enable File Uploads</B>: |
| Are users allowed to upload files? |
| </P> |
| <LI><P STYLE="margin-bottom: 0in"><B>Allowed Extensions</B>: |
| Comma-separated list of file extensions that users are allowed |
| to upload. |
| </P> |
| <LI><P STYLE="margin-bottom: 0in"><B>Forbidden Extensions</B>: |
| Comma-separated list of file extensions that users are NOT |
| allowed to upload. |
| </P> |
| <LI><P STYLE="margin-bottom: 0in"><B>Max File Size (MB)</B>: |
| Maximum size of file that users are allowed to upload. |
| </P> |
| <LI><P STYLE="margin-bottom: 0in"><B>Max Directory Size (MB)</B>: |
| Total upload directory size per user. |
| </P> |
| <P STYLE="margin-bottom: 0in"></P> |
| </UL> |
| <P> |
| </P> |
| <P><SPAN ID="Frame32" DIR="LTR" STYLE="float: left; width: 6.43in; height: 1.2in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m6046b9c9.png" NAME="graphics25" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 33: Config page: newsfeed settings</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <UL> |
| <LI><P STYLE="margin-bottom: 0in"><B>Default number of entries</B>: |
| default number of entries to appear in each newsfeed (RSS and |
| Atom).</P> |
| <LI><P STYLE="margin-bottom: 0in"><B>Maximum number of entries</B>: |
| maximum number of entries to be allowed in each newsfeed (RSS |
| and Atom).</P> |
| </UL> |
| <H1 CLASS="western" STYLE="page-break-before: always">10 - Weblog |
| update ping administration</H1> |
| <P>This section, intended for Roller administrators, describes |
| how Roller weblog update ping feature works and how to configure |
| and administer it.</P> |
| <H2>10.1 - Creating and editing common ping targets</H2> |
| <P>Common ping targets are ping targets that are shared by all |
| users. You can create and edit common ping targets using the |
| <B>Global Admin->Ping Targets</B> page. |
| </P> |
| <P><BR><BR> |
| </P> |
| <P><SPAN ID="Frame33" DIR="LTR" STYLE="float: left; width: 6.39in; height: 3.53in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_mf310db2.png" NAME="graphics28" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 34: Common weblog ping targets</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P>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. |
| </P> |
| <P>Administrators should make sure to test new common ping |
| targets after creating them. |
| </P> |
| <H2>10.2 - How Roller Processes Weblog Update Pings</H2> |
| <P>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. |
| </P> |
| <P>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. |
| </P> |
| <P>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 |
| <B>Preferences->Pings</B> page, as well as a failure policy to |
| deactivate persistently failing ping targets). |
| </P> |
| <H2>10.3 - Configuration Properties Controlling Ping Processing</H2> |
| <P>These properties control processing of the ping queue. They |
| are configured in the <TT><FONT FACE="Courier New">roller.properties</FONT></TT><FONT FACE="Courier New"> |
| </FONT>file. |
| </P> |
| <DL> |
| <DD STYLE="margin-left: 0.49in; margin-bottom: 0.2in"><FONT SIZE=2 STYLE="font-size: 11pt"><B>pings.queueProcessingIntervalMins |
| </B>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. <B>IMPORTANT</B>: 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. <B>Make sure to retain one host in the |
| cluster that does process the ping queue!</B> 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. </FONT> |
| </DD><DD STYLE="margin-left: 0.49in; margin-bottom: 0.2in"> |
| <FONT SIZE=2 STYLE="font-size: 11pt"><B>pings.maxPingAttempts |
| </B>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. </FONT> |
| </DD></DL> |
| <H2> |
| 10.4 - Suspending all ping processing</H2> |
| <P>Administrators can suspend all ping processing at runtime by |
| checking the <B>Suspend ping processing?</B> checkbox under the |
| <B>Site Settings</B> heading on the <B>Global |
| Admin->Configuration</B> page and saving that form. |
| </P> |
| <P>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. |
| </P> |
| <P>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. |
| </P> |
| <H2>10.5 - Controlling and disabling ping usage</H2> |
| <P>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. |
| </P> |
| <DL> |
| <DD STYLE="margin-left: 0.49in; margin-bottom: 0.2in"><FONT SIZE=2 STYLE="font-size: 11pt"><B>pings.disallowCustomTargets. |
| </B>This property controls whether users are allowed to create |
| custom ping targets. If set to true, all existing custom ping |
| targets are <I>removed</I>, and the <B>Weblog:Custom Ping |
| Targets</B> page and the associated actions are disabled |
| preventing any configuration of custom ping targets. <B>Note:</B> |
| <I>Setting this to true this will cause the Roller server to |
| </I>remove <I>any custom ping targets that users have created |
| when Roller is next started.</I> </FONT> |
| </DD></DL> |
| <P> |
| 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. |
| </P> |
| <DL> |
| <DD STYLE="margin-left: 0.49in; margin-bottom: 0.2in"><FONT SIZE=2 STYLE="font-size: 11pt"><B>pings.disablePingUsage. |
| </B>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 <B>Preferences->Pings</B> page and associated |
| actions are disabled, preventing any use of the ping features by |
| regular users. <B>Note:</B> <I>Setting this to true will cause |
| the Roller server to </I>remove <I>any autopings that users have |
| configured when Roller is next started.</I> </FONT> |
| </DD></DL> |
| <P> |
| If both of the above properties are set to true, all ping |
| functionality is effectively disabled for regular users. The |
| <B>Global Admin:Ping Targets</B> 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. |
| </P> |
| <H2>10.6 - Initialization of common ping targets</H2> |
| <P>The initial set of common ping targets is determined by the |
| following configuration property. |
| </P> |
| <DL> |
| <DD STYLE="margin-left: 0.49in; margin-bottom: 0.2in"><FONT SIZE=2 STYLE="font-size: 11pt"><B>pings.initialCommonTargets. |
| </B>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 </FONT> |
| </DD></DL> |
| <PRE STYLE="margin-bottom: 0.2in"> <FONT SIZE=2 STYLE="font-size: 11pt">{{name}{url}}</FONT></PRE> |
| <DL> |
| <DD STYLE="margin-bottom: 0.2in"> |
| <FONT SIZE=2 STYLE="font-size: 11pt">This value is used every |
| time Roller starts <I>and finds an empty list of common ping |
| targets.</I> 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. </FONT> |
| </DD><DD STYLE="margin-left: 0in; margin-bottom: 0.2in"> |
| <BR><BR> |
| </DD></DL> |
| <H1 CLASS="western" STYLE="page-break-before: always"> |
| 11 - Planet Roller administration |
| </H1> |
| <P>This page describes the new Planet Roller feature. This |
| feature is disabled by default. You can enable it by overriding |
| the <TT>planet.aggregator.enabled </TT>(the Installation Guide |
| for details). |
| </P> |
| <P>This new feature allows a you to add separately hosted blogs |
| to a Planet tab on the Roller front-page. Separately hosted blogs |
| can be running on any type of blog server, as long as it supports |
| RSS 0.93 or later and has item-level publication dates. |
| </P> |
| <H2>11.1 - Setting up the Planet aggregator</H2> |
| <P>Before you can configure and use the Planet aggregator, you |
| must set it up. (this material will be moved into the |
| installation guide in a future release). Here are the three |
| steps:</P> |
| <P><B>STEP1: Enable the Planet aggregator </B> |
| </P> |
| <P>Set <FONT FACE="Courier New">planet.aggregator.enabled=true</FONT> |
| in your Roller properties override file.</P> |
| <P>Enter a valid cache directory in the |
| <FONT FACE="Courier New">planet.aggregator.cache.dir</FONT> |
| property of your Roller properties override file. Make sure the |
| cache directory exists and is writable by the user who owns the |
| Roller process.</P> |
| <P><B>STEP 2: Setup the refresh-entries task</B></P> |
| <P>The RefreshEntriesTask is responsible for updating each of the |
| blogs in the Planet aggregator. You should set it up to run every |
| hour. There are two ways to do this. You can add it to the list |
| of hourly tasks run by Roller's built-in scheduler by adding the |
| following to your Roller properties override file:</P> |
| <P> <FONT FACE="Courier New"><FONT SIZE=2># Comma separated |
| list of task classnames to be executed hourly</FONT></FONT></P> |
| <P> |
| <FONT FACE="Courier New"><FONT SIZE=2>tasks.hourly=org.roller.presentation.planet.RefreshEntriesTask</FONT></FONT></P> |
| <P>However, some folks have found that the RefreshEntriesTask can |
| works best when run outside of Roller. If you want to do that |
| instead, you can use cron on UNIX or Windows Task scheduler to |
| run the task. For UNIX users, use the rollertask.sh script which |
| can be found in the Roller install directory under docs/examples. |
| You'll have to modify it to set your paths and your JDBC driver |
| jar.</P> |
| <P><B>STEP 3: Setup the sync-websites task</B></P> |
| <P>The SyncWebsitesTask ensures that every blog in the Roller |
| system is included in the Planet aggregator. It is intended to |
| run every night. Every time that it runs, it adds all new blogs |
| and removes all blogs that no longer exist. If you have a valid |
| technorati.license file your classpath, it will also rank the |
| blogs in the system using the Techorati system. To setup |
| sync-websites, add the following to your Roller propeties |
| override file.</P> |
| <P> <FONT FACE="Courier New"><FONT SIZE=2># Daily Planet task: |
| syncs weblog list with Roller, refreshes Technorati stats</FONT></FONT></P> |
| <P> <FONT FACE="Courier New"><FONT SIZE=2>tasks.daily=org.roller.presentation.planet.SyncWebsitesTask</FONT></FONT></P> |
| <P>As with the refresh-entries tasks, some have found that |
| sync-websites runs best outside of Roller. You can run it from |
| cron or Windows Task Scheduler too. And again, UNIX users can use |
| <FONT SIZE=2 STYLE="font-size: 10pt"><FONT FACE="Courier New">rollertask.sh</FONT></FONT> |
| to do this.</P> |
| <P><B>How do you get a Technorati license in your classpath? </B>You |
| can get an API key from the Technorati Developer Center. Place |
| the API key in a file (which no whitespace) named |
| <FONT FACE="Courier New">technorati.license</FONT> and place that |
| license in the <FONT FACE="Courier New">WEB-INF/classes</FONT> |
| directory of your Roller install.</P> |
| <H2><A NAME="section-AdministrationGuide_120-ConfiguringPlanetRoller"></A> |
| 11.2 - Configuring Planet Roller</H2> |
| <P>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 <B>Planet Admin->Configuraiton</B> |
| page, shown below.</P> |
| <P><SPAN ID="Frame34" DIR="LTR" STYLE="float: left; width: 6.48in; height: 3.71in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_62ac32cd.png" NAME="graphics36" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 35: Planet config page</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P><A NAME="section-AdministrationGuide_120-ToConfigurePlanetRollerYouMust"></A> |
| <B>To configure Planet Roller, you must:</B></P> |
| <UL> |
| <LI><P>Ensure that your site has an absolute URL in the <B>Global |
| Admin->Configuration</B> page in the Site Settings section. |
| </P> |
| </UL> |
| <UL> |
| <LI><P>If you are behind a proxy, you must enter proxy settings |
| in the <B>Planet Admin->Configuration</B> page. |
| </P> |
| </UL> |
| <P STYLE="margin-bottom: 0in"><A NAME="section-AdministrationGuide_120-ThePlanetControlButtons"></A> |
| <B>The Planet Control buttons</B></P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P>The buttons at the bottom of the <B>Planet |
| Admin->Configuration</B> page can be used to kick off the |
| Planet Roller background tasks. Normally, these tasks will run on |
| a schedule and you will not have to touch these buttons. If you |
| are doing testing, you might need to use them to diagnose |
| problems -- so we've left them in the interface. |
| </P> |
| <UL> |
| <LI><P><B>Refresh Entries</B>: this button will launch the |
| Refresh Entries task which updates every newsfeed in the system. |
| Normally this runs every hour. It can take several minutes to |
| complete and the only way to know that it is done is to watch |
| the log files (and have INFO level debugging turned on for the |
| <FONT FACE="Courier New">RefreshEntriesTask</FONT> class). |
| </P> |
| </UL> |
| <UL> |
| <LI><P><B>Synchronize Websites</B>: this button will launch the |
| Synchronize Websites tasks which ensures that every Roller |
| website (i.e. blog) in the system is represented by a |
| subscription in Planet Roller. If any websites have been deleted |
| from the system, the the task will delete the corresponding |
| subscription. |
| </P> |
| </UL> |
| <H2><A NAME="section-AdministrationGuide_120-AddingExternalSubscriptionsToPlanetRoller"></A> |
| 11.3 - Adding external subscriptions to Planet Roller</H2> |
| <P>By default, Planet will include all of the blogs in the Roller |
| site. But the purpose of Planet is to allow externally hosted |
| blogs to be included on the front page.</P> |
| <P STYLE="margin-bottom: 0in"><B>Adding and removing external |
| blogs</B></P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P>To add an externally hosted blog to the Planet, use the <B>Planet |
| Admin->Subscriptions</B> page. To add a blog, enter it's |
| title, newsfeed URL and website URL. Normally, you must enter all |
| three field, but if you have a Technorati license in your |
| classpath you might be able to enter only the website URL and let |
| Roller figure out the rest (by using Technorati).</P> |
| <P>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. |
| </P> |
| <P>Note that 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 it's entries are one day old.</P> |
| <P><SPAN ID="Frame35" DIR="LTR" STYLE="float: left; width: 6.3in; height: 4.51in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_4879cc9c.png" NAME="graphics38" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 36: Planet subscriptions page</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR><BR> |
| </P> |
| <P><BR><BR> |
| </P> |
| <H2><A NAME="section-AdministrationGuide_120-ThePlanetRollerMainPage"></A> |
| 11.4 - The Planet Roller main page</H2> |
| <P>The Planet Roller main page is shown below.</P> |
| <P STYLE="margin-bottom: 0in"><SPAN ID="Frame36" DIR="LTR" STYLE="float: left; width: 6.42in; height: 4.75in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m6732908.png" NAME="graphics37" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 37: Planet front page</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR> |
| </P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P STYLE="margin-bottom: 0in"><A NAME="section-AdministrationGuide_120-RSSNewsfeed"></A> |
| <B>The planet newsfeeds</B></P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P STYLE="margin-bottom: 0in">Planet provides a newsfeed that |
| included posts from all blogs in the aggregator. You can get this |
| feed at the path /planetrss, so for example, for a default Roller |
| install the newsfeed URL would be:</P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P STYLE="margin-bottom: 0in"> |
| <FONT FACE="Courier New">http://localhost:8080/roller/planetrss</FONT></P> |
| <P><BR><BR> |
| </P> |
| <P><A NAME="section-AdministrationGuide_120-TechnoratiRankings"></A> |
| <B>Technorati Rankings</B></P> |
| <P>Because we cannot get hit counts for the external blogs in the |
| system, Planet Roller displays Technorati Rankings for all blogs |
| in the system instead. This only works right if you have a valid |
| Technorati license in your classpath.</P> |
| <P><BR><BR> |
| </P> |
| <H2 STYLE="page-break-before: always">11.5 - Adding custom groups |
| to Planet</H2> |
| <P STYLE="margin-bottom: 0in">You can also add custom aggregation |
| groups to planet. Just use the <B>Planet AdminCustom Groups</B> |
| page, shown below.</P> |
| <P><BR><BR> |
| </P> |
| <P STYLE="margin-bottom: 0in"><SPAN ID="Frame38" DIR="LTR" STYLE="float: left; width: 6.39in; height: 4.27in; border: none; padding: 0in; background: #ffffff"> |
| <P STYLE="margin-top: 0.08in"><IMG SRC="roller-user-guide_html_m5327a1d1.png" NAME="graphics41" ALIGN=LEFT WIDTH=100% BORDER=0><BR CLEAR=LEFT><FONT SIZE=2><I>Illustration |
| 38: Planet custom groups page</I></FONT></P> |
| </SPAN><BR CLEAR=LEFT><BR> |
| </P> |
| <P>In the custom groups page shown above, you can see four custom |
| groups. Each of these groups has a set of subscriptions. |
| Currently, these custom groups are NOT displayed on the Planet |
| page. Someday we'd like to enable that, but for now they only way |
| to display those groups on the Planet page is to customize the |
| Java ServerPages (JSP) code that defines that page.</P> |
| <P>Custom groups aren't displayed on the Planet page, but they |
| are available in newsfeed form. So if you define groups named |
| “mygroup1” and “mygroup2” you'll find |
| that you have two new newsfeeds. For example:</P> |
| <P STYLE="margin-bottom: 0in"> |
| <FONT SIZE=2 STYLE="font-size: 11pt"><FONT FACE="Courier New">http://localhost:8080/roller/planetrss?group=mygroup1</FONT></FONT></P> |
| <P STYLE="margin-bottom: 0in"> |
| <FONT SIZE=2 STYLE="font-size: 11pt"><FONT FACE="Courier New">http://localhost:8080/roller/planetrss?group=mygroup2</FONT></FONT></P> |
| <P STYLE="margin-bottom: 0in"><BR> |
| </P> |
| <P STYLE="margin-bottom: 0in">And that brings us to the end of |
| the Planet section and the end of the Roller user guide.</P> |
| </DIV> |
| </DIV> |
| </DIV> |
| </DIV> |
| </BODY> |
| </HTML> |