!!!The Roller Weblogger User Guide v0.9.7 See also: InstallationGuide Orignal text is ''Copyright © 2003 David M Johnson'' * [1] Introduction * [2] Getting started ** QuickStartGuide ** The Roller Web Application ** Roller Navigation Bars ** The Roller Editor UI * [3] Managing your Weblog ** Adding a New Weblog Post ** Working with Old Weblog Posts ** Working with Weblog Comments ** Sending Trackbacks ** Weblog Categories ** Referer Rankings ** Flushing the Cache * [4] Customizing your Website ** Website Settings ** Website Themes ** Uploading Files * [5] Customizing your theme with Roller Macros ** [5.1|51] Weblog and day pages ** [5.2|52] Other pages and comments ** [5.3|53] Roller Macros and Variables ** [5.4|54] Creating and packaging your own Roller theme * [6] Using Roller for Bookmark and Blogroll Management ** Adding new bookmark folders ** Adding bookmarks to folders ** Editing a bookmark ** Displaying your bookmarks ** Importing OPML via the Bookmarks:Import Page * [7] Using Roller for Display of RSS Newsfeeds ** Newsfeeds:Subscriptions Page ** Newsfeeds:View All Page ** Newsfeed Display Macros * [8] Using a Blogging Client with Roller ** Configuring w:bloggar * [9] Configuration and Administration of Roller ** The Website:Admin Page ** The Website:Config Page \\ \\ !!![#1] Introduction Roller is a Weblogger. Roller makes it easy for you to maintain a weblog, even if you are have little or no knowledge of HTML. All you have to do is go to a web site that is running the Roller software, sign up for an account and bam you have a weblog. You can start posting right away. You will need to know a little about HTML if you want to kick it up a notch by customizing the layout of your Weblog and adding new pages to your Weblog website. More on that later. Please note that Roller is currently beta quality code not necessarily ready for prime time there are probably a number of design flaws and an even larger number of bugs. As always with software of all sorts, and especially pre-release software such as this, use at your own risk. If you find a flaw, a bug, or something that you do not like please contribute back to the Roller project be reporting that bug to the Roller development team's [JIRA issue tracking system|http://opensource.atlassian.com/projects/roller/]. \\ \\ !!![#2] Gettings started To get started with Roller you need to either 1) find a Roller site somewhere that is offering new user registration or 2) install Roller yourself. There are a couple of sites offering free Roller accounts. One is AnthonyEden's aptly named FreeRoller site, hosted by JavaLobby. Another is [http://blogs.application-servers.com]. Both of these sites are currently running Roller 0.9.6, so some of the features described in this guide will not be available. What about installing Roller? You should only attempt to install Roller yourself if you are comfortable with system, database, and Java app server administation. If you are ready for the challenge, download Roller from the DownloadPage on SourceForge and follow the instructions in the Roller InstallationGuide to install and start Roller. \\ !!QuickStartGuide So, how do you get started? The Roller QuickStartGuide shows you how to create a new Roller account and how to make your first weblog post (it's on a separate page because it has lots of images and is only interesting to first time users). \\ !!The Roller Web Application There are three main parts of the Roller Web Application: the main page, user website pages, and the Editor UI. * __The Roller main page__: The main page of a Roller site shows the most 15 most recent weblog posts for all of the users weblogs that are hosted on the site and a the 15 most popular weblogs for the day (according the referer ranking). Under the list of the most recent weblog posts, there is a bright orange XML icon that links to an RssFeed that combines all of the weblogs on the site into one aggregated new feed. For each of the weblogs listed in the most popular weblogs list there is a bright orange XML icon that links to the RssFeed for that weblog. * __User pages__: Each Roller user has his or her own "website" within the Roller installation. A website is a set of pages, each page is defined by an HTML page template that may be edited by the user. These page may contain VelocityTemplateLanguage expressions, control statements, and a special set of VelociMacros for useful things like a WeblogCalendar, EditorNavBar, PageNavBar, RefererList, and other things. One of these pages is the user's weblog page or default weblog page. More about this later... * __The Editor UI__: The Roller Editor UI is a web-based UI for editing your weblog, managing weblog categories, managing a bookmark collection (AKA blogroll) managing newsfeeds, configuring, and administering a Roller website and installation. The menu for the Editor UI contains the same items as the Editor Navigation Bar, but is presented in an Amazon-style tabbed menu format. The rest of this guide will walk you through using the Editor UI to do all these things and we'll take a closer look at the Roller Editor UI menu. To help you find your way around the Roller Web Application, there are three types of Navigation Bars in Roller: the Navigation-Bar, the Page Navigation Bar and the Editor Navigation Bar. __Navigation Bar__ The Navigation Bar appears at the top of the Roller main page and at the top of the Roller Editor UI. When you are not logged into Roller the navigation bar looks like this: [http://www.rollerweblogger.org/userguide/images/navbar.png] When you logged to Roller, the navigation bar expands to show links to all of your public pages, to the Weblog:Edit page and to the Website:Settings page. For example, if you had pages named 'Weblog', 'Bookmarks', and 'Archive' and you were logged into Roller, your Navigation Bar would look like this: [http://www.rollerweblogger.org/userguide/images/navbar-auth.png] __Page Navigation Bar__ The Page Navigation Bar is produced by a Roller macro that may be used in Roller user pages. The macro is called #showNavBar() and it is included in all of the default Roller template, but you could choose to remove it if you wanted. For example, if you had pages named 'Weblog', 'Bookmarks', and 'Archive' and you were not logged into Roller, your Page Navigation Bar would look like this: [http://www.rollerweblogger.org/userguide/images/page-navbar.png] After you logged into Roller your Page Navigation Bar would look like this: [http://www.rollerweblogger.org/userguide/images/page-navbar-auth.png] __Editor Navigation Bar__ The purpose of the Editor Navigation Bar is to make it easy for you, when you are logged into Roller, to access the Roller Editor UI directly from your weblog page. Like the Page Navigation Bar, the Editor Navigation Bar is also produced by a Roller macro. The macro is called #showEditorNavBar() and it is also included in all of the default Roller templates. If you are not logged into Roller, the Editor Navigation Bar will hide itself. The Editor Navigation Bar looks like this: [http://www.rollerweblogger.org/userguide/images/editor-navbar.png] Clicking on any of the links on the Editor Navigation Bar will take you into the Roller Editor UI. \\ \\ !!![#3] Managing your Weblog In Roller, managing your weblog includes writing new weblog posts, editing old weblog posts, deleting comments, sending trackbacks, creating weblog categories, and viewing your referer logs. Here is the Weblog sub-menu of the Roller Editor UI: [http://www.rollerweblogger.org/userguide/images/eui-weblog.png] \\ !!Adding a new weblog post To add a new Weblog post you simply go to the Weblog:Edit page, enter an optional title in the Title field, enter the your post in the Content text area, choose a category from the Category combo, and hit the __Post to Weblog__ button. As soon as you do that, your Weblog entry is posted to your Weblog for the world to see. Here is the relevant part of the Weblog:Edit page. [http://www.rollerweblogger.org/userguide/images/new-post.png] The above screenshow shows the default plain text weblog post editor. With this editor, you are entering raw HTML and if you don't know HTML you will not be able to do bold, italics, paragraph breaks, etc. Roller also support several other WysiwygEditors and you can pick the one you want using the Website:Settings menu of the Editor UI. __The Publication Time Field__ When you make a new weblog post, you don't need to enter anything into the Publication Time field. Roller will fill that in for you when you hit the post or save button. When you edit your post later, you may choose to change this Publication Time. I know this is lame, but you must enter the date in the format 'dd.MM.yyyy HH:mm:ss'. If you don't like it then fix it and send [us|http://sourceforge.net/mail/?group_id=47722] the code. __Save as Draft__ If you want to save your post as a draft, a private draft that nobody can see but you, then hit the __Save as Draft__ button. Your entry will be saved and you can edit and post it later. __Spell Check__ If you want to spell check your entry before posting it or saving it as a draft, then hit the __Spell Check__ button. The Spell Checker will note each misspelling and will offer alternatives for each, as shown below: [http://www.rollerweblogger.org/userguide/images/spell-check.png] \\ !!Working with Old Weblog Posts You can also use the Weblog:Edit page to manage your old posts. Below the Title and Content fields, and below the Post and Save buttons is a table that lists your most recent weblog posts, both public and private (AKA drafts). There is also a calendar so that you can navigate to even older posts. The bottom of the Weblog:Edit page looks like this: [http://www.rollerweblogger.org/userguide/images/edit-old-posts.png] There are a number of operations that you can perform on each post. Here is a summary: *__Edit__: This will load the post into the edit-weblog text area so that you may edit it and then either repost it, save it as a draft or spell check it. *__Comments__: This will display the comments that have been made by users either through the comment form or Roller's Trackback facility. You may choose to delete comment, but you cannot edit them. *__Send Trackback__: This will display the Send Trackback page so that you can send a Trackback ping to another blog to tell that blog that you are writing about them. *__Remove__: This will remove the weblog post. First, Roller will ask you "are you sure?" \\ !!Working with Weblog Comments If you have enabled comments in your Website:Settings page and you have one of the comments macros in your day template (__#showCommentsLink()__ or __#showCommentsPageLink()__) then your users may leave comments on each of your weblog entries. Also, Trackbacks that come in from other weblogs are treated as comments. You can't edit comments, that wouldn't be right now would it? However, you can delete the comments that you do not like. From the Editor UI you can view and delete the comments that are associated with your weblog entries. To view the comments for a weblog entry, click on the __Comments__ link for that entry on the __Weblog:Edit__ page. You'll see the Delete Comments page as shown below. Click the checkboxes for the comments and/or Trackbacks you wish to delete and blow them away. [http://www.rollerweblogger.org/userguide/images/delete-comments.png] \\ !!Sending Trackbacks If you are writing about something you read on another weblog, you want to let the author and readers of that weblog know that you are doing so, and that other weblog is [MT Trackback|http://www.movabletype.org/docs/mttrackback.html] enabled, then you should send that weblog a Trackback ping. To send a Trackback for one of your weblog entries following these steps: # Locate the Trackback URL for the weblog entry that you wish to ping on the other site, copy it with ALT-C (or whatever). # Click the __Send Trackback__ link your weblog entry in the Weblog:Edit page. The Roller __Send a Trackback__ page will appear. # Paste the Trackback URL that you found step 1 into the Trackback URL field of the __Send A Trackback__ page and click the send button. Here is the __Send a Trackback__ page: [http://www.rollerweblogger.org/userguide/images/send-trackback.png] If the Trackback completed successfully, you should see a page like the one below with the number 0 in the tags. If the Trackback failed you should see an error message that explains what went wrong. [http://www.rollerweblogger.org/userguide/images/sent-trackback.png] \\ !!Weblog Categories Roller's weblog categories feature allows you to organize your weblog posts by category. For example, you might setup a category called "Family" for your family related posts, a category called "Music" for your music posts, and a category called "Misc" for everything else. When you write a new weblog post you must decide which category to place it in. On the Weblog:Edit page, there is a combo-box that allows you to pick a category for your post or to change the category when you edit an old post. Currently, Roller only allows you to assign each weblog post to one category. __The Weblog Category Chooser__ When a user views your site, they can choose which category to view. All of the stock Roller weblog templates include the Weblog Category Chooser (displayed by the #showWeblogCategoryChooser() macro) close to the top of the page so that your readers can pick which category to display or "All" for all categories of posts. __RSS Feed for Each Category__ Your weblog's main RSS newfeed includes all categories, but users can choose to subscribe to specific categories. All of the stock Roller weblog templates display a list of your RSS feeds (displayed by the #showRSSLinks() macro), one for all categories and one for each separate category. __Adding, Renaming, and Removing Weblog Categories__ You can change the names of your categories, add new categories, and delete categories using the Weblog:Categories page of the Roller Editor UI. \\ !!Flushing the Cache The __Weblog:Flush__ Cache menu item allows you to flush the Roller page cache. The page cache is a performance feature that allows Roller to serve up pages faster and to minimize database access. Normally, the cache is flushed when you edit a weblog entry, add a new page template, or do just about any other operation. So, under normal conditions you should not need to flush the cache. \\ !!Referer Rankings The __Weblog:Referer__ referer rankings page shows the hits that are coming in from other websites and weblogs that have links to your weblog and to specific entries in your weblog. By looking at your referer logs, you can get an idea of who is reading and commenting on your weblog. \\ \\ !!![#4] Customizing Your Website If you are thinking "my website? What ''are'' you talking about? I thought I had a weblog not a website," then let me explain. In Roller we use the word ''website'' because, as a Roller user, that is what you have, a website. You don't just have a weblog, you have a website made up of multiple pages. Each of these pages is defined by a ''page template'' also known as a ''page''. One of these pages is your weblog. As a Roller user, you are free to customize the look-and-feel of your website 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. Figure: The Roller Editor UI's Website Menu and it's Submenus: [http://www.rollerweblogger.org/userguide/images/eui-website.png] In this section, we'll discuss making simple settings changes via the __Website:Settings__ page, switching themes using the Theme Switcher __Website:Themes__ page, customizing your page templates via the __Website:Pages__ page, and uploading files to your website via the __Website:Files__ menu. \\ !!Website Settings The __Website:Settings__ page allows you to set some simple configuration properties for your website, like the title and description of your site. It also allows you to choose an HTML editor for the __Weblog:Editor__ page and to enable and disable support for the BloggerAPI and for Comments. The __Website:Settings__ page is shown below. [http://www.rollerweblogger.org/userguide/images/website-settings.png] The website settings form allows you to set the following properties for your weblog website: * __Title of this website__ - The title of your website 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 $macros.website.title * __Description of this website__ - The description of your website 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 __$website.description__ * __Page to be used as the homepage__ - Choose a page template to be used as your websites main page. * __Weblog editor page to be used__ - Choose a weblog editor page, some are WysiwygEditors ** editor-text.jsp ** editor-dhtml.jsp ** editor-ekit.jsp ** editor-midas.jsp ** editor-text-js.jsp ** editor-wiki-js.jsp * __Allow commments for your weblog__ - Set this to true to enable comments for your weblog. Note that, in order for comments to work, you will also have to include the comments macro in your day template. All of the themes that come with Roller include this macro, so you shouldn't really have to worry about this. * __Enable Blogger API for your weblog__ - Set to true to enable weblogging via the Blogger API. This will allow you to use handy Blogging clients like [w:bloggar|http://www.wbloggar.com/] to post to your weblog. * __Category for posts recieved via Blogger API__ - Choose the category for incoming posts made via the Blogger API. This only applies if you blogging client does not support categories. * __Ignore incoming referers that contain any of these (comma-separated) words__ - you can use this to filter out what referers are accepted. Somewhat useful if you start getting hit by referer spam, but not a complete solution to the referer spam problem. \\ !!Website Themes A Website Theme is a look-and-feel for your website, a skin, if you will. When you created your Roller weblog/user-account, you picked from one of the available Roller themes. You might have picked the Robot theme, or the Roller theme, or whatever. A theme determines how your Roller website looks. If you want to change your theme, you can use the Roller Website:Themes menu to switch to a different theme. This is really easy and does not require any knowledge of HTML. I'll illustrate this below with a screenshot, but first a word of warning. If you have customized your theme on your own by modifying the HTML, CSS, and/or JavaScript in the pages that comprise your Roller theme, then watch our. Switching themes using the Roller Theme Switcher will destroy the customizations that you have made. Below is the Roller theme switcher. You can pick a new theme, preview it, and then either cancel or save the theme. If you don't hit the save button, your theme will not be switched. [http://www.rollerweblogger.org/userguide/images/theme-switcher1.png] If you were to pick the Moonshine theme in the "Select a theme" combo-box and then hit the preview button, you would see something like the screenshot below. If you want to select this new theme you will have to hit the __Edit__ button to return to the Theme Switcher and then hit the __Save__ button to save your theme selection. [http://www.rollerweblogger.org/userguide/images/theme-switcher2.png] \\ !!Uploading Files Roller now includes a file-upload feature that allows you to upload images and other file for use in your weblog templates. Here are the steps to upload an image to Roller and to use it in a weblog template: # Use the Website:File menu option to upload your image file # Use the Website:Pages menu to edit one of your templates. # Place an HTML IMG tag where you want the image. Here are the steps to upload an image to Roller and use it in one of your weblog entries: # Use the Weblsite:File menu option to upload your image file # Use the Weblog:Edit menu to add or edit a weblog entry. # Place an HTML IMG tag where you want the image. In either case, you should specify the absolute URL to your image in the IMG tag, and you should add an ALT attribute to explain your image. Uploaded Images will be available at a URL like this: http://sitename/resources/username/imagename.ext. For example, if your site is FreeRoller, your username is mrroller, and your image name is leo.gif, then your IMG tag should look like this: {{{ one happy baby }}} \\ \\ !!![#5] Customizing your theme with Roller Macros Your website's theme is defined by a set of page templates. A page template is a file with some special macros that indicate where Roller is supposed to put your Weblog, Weblog Calendar, and other dynamically created content. A template can be an HTML file, an HTML fragment, a CSS page, or just about anything else you can enter into Roller as text. Roller uses the powerful Velocity template language and this gives you a lot of power and flexibility in customizing the look and feel and layout of your website and your weblog pages. For more information on the Velocity template language, refer to the [Velocity website|http://jakarta.apache.org/velocity/] and to the [Velocity Reference Guide|http://jakarta.apache.org/velocity/vtl-reference-guide.html]. Roller user's refer to page templates as either pages or template, the words page and template are used interchangably. ''__NOTE__: Older versions of Roller used macros that began with __$macros__. These old macros have all been replaced by newer macros. The newer macros all start with the __#__ hash mark. See section [5.1|51] below on Roller Macro and Variable Reference for more information on the new macros and for a migration guide to help you move from the old macros to the new macros.'' \\ !![5.1|#51] Weblog and day pages Every Roller theme is a little different, but all themes have a minmum of two page templates: a weblog page and a day page. Let's discuss the purposes of these two pages. __Your Weblog page__ Your weblog page is the main page of your website, the one that is specified as the default page in your Website:Settings page. This page is the page that displays the entries in your weblog, your weblog calendar, etc. This page can be very complex, or very simple, depending on your page design. To understand the weblog template, let's take a look at a simple example. Below is the weblog page template from Roller's Basic theme. This is a really 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: {{{ __#showWebsiteTitle()__ #showRSSAutodiscoveryLink()

#showWebsiteTitle()

#showWebsiteDescription()

#showWeblogCategoryChooser()
#showWeblogEntries("_day" 15)

Calendar

#showWeblogCalendar()

RSS Feeds

#showRSSBadge()
#showRSSLinks()

Links

#showBookmarks("Blogroll" true false)
#showBookmarks("News" true false)

Navigation

#showBasicNavBar(true)
#showEditorNavBar(true)

Referers

#showReferers(30 20)
}}} For a full listing of the Roller Macros refer to the Roller Macros and Variable Reference section below. The most important macro on the page is the __#showWeblogEntries__ macro. As you can see, it takes two arguments, the first is the name of the day page to use in the display of the weblog entries and the second is the number of weblog entries to be displayed on the page. __Your Day Page__ Your Day page is used by the __#showWeblogEntries__ macro to display your weblog entries. This is where you customize the display of each day and of each weblog entry. Returning our example, below is the day page from the Basic theme: {{{
#showDayPermalink( $day ) #showEntryDate( $day )
#foreach( $entry in $entries )

