Radio Userland monthly archive macro - Come get some!!

| 20 Comments | 5 TrackBacks

I've searched high and low for a macro that would create a list of links to the monthly archive pages without success, so I decided to try and write one myself. This is a macro is a Cadillac - there's many features in it that many people may never use, but hopefully it will be of use to the largest possible number of Radio Userland users.

In deciding what the macro should be able to do, I included macro programming to do what I wanted it to do, what some posters on Radio Userland's forums have requested, and some things I thought would be cool or handy features for the macro.

How to install this script into your Radio.root

  1. Download the file to your local hard drive.

  2. You will then need to install it into Radio. Bring your Radio application to the front. From the 'File' menu choose 'Open...' and then select the newly downloaded script. A box will open, asking "Name for imported object?" and "workspace.monthlyArchiveLinks" will be displayed in the text box. Click OK to install the script. You will then see the script in a window.

    If you installed a previous version of this macro, you can install a newer version over an older version. Follow the steps #1 and #2. After clicking "OK" to install the script, another box will display which asks, "Replace existing object named workspace.monthlyArchiveLinks?". Click Yes to install the new version.

  3. Click Compile, then close the window. (Or take a look at the code if you want to see what is under the hood, then close the window.) The macro is now ready to use.

Feedback, comments, and suggestions to improve this macro are welcome.

Update 21-Aug-2003: hideInactive parameter added and documentation updated in response to a comment left by Jim Biancolo on Radio Userland's discussion forum.

Update 30-Aug-2003: Macro now respects #renderedFileExtension directive in #prefs.txt. Thanks to Lisa at distant, early morning for the tip.

Update 01-Sep-2003: Fixed Home Page archive links bug that caused macro to not correctly determine if a month has posts. (Incorrectly used nameOf instead of indexOf to get index number for post.)

Update 26-Oct-2004: Fixed bug where date format with month and year having no separating characters (such as "mmmyy") would give incorrect output for month names ending in a "y".

Documentation is included in the macro as comments, and reprinted below:

