I realized this afternoon -- rather unhappily -- that the outline version of the macro list was lieing to everyone. It claimed that it's reference for the very important macro "weblog.addToWeblogForm" was complete, when it actually wasn't complete at all.

Now it is complete. There were quite a few optional macro parameters missing.

On 2/19/05, Brian Carnell said:

>I'd really like a message macro that would let me point to the path of a 
>weblog ii page, and the macro would report back a) whether that message 
>is on that weblog ii page, and b) if so, what date it appears.

How about something like this:

<!--#weblog.findMessage
	pageId="weblog2beta/index"
	linkText="On the Weblog"
	noValueText="This message is not on the weblog."
-->

Which produces: On the Weblog

That will return the full url to the message in the weblog archives, including the #anchor. If the message isn't there, it'll return noValueText if you provide it or an error (in html comments, of course) if you don't.

There are other options, too.

Set linktext="anything here" if you want the result to be an HTML link to the location on the weblog. If you don't set the linkText attribute, then the result will be just a URL (or the result of noValueText, or an error, as describe above).

Set dayPathOnly="true" if you want the result to just be the path to the day in the archives, like /2005/02/18#item1234.

Set pathOnly="true" if you want hte result to just be the path within the conversation, starting at the root of the conversation. So, you'd get back something like "index/2005/02/18#item1234" instead of "http://www.free-conversant.com/myfreesite/index/2005/02/18#item1234".

Set includeAnchor="false" if you don't want it to include the #item1234 portion in the result.

Finally, if you want to link to it on a particular channel, just include channel="theChannelName" in the macro. So the macro might look something like this:

<!--#weblog.findMessage
	pageId="weblog2beta/index"
	linkText="On the Weblog"
	channel="channelNameHere"
	noValueText="Not on the weblog."
-->

That will, of course, check to make sure the message appears on the channel in question before linking to it.

Got all that? :-)

Seth

Though it's a little later than I had planned, I've posted the documentation on the new weblog.listChannels macro.

It includes examples.

Hey actually, looking it over I see that it even reveals a bug in the code.

It's not a serious bug. Three and a half points to the first person to spot the bug.

A long time ago, it was requested that a weblog post's list of categories be linkable to channels. In other words, it should be possible to make each item in the output of #weblog.item.categories (which produces a list of the categories assigned to a weblog post) into a link to the corresponding channel.

Until now, I don't think that was possible.

There are two new attributes: links (true or false) and datedLinks (true or false). The default value for both of them is false (so if you don't specify them, they're treated as false).

If links is "false" (or not specified), then datedLinks is ignored.

If links is "true" and datedLinks is "false" then the category names will be links to the channel's homepage, like news.

If links is "true" and datedLinks is "true" then the category names will be links to the appropriate day in the channel's archives, like news.

See this site's weblog for an example of the macro being used this way: <!--#weblog.item.categories links="true" datedLinks="true"-->

There's a new page of documentation, all about channels and categories. This page didn't go out in email, as it was too long and really needs to be read in the browser.

This is a long page, probably too long. There's a good chance that I'll break it up into five or six smaller pages. So, please don't be overwhelmed by the length of the page.

All comments are welcome, encouraged, solicited, begged.

(If you can, please follow the step-by-step guides.)

• Is it approachable, and useful?
• Is it too technical, or seem like it was written for "someone else?"
• Does it explain what you want to know about categories and channels?
• Do the example screen-shots help? Should there be more, and where/what should they be?
• Does it leave any holes? Is there anything you wish it explained, but didn't?
• Is anything over-explained?

The third page of documentation is ready for your review, and covers the basics of posting to the weblog and understanding the fields on the default weblog posting form:

Posting Messages to Your Weblog

I'm rather pleased with how this page came out, but that doesn't mean it's perfect. As always, your review and comments are needed.

A first pass at the next page in the docs is ready. This page takes you through the process of creating a new weblog from scratch or using the wizard to convert an old weblog.

Please review!

This is just a first pass. I'm a little rushed tonight and didn't get to edit it or really read it through a second time.