$entry.title $entry.text ($entry.pubTime) #showEntryPermalink( $entry ) #showCommentsPageLink( $entry )

#end #showLinkbacks( $day )
}}} Note that there are two variables __$day__ and __$entries__ available for use in the day template that are not available in other templates. The __$day__ variable refers to a date object (java.util.date) that contains the date of the day that is being rendered by the dat page. The $entries variable contains a collection of weblog entry objects (org.roller.model.WeblogEntryData). The example above uses a Velocity __#foreach__ loop to iterate through the individual entries in the entries collection and to display the title, text, and publish time of each. \\ !![5.2|#52] Other pages and comments You can add as many pages as you like to your Roller website, you can choose which ones are to appear in your website's navigation bar, you can include pages in other pages using the __#includePage__ macro, and you can include Roller macros in any of these pages. Use the Roller Editor UI's Website:Pages menu to add new pages and to edit your existing pages. __Your default page__ You can define as many pages as you would like, but you must specify one page is to be your default Page, that is, the page that your readers first see when they visit your website. You can specify your default page in your website settings on the Website:Settings page of the Roller Editor UI. __Some pages are visible, some are not__ Note that any page whose name begins with the underbar "_" character will not be visible to your readers, meaning that it will not appear in your website's navigation menu that is dislayed by the __#showNavBar__ macros. __Pop-up comments, the comments page, and TwistyComments__ The Basic theme example above also uses the __#showCommentsPageLink__ macro to display a link to the comments page for the weblog entry. If, instead, you wanted to use a popup comment, you could use the __#showCommentsLink__ macro. __NOTE__: comments will not work unless you check the ''Allow Comments'' check-box on the __Website:Settings__ page. What about Raible's TwistyComments? They are available in Roller 0.9.8, but not in Roller 0.9.7. If you are upgrading from Roller 0.9.6, take a look at EnablingComments. \\ !![5.3|#53] Roller Macros and Variables For a complete list of the Roller Macros, see the [Macro Reference Guide|http://www.rollerweblogger.org/velocidocs/index.html]. If you are upgrading your pages from Roller 0.9.6, then see the [Macro Conversion Guide |http://rollerweblogger.org/docs/macro_conv.html]. There are also a host of variables and objects that are available for your use in page templates: |__$now__ | The current time (a java.util.Date object). |__$ctxPath__ | The path under which Roller is running (see Webapp context). |__$baseURL__ | Base URL for your Roller website |__$absolutebaseURL__ | Absolute base URL for your Roller website. |__$uploadPath__ | The location where uploaded files are placed. |__$user__ | The current user object for the page/entry being viewed. |__$userName__ | The current user's username. |__$fullName__ | The current user's full name. |__$emailAddress__ | The current user's email address. |__$macros__ | The old legacy Roller 0.9.6 macros object. |__$website__ | The website for the current user. |__$page__ | The current page being viewed. |__$requestParameters__ | A map of the request parameters |__$rollerVersion__ | Version number of Roller software |__$utilities__ | A utilities object |__$stringUtils__ | A string utilities object Date formatting variables and objects: |__$dateFormatter__ | Date formatter object |__$toStringFormat__ | A date format to be used with the macro formatDate( $dateFormat $date ) :\\ EEEE MMMM dd, yyyy |__$plainFormat__ | Another date format for use with the formatDate() macro:\\ yyyyMMdd If the page is a day page template, then these variables are available too: |__$day__ | Date object holding date being displayed |__$entries__ | Collection of entries for date being displayed If the page is a comments page, then these variables are available: |__$isCommentPage__ | will be set to true |__$entry__ | weblog entry containing collection of comments |__$autoFormat__ | True if comments should be autoformatted |__$escapeHtml__ | True if HTML should be escaped \\ !![5.4|#54]Creating and packaging your own Roller theme A Roller theme is, at a minimum, a subdirectory in the Roller ''themes'' directory with a page template named Weblog.vm in it. How does Roller determine what themes are available? Roller considers every subdirectory in the themes directory to be a theme. __How does Roller create a theme?__ When you create a new user or switch themes for an existing user, Roller will read in a new theme for that user. When Roller reads in a theme for a user, all it is does is to create or replace the user's page templates. Roller follows these steps to read in a theme: # For each file in the theme's subdirectory that ends with ''.vm'' Roller creates a page template with the same name as the file, minus the ''.vm'' extension # The page template that is named ''Weblog'' is set to be the website's default page. __Including images, JavaScript, and CSS style sheets in a theme__ If you want to create a more sophisticated theme, one that takes advantage of the Roller theme macros, you can use the following directory structure for your theme (as illustrated by [MattRaible]'s x2 theme): [http://www.rollerweblogger.org/userguide/images/theme-dir-structure.png] The page templates go in the root directory of the theme, images in the ''images'' directory, JavaScript files in the ''scripts'' directory, and CSS style sheets in the ''styles'' directory. Then, you can make your theme ''distributable'' by using relative paths to get to all of your themes images, scripts, and style sheets. You do this by using the Roller theme macros, listed below, whenever you refer to a file in your theme: * #showThemeScript( themeName, scriptFileName ) * #showThemeScriptPath( themeName ) * #showThemeStyleImport( themeName, scriptFileName ) * #showThemeStyle( themeName, styleFileName ) * #showThemeStylePath( themeName, styleFileName ) * #showThemeImage( themeName, imageFileName ) * #showThemeImagePath( themeName, imageFileName ) * #showThemePath( themeName ) \\ \\ !!! [#6]Using Roller for Bookmark and Blogroll Management You probably already have a web bookmark (AKA links) collection stored in your web browser, so why do you need to enter bookmarks into Roller? There are a couple of reasons. Most bloggers like to display a ''blogroll'' of links to favorite blogs. Most bloggers also like to display lists of favorite websites. By entering your bookmarks into the Roller bookmark manager, you'll find that it is easier to display your bookmarks on the various pages that make up your website. Bookmarks Management Submenu: [http://www.rollerweblogger.org/userguide/images/eui-bookmarks.png] \\ !!Adding new bookmark folders Bookmarks are organized in to named folders. You can define any number of folders and each of these folders can hold any number of bookmarks. There is only one level of folders, so you cannot have a folder that contains other folders. Your initial website contains two bookmark folders: one named "Blogrolling" that contains Weblogging related links and one named "News" that contains links to well known news sources. If you look at Figure 1 again, you can see that these two folder are displayed on the left side of the Weblog page. You can use Roller's bookmark management features to rename these folders if you wish, or you can delete them add add folders of your own choosing. Figure: the Edit-Bookmark Folders page \\ !!Adding bookmarks to folders Once you have defined one or more bookmark folders, you can start adding bookmarks to those folders. From the Edit-Bookmark Folders page, click the Edit link for the Folder you wish to edit. You will be taken to the Edit-Bookmark Folder page for that folder. From there you can edit the name of the folder and you can add and remove bookmarks in that folder. Figure: the Edit-Bookmark Folder page \\ !!Editing a bookmark After you use the Edit-Bookmark Folder to add a bookmark, you can edit the Bookmark itself. To edit a bookmark, click on the Edit link in the Edit-Bookmark Folder page. That will take you to the Edit-Bookmark page and from there you can change the name, description and display priority of the bookmark you have chosen to edit. You can also move the bookmark to another folder by changing the Bookmark Folder combo-box. Figure: the Edit-Bookmark page \\ !!Displaying your bookmarks You can use the __[#showBookmarks|http://www.rollerweblogger.org/velocidocs/macro-showBookmarks3.html]__ macro to display your bookmarks on your website pages. The macro will display all of the bookmarks in one of your bookmark folders. The arguments are ''String folderName'', ''boolean showFolderName'', and ''boolean expandingFolder''. The expanding folder feature is implemented using JavaScript, so, it will only work if the Roller JavaScript file is included on the page where the macro is used. For example, let's say that you want to display a folder named "News", you want to display the folder name, and you want to display it as an expanding folder. First, near the top and inside the tag of your page, include the Roller JavaScript page roller.js, as shown below: {{{ ... My badass blog ... }}} Later in your page, include the __#showBookmarks__ macro to display your bookmarks: {{{ ... #showBookmarks( "News" true true ) ... }}} \\ !!Importing Bookmarks in OPML format Roller makes it easy to import bookmarks and build your blogroll by importing bookmarks in OPML format. XBEL might be a better bookmarks format, but OPML is more popular in the world of weblogs. To import bookmarks via OPML, follow these steps: #download bookmarks in OPML format from a site such as Scripting.COM and save them as a file on your hard disk. #Login to Roller and choose the Bookmarks:Import menu option. #Use the file-upload capability to upload the OPML file into Roller. The bookmarks will be imported into a folder called "unfiled". You can use Roller to organize the bookmarks as you wish. \\ !!![#7] Using Roller for Display of RSS Newsfeeds Newsfeed Aggregation Submenu: [http://www.rollerweblogger.org/userguide/images/eui-newsfeeds.png] \\ !!Adding and deleting newsfeeds A newsfeed is a list of news stories and a short desciption of each story that is automically retrieved from some remote website. Newsfeeds are delivered in a format known as Really Simple Syndication or Rich Site Summary or just RSS. Roller allows you to include newsfeeds on your Weblog page or on a separate page that you create as part of your Weblog's website. Your initial website will include three newsfeeds, but none of these newsfeeds are displayed on your Weblog page. You can use one of the macros that we will discuss later to display your newsfeeds. Before you include a newsfeed on your website, you should probaby make sure that doing so is OK with the provider of the newsfeed. Some providers might frown upon this and by frown I mean that they might sick a pack of rabid lawyers on your ass. Anyhow, use your own judgement here, I am not a lawyer and I am not responsible for any of your current or future legal troubles. To add a newsfeed you need a URL to the providers RSS feed. This URL usually ends with the letters ".xml". Enter the name that you would like to use for the newsfeed, enter the URL and hit enter to add the newsfeed. \\ \\ !!![#8] Using a Blogging Client with Roller You can use any Blogger API client to post and edit Roller weblog entries. Before you can do this, you must go to the Roller Website:Settings menu and check the box that reads Enable Blogger API for your weblog. You should also pick a category for posts made through the Blogger API because some blogging clients do no support categories. \\ !!Using w:bloggar [w:bloggar|http://www.wbloggar.com/] is a full-featured blogging client that runs on Windows. If you want to take advantage of all of the cool w:bloggar features, like support for titles and categories, then you'll need to modify the w:bloggar configuration file. The configuration file is located in the CMS directory of the w:bloggar install, it is named ''CMS.ini''. To configure w:bloggar for Roller, you'll need to add a Roller section to CMS.ini. Near the start of ''CMS.ini'', you find a line that reads ''Config='' and then some number. That count is the number of sections in the ''CMS.ini'' file. Since we are adding a section, we need to increment that number by one. For example, below we have incremented it from 15 to 16. {{{ [CMS] Count=16 }}} Next, add the following section at the end of the CMS.ini file. Make sure that the number at the end of ''CMS-'' matches the number that you entered for the count above. {{{ [CMS-16] Name=Roller Weblogger URL=http://rollerweblogger.org Icon=rollerbadge.jpg Service=0 Host=myhost.com Page=/roller/xmlrpc Port=80 Https=0 MultiCateg=3 GetCategMethod=3 PostMethod=3 GetPostsMethod=3 TemplateMethod=1 }}} Once you've doen this, start w:bloggar. To hook up to your Roller account, choose the File-Select-Account menu item. You'll see the dialog-box below, choose ''<>'' in the account combo-box and enter your Roller user-name and password, as shown below. [http://www.rollerweblogger.org/userguide/images/bloggar-new-account.png] Next, answer ''Yes'' to the ''Do you want to create this account?'' message-box and hit ''OK''. Next, you'll see the ''Account Properties'' dialog-box, shown below. Choose ''Roller Weblogger'' in the Blog Tool combo-box, enter a name for this account in the Alias text-field, and check ''Ping Weblogs.com''. __NOTE__:If you are using FreeRoller, remove the ''/roller'' from the start of the ''Page'' setting as shown below: [http://www.rollerweblogger.org/userguide/images/bloggar-account-settings.png] \\ \\ !!![#9] Configuration and Administration of Roller If your friendly Roller adminstrator has added your username to the list of admin users in roller-config.xml, then you will have access to the Roller adminstration menus __Website:Admin__ and __Website:Config__. Let's discuss what you can do with those menus. \\ \\ !!Admin The admin screen is only available to Roller administrators. It allows you to edit user information and to delete users. All you have to do is to pick a user using the combo-box, make your changes, and hit submit. If you have a lot of users, this page may take a while to load - all the user names will be put into the combo-box! Don't like this? Why don't you fix it and submit a patch to the Roller dev team? [http://www.rollerweblogger.org/userguide/images/user-admin.png] \\ !!Config The Website:Config page allows you to tweak all sorts of Roller settings. It is a big page, so we will discuss each section separately below. [http://www.rollerweblogger.org/userguide/images/admin-site.png] * __Site Name__: name of the site, to be included in site-wide RSS feed * __Site Description__: description of site, to be included in site-wide RSS feed * __Site Administrator's E-Mail Address__: admin's E-Mail address, to be include in side-side RSS feed * __Absolute URL to this site__: (optional) to be used as basis for creating absolute URLs. If you are running your Servlet Container behind a Web Server, you may need to set this. * __Enable Linkback extraction__: LinkBack extraction is expensive, a one-shot thread is started for each incoming referer. For a large multu-user site (like FreeRoller), it should probably be turned off. [http://www.rollerweblogger.org/userguide/images/admin-users.png] * __Allow New Users__: Set this to enable the ''register as new user'' link on the main page. * __Admin Users__: Comma-separated list of users that have admin rights. * __New User Data__: This is no longer used by Roller and should be removed. * __New User Themes__: Directory where new user themes are located. * __Editor Pages__: comma-separated list of weblog editing pages available to users, some are WysiwygEditors. * __Autoformat Comments__: should comments be auto-formatted (turns linefeeds into
tags)? * __Escape Comment HTML__: should HTML be remove from comments? * __E-Mail Comments?__: turn on e-mail comment notification for all users. This should be a per-user setting, not a site wide setting. [http://www.rollerweblogger.org/userguide/images/admin-upload.png] * __Enable File Uploads__: are users allowed to upload files? * __Allowed Extensions__: comma-separated list of file extensions that users are allowed to upload. * __Forbidden Extensions__: comma-separated list of file extensions that users are NOT allowed to upload. * __Max File Size (MB)__: max size of file that users are allowed to upload. * __Max Directory Size (MB)__: total upload directory size per user. * __Upload Directory__: store user uploads under this directory with a subdirectory per user. * __Upload Path__: URL that is mapped to the upload directory. [http://www.rollerweblogger.org/userguide/images/admin-rss-agg.png] * __Enable RSS Aggregator__: allow users to display aggregated newsfeeds on their pages? * __Cache incoming RSS newsfeeds__: cache aggregated newsfeeds? I'm not sure why you'd ever want to turn this off. * __RSS newsfeed Cache Time__: Time, in minutes to cache each aggregated newsfeed.