Features

  • Automatically determines range of dates to create monthly archive links for.

  • For dynamic pages (pages served locally on the Desktop Website), relative links starting at / are provided for the monthly archive links.

  • For static pages (pages upstreamed to a web server), full URLs for the monthly archive links are provided.

  • If the page being rendered is a category web page, monthly archive links to the category archive pages are provided.

  • If no posts were made in a particular month, the macro can optionally render that month as plain text instead of a link (so as to not link to a page which doesn't exist), or not render that month at all (omit that month from the list).

  • A start date, end date, or both can be specified to restrict the date range monthly archive links are created for.

  • Monthly archive links can be displayed in ascending or descending chronological order.

  • Separator text can be customized to create a vertical or horizontal list of links as well as include any special characters desired between monthly archive links.

  • Date format strings can be used to customize the appearance of the date text displayed for each monthly archive link.

  • Uses CSS classes for archive links, inactive archive "link" text, and separator text.

Usage

<%workspace.monthlyArchiveLinks (start:"date1", end:"date2", order:"o", separator:"sep", dateFormat:"format_string", hideInactive:true)%>

All parameters are optional and will use default values if omitted. (Using the macro can be as simple as including <%workspace.monthlyArchiveLinks ()%> in your template.)

Parameters:

start:"date1"

Type: string
Default: nil ("")

Valid values: Any string which can be interpreted as a date

  • Numbers separated by slashes or dashes, in the order in use by the system (e.g., "4/20/91" or "20/4/91" or "4-20-91" or "20-4-91")

  • Standard abbreviations for the month, with or without punctuation (e.g., "April 20, 1991" or "Apr 20, 1991" or "Apr 20 1991").

  • The full month, day and year (e.g., "April 20, 1991").

This parameter determines the beginning of the time period monthly archive links are created for.

If omitted, or has a value of nil (""), this parameter is set to the date of the earliest post (1st post) in the weblog.

Date for start parameter ("date1") must be less than or equal to date for end parameter ("date2"); otherwise the macro will exit with no error and no links will be created. Use the "order" parameter to reverse the order of links.

If an invalid date string is used, the macro uses the default value (date of 1st post in weblog) and outputs an error message along with the list of monthly archive links.

end:"date2"

Type: string
Default: nil ("")

Valid values: Any string which can be interpreted as a date

  • Numbers separated by slashes or dashes, in the order in use by the system (e.g., "4/20/91" or "20/4/91" or "4-20-91" or "20-4-91")

  • Standard abbreviations for the month, with or without punctuation (e.g., "April 20, 1991" or "Apr 20, 1991" or "Apr 20 1991").

  • The full month, day and year (e.g., "April 20, 1991").

This parameter determines the ending of the time period monthly archive links are created for.

If omitted, or has a value of nil (""), this parameter is set to the current system date (today).

Date for end parameter ("date2") must be greater than or equal to date for start parameter ("date1"); otherwise the macro will exit with no error and no links will be created. Use the "order" parameter to reverse the order of links.

If an invalid date string is used, the macro uses the default value (current system date) and outputs an error message along with the list of monthly archive links.

order:"o"

Type: string
Default: nil ("")

Valid values (case insensitive): "" (nil), "ascending", "ascend", "a", "descending", "descend", "d"

This parameter determines the chronological order of the monthly archive links.

For values of "" (nil), "ascending", "ascend", or "a" (or if this parameter is omitted), monthly archive links are listed in ascending chronological order (earliest to latest).

For values of "descending", "descend", or "d", monthly archive links are listed in descending chronological order (latest to earliest).

If an invalid value for this parameter is used, the macro uses the default value ("ascending") and outputs an error message along with the list of monthly archive links.

separator:"sep"

Type: string
Default: "<br/>"

Valid values: Any string

This parameter determines the separator text which is output between each monthly archive link.

If omitted, this parameter is set to a value of "<br/>". If set to a value of nil (""), monthly archive links will be created with no separator between them.

For vertical links, "<br>" or "<p>" can be used as a separator to put a line-break between each link.

For horizontal links, "&nbsp;" (non-breaking space) or a "|" character can be used as a separator.

No checking or processing is performed on separator string text. Invalid html included in separator string will have unintended effects.

dateFormat:"format_string"

Type: string
Default: nil ("")

Valid values:

Nil ("")

Literal value of "monthRange" (case sensitive)

Format string:

  • String must contain at least one of the following: "m", "mm", "mmm", "mmmm"

  • String may optionally contain at least one of the following: "yy", "yyyy"

  • String may contain other spacing and/or separator characters as desired

This parameter determines the date format for the text of the monthly archive links.

Value of "monthRange" produces links in the format of "08/01/2003 - 08/31/2003".

If a fomat string is used, the string must contain a "month" format code. A "year" format code is optional but recommended.

To display the month and year, include the following format codes in the format string:

  • "m" - displays months as 1 - 12
  • "mm" - displays months as 01 - 12
  • "mmm" - displays months as Jan - Dec
  • "mmmm" - displays months as January - December
  • "yy" - displays years as 00 - 99
  • "yyyy" - displays years as 1900 - 9999

If omitted, or has a value of nil (""), this parameter is set to a default value of "mmmm yyyy" (produces links in the format of "August 2003")

If this parameter does not contain a month format code ("m", "mm", "mmm", or "mmmm"), an error message is output and the macro exits (no links are created).

Leading and trailing spaces are trimmed from format string before creating monthly archive links.

Other characters present in format string are included as a part of the monthly archive link text as-is.

Examples of format strings used to format an August, 2003 monthly archive link:

  • "yyyy-mm" = "2003-08"
  • "mmmm, yyyy" = "August, 2003"
  • "mmm yyyy" = "Aug 2003"
  • "mmmyy" = "Aug03"
  • "mm.yyyy" = "08.2003"
  • "mm-yy" = "08-03"
  • "mmmm" = "August"
  • "< mmm >" = "< Aug >"

hideInactive:true

Type: boolean
Default: false

Valid values: true, false ("true", "false", 1, 0 also allowed)

This parameter determines whether months that have no posts are included in the list of monthly archive links.

If omitted, or has a value of false, months that have no posts are rendered as an "inactive" link (month is displayed as plain text only).

If parameter has a value of true, months that have no posts are not rendered and not included in the list of monthly archive links.

Values other than those listed above may cause unexpected behavior:

  • A non-zero numeric value will evaluate as true (inactive months not be rendered)

  • A value of nil ("") will evaluate as false (inactive months will be rendered)

  • Any non-empty string value other than "false" (case insensitive) will evaluate as true (inactive months will not be rendered)

adrBlog

Type: address
Default: radio.weblog.init ()

Valid values: ?? Use of this parameter, and use of values other than default not recommended

CSS classes

monthlyArchiveInactiveLink

Class used for monthly archive "link" when there are no posts for that month (and no link is created). This class should have same CSS as "a" tags (links) but use different color to indicate that the "link" is disabled. (I use "color: #999;" to indicate this.)

monthlyArchiveLink

Class used for "a href" tags of monthly archive links. Any characters included in the format string besides month and year format codes will also take on this formatting.

monthlyArchiveText

Class which encloses all text output by macro. Most notably, this class can be used to format separator text (for example, if "|" characters are used in a horizontal list of links, this class can be used to change their color, etc.).

Possible issues

If a category is being upstreamed to a different server than the main blog, it is not known if this macro will function correctly. (This case is untested.)

Changes

10/26/2004 - Fixed bug where date format with month and year having no separating characters (such as "mmmyy") would give incorrect output for month names ending in a "y".

09/01/2003 - Fixed Home Page archive links bug that caused macro to not correctly determine if a month has posts. (Incorrectly used nameOf instead of indexOf to get index number for post.)

08/30/2003 - Respect #renderedFileExtension directive in #prefs.txt

08/21/2003 - hideInactive parameter added and documentation updated

08/20/2003 - Macro created by David Phillips (TweezerMan)

5 TrackBacks

Monthly archive links, thanks to Tweezerman from clock -- watching time, the only true currency on April 14, 2004 9:42 PM

I implemented monthly archive links quite easily yesterday, thanks to this Radio macro for monthly archive links . Read More

A Radio macro that displays a list of links to the monthly archives. Read More

David Phillips: "I fixed a bug in my Monthly Archive Links macro (for Radio UserLand users) where specifying a date format that has the month and year next to each other (such as "mmmyy") displays the wrong output for months that end in "y". Read More

Archives from Tib's Bits on March 4, 2005 1:09 AM

Experimenting with an archives macro... Read More

20 Comments

I would like to add the archive links tool so I downloaded workspace.monthlyArchiveLinks.ftsc.txt. As instructed opened Radio and used File Open... on the downloaded file. The instructions http://tweezersedge.com/archives/2003/08/000090.html say a box will open, (it didn't) and later it mentions a compile option. I can't find one.

I guess I'm missing something basic.

Any help appreciated,

Regards,

ian.

I would like to add the archive links tool so I downloaded workspace.monthlyArchiveLinks.ftsc.txt.

Remove the ".txt" extension from the end of the file name, then reopen the file in Radio.

Thanks for the quick response. I renamed and compiled the file however I have to appologise for being a 'dumb user'. I added to my home page template and now I get the following error.
[Macro error: Monthly Archives are not enabled for this weblog.]

Any suggestions on how to enable the macro ?

Ian.

On the 'Archives' prefs page (Radio Desktop Website - Prefs page, listed under 'Weblog'), you need to check (enable) "Check this box to enable monthly archives." and click the 'Submit' button.

I'm missing something. I downloaded the Monthly Archives link and thought I saved it properly, as per your instructions. I went step-by-step through your configuration instructions listed above and designed the tool as I would like to see it work on my page. When my site renders, I get this message: [Macro error: Can't call the script because the name "monthlyArchiveLinks" hasn't been defined.] I'm doing something wrong - just don't know what.

Regards,

Bob

1) How is the macro being called in the template? Make sure there are no typos there - it should be <%workspace.monthlyArchiveLinks ()%> (with whatever optional parameters you wish to use).

2) Check to see if the macro was stored with the right name in Radio.root:

a) Open the Radio app - Right click on the Radio icon in the system tray and click "Open Radio".

b) In the Radio app, on the menu, click "Window", then "Radio.root".

c) On the menu, click "Outline", then "Collapse Everything".

d) Double-click the little black triangle just to the left of "workspace" in the Radio.root window.

e) See if there is an entry listed under "workspace" named "monthlyArchiveLinks" (exact match).

f) Double-click the little black triangle just to the left of "monthlyArchiveLinks".

g) Make sure the first line of the macro code begins with "on monthlyArchiveLinks" (exact match).

h) Click the Compile button, just in case it wasn't compiled when the macro was installed.

Something should turn up in one of those steps, indicating what the problem is.

OK - you are right - something did turn up. Problem is, when I opened Radio and tried to save the file, it never saved to Radio Root. In fact, I'm apparently not clear on how to save the file into Radio.root. I have tried to save it as per the directions above, and it's nowhere to be found when I open Radio. That's the problem. The system is trying to render a file that doesn't exist. Ugh! I'm using Windows XP and when I use the "open" button in Radio, XP pops up with everything on my computer. So, can you tell me how to save the file directly to the root folder? That will solve my problem. Thanks David.

Bob

You don't save the file directly into Radio - you download a copy of the file and save it to some directory you can find again. Then when you do the 'File, Open' in Radio, Radio reads the downloaded file and imports a copy of it into the main Radio.root file.

