Counter Macro

This is a very simple macro. It just returns a number indicating how many times the macro has been called on the current page.

That's an important distinction: this is not a "web counter," it doesn't tell you how many times a page has been viewed. (Conversant already has enough ways to do that, at least with messages.)

Every time a page is requested, the counter starts over at zero, so in other words it's an "in-page counter."

Usage

<!--#counter name="any name" lastValue="true/false"-->

There are two optional parameters for this macro:

• name lets you have more than one counter working on the page. If you provide a name for your counter, then only the counter with that name is incremented and returned. So you could have a counter named "foo" and a counter named "bar" which are used in different places on the page, operating independently of each other.
• lastValue must be set to either true or false, but the default is false. If set to true, then that instance of the macro will return the most recent value of the counter, without incrementing it. So if the counter's current value is 3, you could use the macro a dozen more times with "lastValue" set to true and the result will still be 3. (Generally, you won't need this feature. We imagined some obscure situations where it could be useful, so we included it.)

Example

Here the macro is used three times:
<!--#counter--> - <!--#counter--> - <!--#counter-->

Which produces these results:
1 - 2 - 3

See? The first time it returns 1, then 2, then 3.

Discussion

This macro is expected to be useful within templates and macros which generate content, especially a "list" of content or anything in a series. Two easy examples are: within automatically generated paragraph tags, and within search results.

In the paragraph tags, you could use this macro to give every paragraph its own id, which would then give you an easy way to refer to specific paragraphs within the page, like this:

<p><!--#msgbody htmlSeparatorText="</p><p id=\"p<!--#counter-->\">"-->

... which says "put the message body here, and replace double-spacing with these paragraph tags." Every time it adds another paragraph tag it runs the macro again, and so each paragraph gets a unique id.

(The same could be done with anchor tags, to produce paragraph anchors like <a name="p1"></a>.)