Publishing active blogRolls
activeRenderer tutorial - part 4
activeRolls are just like regular blogrolls, with a twist: active outline wedges to uncover underlying levels of information. They are great for preserving screen real-estate.
Step 1: Create a blogRoll outline.
According to Jake Savin's definition, blogrolls are a collection of links on the home page of a weblog that point to sites that are somehow related to yours.
They serve several purposes, they direct readers to the sites that are important to you, and serve as a set of bookmarks for you.
They also help build page rank in search engines for sites you wish to bestow page rank on.
So first use Radio's outliner to create an OPML document with your links.
Here is a screenshot of the original version. (expand the wedge on the left to see a current version in this page).
And here is a screenshot of the same outline in the right sidebar of s l a m's home page.
Usually, blogrolls are organized into sections, the title of each section is a summit node, and all related links are indented underneath it.
Links are actually nodes bearing a link XML tag attribute.
In Radio's outliner, you can define a link attribute by selecting a node in the outline, then the 'Outline / Add Link...' menu option, then typing or pasting a URL (a Web address) for the link.
You can save your blogroll outline under any file name ending with '.opml'.
There's nothing preventing you from creating several blogrolls, with different file names.
If you create a file named blogroll.opml and save it in the gems sub-folder of your www folder, you will conform to UserLand's recommendations.
Your blogroll will be automatically scanned if you're using UserLand's headLinks macro.
But there's nothing preventing you from saving it to any folder which content is upstreamed to the public site without any rendering, such as the opml folder created by aR under www.
Step 2: Insert an activeRoll macro call in your main template.
Open the #homeTemplate.txt file located in Radio's www folder with a text editor.
Find a good place to insert the activeRoll macro.
A good place is usually within the left or the right sidebar of your template.
Insert a line like the one in the screenshot attached to this node, substituting the pathname for your own blogroll file.
On a Windows system, the local URL would look more like this :
file:///C/Program%20Files/Radio%20UserLand/www/gems/blogroll.opml
You may also use a local URL:
http://127.0.0.1:5335/gems/blogroll.opml
Or like this if you were referencing a file on your public site, it could look like this :
http://radio.weblogs.com/0104487/gems/blogroll.opml
You can and should substitute another string for the blogroll's title, title:"activeRoll" is just an example.
If you do not provide a title argument, your blogRoll will still be rendered, but without a title.
Important: if you are not currently publishing your weblog's home page with any of aR's 2 outline styles.
And have never done so at some point in the past.
Then, there's a good chance that your #homeTemplate.txt file is missing links to aR's Javascript code and CSS stylesheet in its header.
So, insert an activeRendererHeader macro call in the HEAD section of the template - check the attached screenshot.
Step 3: Re-publish your home page and check the result.
Use the Radio / Publish / Weblog Home Page menu in Radio.
Then check your Event Log after a minute or so, and click on the index.html link in the latest Upstream event, it should be listed as one of the most recent events.
Step 4: Customize your blogRoll's style.
All elements of the roll are defined by CSS classes in the activerenderer.css stylesheet.
You will find activerenderer.css in the activeRenderer sub-folder of www.
To learn more about CSS stylesheets, try the O'Reilly Salmon book, and the W3C specification.
rollTitle defines the style for your blogroll's title element.
roll defines the style for the 'box' - an HTML div - in which the blogroll is encased.
roll1 to roll4 define the style for each indentation level in the blogroll's outline.
Feel free to add more levels if you need them.
rollHelp defines the style for the 'how this works' link.
If you customize the activerenderer.css stylesheet, do update the version number (currently 1.0.4) at the top of the file to a greater value.
This way, your customized version will not be automatically superseded the next time I update the default CSS stylesheet in activeRenderer.
You may also override those classes by inserting new definitions for them in the header section of your template file, inside a STYLE tag.
Step 5: Use activeRoll's optional parameters.
In the previous step, you've learned that the default style for your blogroll is defined by CSS classes with names all starting with roll.
You can specify another name when calling activeRoll from a template.
In the attached example, the title - Navigation - will have a style of navLinksTitle, the blogroll's box will be defined in navLinks, indentation levels will start at navLinks1.
This way, you may have several activeRolls with different styles on the same page.
If you are Rick Klau, and inserting your blogroll in an HTML iframe tag, you can specify a target:"_parent" optional parameter to have all links point to your main frame.
This should work even if your name is not Rick Klau.
Specially since Rick has now moved his weblogs to Movable Type :-)
You don't even have to be a lawyer, though it may help...
You can also use target:"someWindowName" to have all links open in the same distinct window.
By default, all links in your blogroll open in a new window.
So, by now you should be convinced that activeRolls are both neat and simple to add to your weblog. But wait, wouldn't it be even cooler if you could publish your browser bookmarks, even your Yahoo bookmarks directly into an activeRoll ? Check out part 5 then.