To download the file:

1) Right click on the download link and click on "Save Target As...".

2) Pick a directory to save the file in - I would suggest clicking on the large "Desktop" button on the left to select your Windows XP desktop.

3) In the "Save as type" dropdown, select "All Files". (If you leave this as "Text Document", Window XP will download and save the file with the name "workspace.monthlyArchiveLinks.ftsc.txt", and you will need to rename the file to remove the ".txt" from the end of the file name in order for Radio to read it properly.)

4) Click the "Save" button.

To import the file into Radio's Radio.root file:

1) Right-click on the Radio icon in the system notification area (system tray) and click "Open Radio".

2) On the Radio app menu, click 'File', then 'Open...'

3) Click the large "Desktop" button on the left to show files on the desktop.

4) Select the "workspace.monthlyArchiveLinks.ftsc" file and click "Open".

5) You should see a box that asks "Name for imported object?" with "workspace.monthlyArchiveLinks" already filled in. Click "OK".

6) You will then see a window with the code in it. Click the "Compile" button at the top of the code window. Close the window by clicking the "X" in the upper right-hand corner.

At this point, the macro is installed (saved) in Radio.root and you should be able to use the macro in your templates.

Hope this helps...

OK - Now I know what the problem is. The box that asks "Name for imported object?" doesn't come up. A box comes up with the text in it and the name of the file with an OPML extension. After I close the window, nothing happens, which leads me to believe that the file is not saved to the system. Indeed, when I follow the previous procedure and check Radio.root, there is nothing there. In other words, Steps 5 and 6 don't happen.

I know this must be frustrating to you. Know that I do appreciate your help.

Bob

Bob,
Do you know where you saved the file? I am assuming you took David's suggestion and saved it to your Desktop. Do you see the file on your Desktop? Right-click on the file once and read the file name, it should read "workspace.monthlyArchiveLinks.ftsc". If it doesn't, go ahead and rename the file that way.

1)Then go to your Radio Application icon (right hand corner of your PC window by the clock) and right click to "open radio". This will open the Radio Application Window.

2)At the Menu Bar, Click File-->Open-->Desktop-->workspace.monthlyArchiveLinks-->open

3)At this point you should see the box that asks "Name for imported object?" with the file name already filled in click "OK".

4)You will then see a window with the code in it. Click the "Compile" button at the top of the code window. Close the window by clicking the "X" in the upper right-hand corner.

At this point, the macro is installed (saved) in Radio.root and you should be able to use the macro in your templates.

Rhye - appreciate the help, but it doesn't work. When I try to import the file into Radio, it automatically assigns it as an .opml file. I get no dialog box and the macro still isn't showing up in Radio.root. I must have tried saving this thing a hundred times today. I'm about to give up on it. I have followed all these instructions to the letter and no results. I'm not the dullest tool in the shed but this is making me feel poorly - and it's time-consuming as well. In short, Radio does not give me a dialog box with a "compile" button -- at all!

I saved the file as workspace.monthlyArchiveLinks.ftsc on the desktop, opened Radio and followed the instructions. The text is not imported, per se (no dialog box appears), but appears in a box with an .opml extension on the end. I then close the windown and there is nothing. Was this saved (if so, this file has been saved many times today). I may have to try something else.

Bob

Persistence is everything. Finally got the thing saved to Radio.root. Thanks David and Rhye for your help. :-)

Bob

Dear TweezerMan Dave..

I just downloaded, installed and used your macro.
It installed and worked PERFECTLY first time.
I just wanted to let you know that.
Thank you.

Pete

Hi Tweezerman,

I would like to download your macro, but I think I would do better with a weekly archive, rather than a monthly archive. I tend to put pictures up almost every day, sometimes several pictures/day and I think a monthly archive will be cumbersome to load. Is there a way to adapt this for a weekly archive, or am I being to squeemish about the size of the files?

thanks,
lulu

http://voodoolulu.com/blog

Hi -

It's lulu again. I'm wondering if you think some kind of weekly archive script will be available any time soon, or if I should just go ahead and download the macro for the monthly archive. Not trying to rush you, just wondering what you think.

Thanks so much,
lulu

lulu - I can't say whether your weblog would be better off using monthly archives or weekly archives. Only you can answer that question.

The Monthly Archive Links macro cannot be "adapted" to produce weekly archive links. Significant parts of it would just have to be rewritten.

I never said I was writing any sort of weekly archive links script, so as to whether I think there will be such a script available any time soon, the answer to that would be "No". I'm not involved in writing things for Radio any more, so it is very unlikely I will ever write one either.

I've been working on the same task as Bob and thank TweezerMan and Rhye for giving advice that has also guided me along the way as I have "missed" seeing elements such as "Name for imported Object" and "Compile." I have it downloaded, and I see the macro in a code window inside of Radio as you described, but I didn't get that last step of getting it saved...looks like Bob may have found these options or got it saved somehow but I didn't see that particular step documented...thanks in advance for the help finding compile or how to save the file into Radio (I tried updating the Radio.root without success). I also checked in my Radio.root directory but didn't find the macro on the workspace listing.

What I'm after is a way to list my previous posts for users to see archives/titles of posts...is this the correct macro?

You should check out the file you downloaded and make sure that it didn't get a ".txt" extension put on the end of it. Radio won't see it as a macro if the file doesn't end in ".ftsc".

It really doesn't sound like this is the macro you're looking for - the Monthly Archive Links macro only displays a list of links to the Monthly Archives, not a list of post titles.

I just installed this (after reading the comment aboutdeleting .txt) and got it running in no time. One minor problem though, the month of May in MMMMYY format is displaying as 'Ma04y'. Also, July is 'Jul04y'. Any easy fix for this? Thanks. You can see the error at my blog: http://radio.weblogs.com/0135731/

I fixed the code that was causing the problem and the updated macro is now available for download.

About this Entry

This page contains a single entry by TweezerMan published on August 20, 2003 10:00 AM.

Finally - A working Monthly Archive macro! was the previous entry in this blog.

1st release of Radio Userland monthly archive links macro is the next entry in this blog.

Find recent content on the main index or look in the archives to find all content.

Powered by Movable Type 6.1.2

MT-Vampire plugin

web hosting by TotalChoice Hosting

Valid XHTML 1.0!
Valid CSS!