MR: Weblog 2.0 | Weblog Macro Outline

Weblog Macro Outline

The following is a complete list of the macros available in the Weblog II plugin.

Some of these macros work outside of a Weblog II page, but more are intended for use in specific templates within a Weblog.

Note that this document is currently incomplete. It doesn't yet list the parameter attributes of the macros, or explain them in any way.

Collapse Outline
Expand Outline

conditional macros
- weblog.channel
  - weblog.channel
    - Description:
    - Operators:
    - Examples:
  - weblog.channel.isCurrent
    - Description:
    - Operators:
    - Examples:
  - weblog.channel.isDefault
    - Description:
    - Operators:
    - Examples:
  - weblog.channel.name
    - Description:
    - Operators:
    - Examples:
- weblog.item
  - weblog.item.categories
    - weblog.item.categories
      - Description:
      - Operators:
      - Examples:
    - weblog.item.categories.length
      - Description:
      - Operators:
      - Examples:
    - weblog.item.categories.name
      - Description:
      - Operators:
      - Examples:
    - weblog.item.categories.value
      - Description:
      - Operators:
      - Examples:
- weblog.request
  - weblog.request.isArchive
    - Description:
      Determine if the current request (the actual page request, based on the path passed to the server) is for a page in the weblog archives.
      
      Any archive request will do, including daily and monthly archives. Also works in the RSS feed.
      
      Again, this is about what page was actually requested, and has nothing to do with what part of the weblog is currently being rendered.
      
      One possible use: to specify different templates to be used for the archives than are used for the main weblog page. Another use: to display certain items on the archive pages but not on the main weblog.
    - Usage:
      This conditional can be used anywhere on the page.
    - Operators:
      None.
    - Examples:
      - 
  - weblog.request.isArchiveDay
    - Description:
      Determine if the current request (the actual page request, based on the path passed to the server) is for a specific day in the weblog archives.
      
      Works in both the HTML version and in the RSS feed.
      
      Again, this is about what page was actually requested, and has nothing to do with what part of the weblog is currently being rendered.
      
      One possible use: to specify different templates to be used for the archives than are used for the main weblog page. Another use: to display certain items on the archive pages but not on the main weblog.
    - Usage:
      This conditional can be used anywhere on the page.
    - Operators:
      None.
    - Examples:
  - weblog.request.isArchiveMonth
    - Description:
    - Operators:
    - Examples:
- weblog.userIsEditor
  - Description:
  - Operators:
  - Examples:
macros
- weblog.addToWeblogForm
  - Description:
    Inserts a form which allows you to post a message to any of your Weblog II pages.
    
    This macro is required in the template for the New Item Form.
    
    When posting a message to a weblog on another conversation, there are two Weblog 2.0 preferences which affect this macro's behavior: Keep Creation Date, and Keep Creator Address
    
    (Set the preferences in the target site, not the message's original site.)
  - Parameters/Attributes:
    - convId
      Optional. Specify that the checkboxes should refer to another converation in the same zone, thus allowing you to post messages to weblogs on other sites. (Messages are copied to the other site.)
    - separator
      Optional. The text that will be used to separate the checkboxes for the weblogs you can post to.
    - formLabel
      Optional. Text that labels the form. Default value is "Add to Weblogs:"
    - showDate
      Optional. true or false. If true, a small text field is included for specifying the date on which the message should appear in the weblog. Default is false.
    - datelabel
      Optional. The text used to label the date field. Default value is "On this date:"
    - buttonText
      Optional. The text used on the submit button. Default value is "Post to Weblog(s)". Unused in edit forms (including the "new item form").
    - omitButton
      Optional. Default is true. If false, then the "omit from default channel" checkbox is left off of the form.
    - omitLabel
      Optional. The label text for the "omit from default channel" checkbox.
    - target
      Optional. If provided, it's used as the form's target (allows you to target a new window, for example)
    - defaultChecked
      Optional. Determines if the checkbox(es) for posting to the weblog should be 'checked' by when the form is first rendered. (When the form is submitted, the new or edited will be posted to any weblogs whose checkboxes are checked.)
- weblog.archiveDatePath
  - Description:
    Creates a date-path that points to a date in the archives of your weblog. Intended for use in links.
  - Parameters/Attributes:
- weblog.bloggerID
  - Description:
  - Parameters/Attributes:
- weblog.calendar
  - weblog.calendar.ctEmptySpaces
    - Description:
    - Parameters/Attributes:
  - weblog.calendar.date
    - Description:
    - Parameters/Attributes:
  - weblog.calendar.dayCssClass
    - Description:
      Returns a class name for a cell in the weblog calendar.
      
      Only works in a Weblog Calendar Day Template.
      
      There are different class names for different types of cells: weekday, saturday, sunday, and the "current day".
      
      Also, a second class name is returned if the day contains any weblog items, which means this cell will contain a link. (So, the final result might be something like "calendarLinked calendarSunday".
      
      The parameters allow you to override any of the default class names.
      
      Note that the default template for calendar days, called "Weblog Calendar Day READONLY," appends "Cell" to the end of the class name returned by this macro. To change that, you must provide your own template for calendar days.
    - Parameters/Attributes:
      - currentDayClass
        Optional. The class name returned if the day being rendered into the calendar is also the "current day" on the weblog. (Allows you to highlight the requested day on the weblog calendar, as a sort of "you are here" marker.)
        
        Default value is "calendarCurrentDay".
      - sundayClass
        Optional. The class name returned for Sundays on the calendar.
        
        Default value is "calendarSunday".
      - saturdayClass
        Optional. The class name returned for Saturdays on the calendar.
        
        Default value is "calendarSaturday".
      - weekdayClass
        Optional. The class name returned for days from Monday to Friday.
        
        Default value is "calendarDay".
      - linkedDayClass
        Optional. The extra class name that is provided when the day contains content and the day cell will therefore contain a link.
        
        Default value is "calendarLinked".
        
        If provided, this class name is included at the beginning of the result, like this: "calendarLinked calendarDay".
  - weblog.calendar.daynum
    - Description:
      Returns the date being referred to for your weblog archives.
      
      The date is typically formatted as a number between 0 and 31, but can be formatted differently. See the format attribute, below.
      
      Number is wrapped in a link tag pointing to that date in the weblog archives, if that day of the weblog has any posted items.
      
      The "current day" (the requested day for the weblog) is normally not linked. This can be changed with the linkCurrentDay attribute, described below.
      
      If a |weblog channel| is being viewed, then the links point to that channel's archives.
    - Parameters/Attributes:
      - format
        Optional. Allows you to specify the formatting used for the date returned by this macro.
        
        Default value is simply "%d", which returns the number of day in the month (1-31).
        
        See the documentation on formatting dates in Conversant for all of the options.
      - lang
        Optional. Specifies the language of the formatting for the date.
        
        Default value is "en", which returns English-formatted dates.
        
        See the documentation on formatting dates in Conversant for all of the options.
      - linkCurrentDay
        Optional. A boolean value ("true" or "false") which specifies whether or not the current day (the "requested" day on the weblog) should get a link.
        
        Default value is "false", which means that the weblog calendar will just show the plain date (usually just the day of the month) for the requested day, rather than a link. Change to true if you want the link.
  - weblog.calendar.days
    - Description:
    - Parameters/Attributes:
  - weblog.calendar.emptySpace
    - Description:
    - Parameters/Attributes:
  - weblog.calendar.monthLink
    - Description:
    - Parameters/Attributes:
  - weblog.calendar.weekdays
    - Description:
    - Parameters/Attributes:
  - weblog.calendar.wrapper
    - Description:
    - Parameters/Attributes:
- weblog.channel
  - weblog.channel.description
    - Description:
    - Parameters/Attributes:
  - weblog.channel.displayName
    - Description:
    - Parameters/Attributes:
  - weblog.channel.name
    - Description:
    - Parameters/Attributes:
  - weblog.channel.searchargs
    - Description:
    - Parameters/Attributes:
- weblog.channelName
  - Description:
  - Parameters/Attributes:
- weblog.copyright
  - Description:
  - Parameters/Attributes:
- weblog.day
  - weblog.day.anchor
    - Description:
    - Parameters/Attributes:
  - weblog.day.date
    - Description:
    - Parameters/Attributes:
  - weblog.day.items
    - Description:
    - Parameters/Attributes:
  - weblog.day.link
    - Description:
    - Parameters/Attributes:
  - weblog.day.path
    - Description:
    - Parameters/Attributes:
- weblog.days
  - Description:
    Renders the 'days' which will appear on the request page of the weblog. (Remember that content on the weblog is grouped by day.)
    
    This macro is typically found in the 'weblog wrapper' template, but that is not required: you can use the weblog.days macro anywhere. You can even use it on a non-weblog page if you specify which weblog it should use.
    
    The standard behavior for this macro is to return the number of days specified in the weblog's page properties (in Conversant's admin area). The page properties also (normally) determine the day and item templates used. However, you can override all of these things with the parameters/attributes provided with the weblog.pageWrapper macro, which can further be overridden here in this macro.
    
    This macro uses 'scope' to figure out the values for any parameters/attributes you don't provide. That is, if you don't specify the value for something as a macro attribute, it checks the values for the weblog.pageWrapper macro if one was used. If the value can't be found there, then it uses the weblog's own page properties. (In the normal case, which is just a request for an actual Weblog II page, everything is just specified by the page settings and you don't even need the flexibility provided by this macro and its many attributes.)
    
    Important: This macro can only run if it knows which Weblog II page you're trying to present. If the macro is used on a Weblog II page, then it will used that page by default. However, if this macro is being used on a non-weblog page, then one of the following must be true:
    - The macro is part of a "weblog wrapper" template (inserted via the weblog.pageWrapper macro), and the weblog.macro wrapper includes the pageId (or path) attribute to specify which page you want to render.
    - This macro includes the pageId (or path) attribute to specify which Weblog II page is being rendered (see the first two attributes in the list, below).
  - Parameters/Attributes:
    - pageId
      Required (unless a weblog page is already in scope). If your site (conversation) has more than one wblog, and a weblog is not already "in scope" (being rendered), use this attribute to specify which weblog should be checked to see if it uses the message.
      
      Format: pageId="conversationName/path/to/weblog/page"
      
      Example from the weblog 2 beta site: pageId="weblog2beta/index". Here, weblog2beta is the name of the conversation, and the Weblog II page is named "index" and can be found right at the 'root level' of the site (it's not in a subfolder).
    - path
      Deprecated.
      
      This is an alternative to the pageId parameter, and is only included for backwards compatibility. Same format as pageId, but without the name of the conversation or the first slash (so, "index" instead of "weblog2beta/index").
    - channel
      Optional.
      
      If included, then only the specified channel will be rendered. Use the channel's "short name" (the URL-friendly name), not the display name.
      
      If omitted, then whatever channel is already 'in scope' will be used instead.
    - format
      Optional. Specify the type of output format being requested.
      
      Current choices are HTML and RSS. If it's not specified anywhere, then HTML is assumed.
    - daysToDisplay
      Optional.
      
      How many days should be included in the output from this macro?
      
      Only affects requests which are not for the weblog's archives (no date was specified).
    - archiveDaysToDisplay
      Optional.
      
      If archives are being requested (meaning, the request includes a date), how many days should be shown?
    - dayTemplate
      Optional.
      
      Specify the name of the weblog day template to use for rendering the days.
      
      Very useful when you want to show different parts of your weblog in different ways. For example, by combining the dayTemplate and the itemTemplate parameters, you could use minimal templates to insert "recent headlines" from your weblog anywhere on your site.
    - daySeparatorText
      Optional.
      
      Specify the text or HTML that is placed between days in the output.
    - itemTemplate
      Optional.
      
      The name of the template used to display the items on each day in the output from this macro.
    - itemSeparatorText
      Optional.
      
      The text or HTML placed between each item in the output.
    - startingDay
      Optional.
      
      How many days back (into the archives) from the original request should this macro start? In other words, if the request was for 2005/12/31, and this value is 5, then it should start 5 days back in the archives so the output would start with 2005/12/26.
      
      This parameter is currently broken, don't use it. It always goes back the specified number of days, even if there are no items on those days.
    - allowCache
      Optional. Boolean value: set to "true" or "false".
      
      This is the master 'caching' switch. Default value is 'true', but it won't even be checked if the weblog.pageWrapper or the page's properties (in the admin area) have disabled caching.
      
      The rest of the caching attributes (see below) are ignored if this value is 'false'.
      
      What is caching? The server will keep a local copy of the 'rendered output' for each day, so that additional requests for those days don't have to be re-rendered. In the cacched copy, all of the macros and resources are already processed, so the server doesn't have to do much of anything.
    - allowGuestCache
      Optional. Boolean value: set to "true" or "false".
      
      Default is true, unless caching is disabled entirely by allowCache.
      
      When the page is rendered for a guest (anyone who hasn't logged in, including crawlers), should the output be cached so that more requests for the same days (by more guests) do not need to be re-rendered? HUGE performance boost.
    - allowMemberCache
      Optional. Boolean value: set to "true" or "false".
      
      Default is true, unless caching is disabled entirely by allowCache.
      
      When the page is rendered for a member (anyone who is logged in, but is NOT an admin), should the output be cached so that more requests for the same days (by members) do not need to be re-rendered? This is great for performance, but make sure you don't have any member-specific or group-specific macros in your templates (all members will see the same cached pages).
    - allowAdminCache
      Optional. Boolean value: set to "true" or "false".
      
      Default is true, unless caching is disabled entirely by allowCache.
      
      When the page is rendered for an admin, should the output be cached so that more requests for the same days (by another or the same admins) do not need to be re-rendered?
      
      It's useful to set this attribute to "false" when you're working on your templates or debugging a problem, so that you can be sure to always see a fresh copy.
    - cacheMinutes
      Optional.
      
      If caching is enabled, for how many minutes should each day be cached (on the server) from when it is first rendered?
- weblog.description
  - Description:
  - Parameters/Attributes:
- weblog.displayName
  - Description:
  - Parameters/Attributes:
- weblog.editButton
  - Description:
  - Parameters/Attributes:
- weblog.findMessage
  - Description:
    Intended for use outside of a weblog, this macro returns the url of a message on a weblog. Ie, it finds the message somewhere in the weblog's archives.
    
    Useful for cross referencing from messages, Bound URL pages, and search results into the message's location in the weblog.
    
    Special use case: it can also provide the item's timestamp. See the "dateOnly" parameter, below.
  - Parameters/Attributes:
    - pageId
      Required (unless a weblog page is already in scope). If your site (conversation) has more than one wblog, and a weblog is not already "in scope" (being rendered), use this attribute to specify which weblog should be checked to see if it uses the message.
    - channel
      Optional. Check only the specified channel for use of the message.
      
      If omitted, and if a weblog channel is already in scope, then the scoped channel will be used.
    - msgNum
      Optional. Specify the message number to test against the weblog.
      
      Overrides the message number already in scope (or "context"). Value can be a message number, or a keyword that indicates a message relative to the message number already in scope. Acceptable relative values are: "next" (next valid message), "prev" (previous valid message), "nextThread" (top of next thread), "prevThread" (top of previous thread), "top" (first message in current thread), "inresponseto" (the message the current message is a reply to).
      
      If omitted, then the message which is already in scope (context) will be used.
    - noValueText
      Optional. Result that is returned if the message is not used on the weblog.
      
      If omitted, and if the message isn't used on the weblog, then an error is returned in the standard  format.
    - includeAnchor
      Optional. Boolean value (true or false). Default is true.
      
      If the message appears on the weblog, should the result include the #anchor portion of the message's URL, so that the url will point directly at the message on the weblog?
    - prefix
      Optional. Default value is the page's 'permalinkFragText' property, as set through Files & Folders in the Admin area.
      
      In permalinks that point into the weblog, the format generally looks like prefix543, where prefix is generally something like "item" or "msg."
      
      (After setting this value in the page's properties editor, there's usually no reason to use anything different in a macro. There may be cases where it's useful, however, so it's included and documented for the sake of completeness.
    - linkText
      Optional. If defined, a full <A> tag is returned, with the href attribute pointing to the url of the message in the weblog, and the text between the <a> tags </a> being the value of this attribute.
      
      If omitted, then only the url or a path is returned. (See the remaining attributes.)
      
      NOTE: If linkText, archivePathOnly and pathOnly are all omitted, then the full URL is returned.
    - archivePathOnly
      Optional. Boolean value (true or false). Default is false.
      
      This attribute is ignored if the linkText attribute is provided.
      
      If set to "true" then only the archive path (the "date" portion of the url) is returned (along with the #anchor, unless includeAnchor is set to false).
      
      Example: If the conversation's URL is <http://www.example.com/mysite/> and the item's full url in the weblog is <http://www.example.com/mysite/news/index/2005/02/20#msg3596>, then the final result would be /2005/02/20#msg3596
    - pathOnly
      Optional. Boolean value (true or false). Default is false.
      
      This attribute is ignored if the linkText attribute is provided, or if archiveDatePath is set to "true".
      
      If set to "true" then the result will be the path of the item within the conversation, starting after the last / in the conversation's URL.
      
      Example: If the conversation's URL is <http://www.example.com/mysite/> and the item's full url in the weblog is <http://www.example.com/mysite/news/index/2005/02/20#msg3596>, then the final result would be news/index/2005/02/20#msg3596
    - dateOnly
      Optional. Boolean value (true or false). Default is false.
      
      This attribute is ignored if the linkText attribute is provided, or if archiveDatePath is set to "true", or if dayPathOnly is was set to "true"
      
      If set to "true" then the result will be the timestamp of the item on the weblog!
      
      Adds support for the standard date-formatting attributes format and lang, so you can format the date however you wish.
      
      Example:  might produce this date: Samstag, 1. April 2006 8:33 PM
- weblog.header
  - Description:
  - Parameters/Attributes:
- weblog.item
  - weblog.item.anchor
    - Description:
    - Parameters/Attributes:
  - weblog.item.body
    - Description:
    - Parameters/Attributes:
  - weblog.item.categories
    - Description:
    - Parameters/Attributes:
  - weblog.item.channels
    - Description:
      Returns a list of weblog channels in which this message appears, based on the categories it is assigned to.
      
      The list can be formatted however you want.
      
      The items in the list can be plain text, links to the channels on the weblog, or dated links to the actual day and channel on which the item appeared. The links can also point to the RSS feed for the channel.
    - Parameters/Attributes:
      - pageId
        Optional. If your site (conversation) has more than one weblog, use this attribute to specify which weblog should be checked for channels. Not necessary when used on a weblog item template, as it will automatically reference the weblog being rendered.
      - preWrapper
        Optional. Text or HTML that is inserted before every item in the resulting list of channels.
      - postWrapper
        Optional. Text or HTML that is inserted after every item in the resulting list of channels.
      - separator
        Optional. Text or HTML that is inserted between every item in the resulting list of channels.
        
        If not specified, a comma and a space is used.
      - categoryFields
        Optional. Advanced users only.
        
        Specify that only a specific set of category fields should be used to construct the list of channels. Separate field names with commas, like this: categoryfields="keywords, technology, people"
      - entifyValues
        Optional.
        
        Causes 'special characters' in channel names to be converted to entities (such as & to &), without affecting anything else in the macro output (such as the wrapper or separator).
        
        Useful when you want to wrap the channel names in html or xml tags, but also want to make sure you're producing valid html or xml. For example, if one of the item's channels is "Food & Drink", and you've wrapped the channel name in RSS category tags, the output will be "Food & Drink".
        
        Just setting entify="true" would cause the wrapper tags to be entified also (so "<category>channel name</category>" would render as "<category>channel name</category>").
        
        Restriction: Only one of entifyValues or urlEncodeValues can be true. If both are true, then entifyValues takes precedence.
      - urlEncodeValues
        Optional.
        
        Similar to setting urlEncode="true", but only affects the channel names, rather than the full output of the macro. (So, it does not affect anything added to the output as a result of the preWrapper, postWrapper, or separator attributes.)
        
        Restriction: Only one of entifyValues or urlEncodeValues can be true. If both are true, then entifyValues takes precedence.
      - format
        Optional. Set to "RSS" and the links will point to the RSS feed.
        
        Ignored if links and datedLinks are both false.
      - datedLinks
        Optional. Set to true if you want links to the channels which point to the most recent day in the archives in which the current item appeared.
      - links
        Optional. Set to false if you don't want the items in the list of channels to link to the channels.
        
        Ignored if datedLinks is set to "true".
      - rel
        Optional. If links are being returned (dated or not), then this value provides a "rel" attribute to those links.
        
        One common rel attribute is "tag", as used by Technorati and other weblog-related applications. Another is "no-follow," which is used by search engines.
        
        Separate multiple values with spaces.
      - noValueText
        Optional. If the item is not in any channels, what text should appear?
        
        If not specified, then nothing (the empty string) is returned.
  - weblog.item.enclosure
    - Description:
      Returns the RSS <enclosure> tag for the first enclosure it finds in the current message.
      
      Only intended for use in the RSS Item template.
    - Parameters/Attributes:
      - None
  - weblog.item.link
    - Description:
    - Parameters/Attributes:
  - weblog.item.permaLink
    - Description:
    - Parameters/Attributes:
  - weblog.item.permaLink_old
    - Description:
    - Parameters/Attributes:
  - weblog.item.postedTime
    - Description:
    - Parameters/Attributes:
  - weblog.item.subject
    - Description:
    - Parameters/Attributes:
  - weblog.item.summary
    - Description:
    - Parameters/Attributes:
- weblog.language
  - Description:
  - Parameters/Attributes:
- weblog.listChannels
  - Description:
  - Parameters/Attributes:
- weblog.newItemForm
  - Description:
  - Parameters/Attributes:
- weblog.owner
  - Description:
  - Parameters/Attributes:
- weblog.pageWrapper
  - Description:
  - Parameters/Attributes:
- weblog.setScope
  - Description:
  - Parameters/Attributes:
- weblog.unsetScope
  - Description:
  - Parameters/Attributes:
- weblog.URL
  - Description:
  - Parameters/Attributes:
- weblog.xmlrpcURL
  - Description:
  - Parameters/Attributes: