Resource Variables

Overview
Resource Variable Syntax
Resource Variable Index
- Variables

Overview

Resource variables are used to represent dynamic data in MHonArc resources. Take the following LITEMPLATE resource setting for example:

<LiTemplate>
<LI><STRONG>$SUBJECT$</STRONG>
<UL><LI><EM>From</EM>: $FROM$</LI></UL>
</LI>
</LiTemplate>

The LITEMPLATE resource defines how each message listing is displayed in the main index page. The $SUBJECT$ and $FROM$ are resource variables. $SUBJECT$ will get expanded to the current message's subject, hyperlinked to the message page. $FROM$ will be replaced with the message's author's name and address.

Some resource variables take arguments. Take the following NEXTLINK resource setting for example:

<LI>Next by Date:
<STRONG><A HREF="$MSG(NEXT)$">$SUBJECT(NEXT)$</A></STRONG>
</LI>

The resource setting uses two resource variables: $MSG$ and $SUBJECT$ . However, an argument is given to each resource variable delimited by ( ). $SUBJECT$ will get expanded to the current message's subject^[*]. With the "NEXT" argument, we are instructing MHonArc to use the next message's subject. $MSG(NEXT)$ will get expanded to the next message's filename. Therefore, the above resource value is creating a link to the next message in the archive.

* NOTE

In the two examples given, the replacement value of $SUBJECT$ is different (excluding the variable argument difference). For compatibility of older versions of MHonArc, when $SUBJECT$ is used without any arguments, it will be expanded to the current message's subject hyperlinked to the current message page. If an argument is given to $SUBJECT$ , then the variable will get expanded only to the subject text of the applicable message. NO hyperlink is automatically created.

Resource Variable Syntax

The syntax of resource variables in resources is as follows:

$VARIABLE[[:[N][U][J]][(arglist)]]$
	  ^----------^^---------^ 
         ^-----------------------^

The items in []'s are optional. The "^---^" are used to highlight the nested optional groupings.

Definition of each part:

$

The start of a resource variable. Everything (including line breaks) up to the next $ is part of the resource variable.

VARIABLE

The name of the variable. Variable names are case-sensitive.

:[N][U][J] (optional)

The optional grouping starting with a colon are variable modifiers. The definition of each modifier is as follows:

N: Length specification. MHonArc will clip the expanded text to N if the text length is greater than N.
U: Treat the text as part of a URL string. MHonArc will escape any characters that are considered special in a URL.
J: Treat the text as a JavaScript string. MHonArc will escape any quote characters so the text can be part of a JavaScript string.

(arglist) (optional)

An optional argument list delimited by parentheses: ( ). Some resource variables can take arguments which modify how the variable is expanded. If a variable can take more than one argument, each argument will be separated by a semi-colon. For example: $MSGLOCALDATE(NEXT;%H:%M)$ . In the example, there are two arguments to the $MSGLOCALDATE$ variable: "NEXT" and "%H:%M".

$

The end of a resource variable.

If an unrecognized variable is encountered, it gets replaced with an empty string, and a warning is generated. If a literal "$" is needed, use "$$".

NOTE

The MAILTOURL resource has different rules for variable expansion. If a variable does not exactly match the set of variables available for the MAILTOURL, the variable text will be taken literally as part of the element content. Therefore, a single "$" can be used to represent a "$" character.

Also, variables in the MAILTOURL should NOT have ":NUJ" modifiers. This will prevent the variables from being recognized. MHonArc will automatically treat the replacement value as a part of a URL string.

Resource Variable Index

This sections lists all the resource variables supported by MHonArc. Since many resource variables can take arguments, the following notations are used to represent argument values:

mesg_spec

A message specification determines which message the variable's expanded will be based upon. Possible values are:

Value	- Meaning
`CUR`	- Current message.
`FIRST`	- First message listed in main index.
`LAST`	- Last message listed in main index.
`NEXT`	- Next message by main sort order.
`PREV`	- Previous message by main sort order.
`TFIRST`	- First message listed thread index.
`TLAST`	- Last message listed thread index.
`TNEXT`	- Next message by thread.
`TPARENT`	- Parent message of current thread.
`TPREV`	- Previous message by thread.

"CUR" is the default if nothing is specified for mesg_spec.

idx_page_spec

An index page specification denoting the index page to use when determing the value of the variable. The possible values are:

Value	- Meaning
`FIRST`	- First page of main index.
`LAST`	- Last page of main index.
`NEXT`	- Next page of main index.
`PREV`	- Previous page of main index.
`TFIRST`	- First page of thread index.
`TLAST`	- Last page of thread index.
`TNEXT`	- Next page of thread index.
`TPREV`	- Previous page of thread index.

If no value is given for idx_page_spec, the resource variable's value is undefined.

time_fmt_str

A time format string specifies how a date/time will be printed for a date/time related variable. The syntax of the format string is the same as the conversion specification as defined in the GMTDATEFMT and LOCALDATEFMT resources.

Variables

$A_ATTR$

Arguments:	N/A
Description:	The `NAME` and `HREF` attributes to use in an anchor to link to the archived message. The `NAME` attribute provides a destination location when a message links to the index page.

$A_HREF$

Arguments:	N/A
Description:	The `HREF` attribute to use in an anchor to link to the archived message.

$A_NAME$

Arguments:	N/A
Description:	The `NAME` attribute to use in an anchor for messages to link to the index page.

$BUTTON$

Arguments:	`mesg_spec`
Description:	Button markup linking to a message. The value of $BUTTON$ is determined by the following resources: NEXTBUTTON, NEXTBUTTONIA, PREVBUTTON, PREVBUTTONIA, TNEXTBUTTON, TNEXTBUTTONIA.

$DATE$

Arguments:	`mesg_spec`
Description:	The date of the message.

$DDMMYYYY$

Arguments:	`mesg_spec`
Description:	Message date (according to local time) in dd/mm/yyyy format.

$DOCURL$

Arguments:	N/A
Description:	URL to MHonArc documentation. Value of variable set by the DOCURL resource.

$ENV$

Arguments:	`variable_name`
Description:	The value of the environment variable specified by variable_name. For example, $ENV(HOME)$ would expand to the value of the HOME environment variable.

$FROM$

Arguments:	`mesg_spec`
Description:	The complete text in the `From:` field of the message.

$FROMADDR$

Arguments:	`mesg_spec`
Description:	The full mail address in the `From:` field of the message.

$FROMADDRNAME$

Arguments:	`mesg_spec`
Description:	The username/local-part of the mail address in the `From:` field of the message. For example, given the address "someuser@foo.com", $FROMADDRNAME$ would equal "someuser".

$FROMADDRDOMAIN$

Arguments:	`mesg_spec`
Description:	The domain part of the mail address in the `From:` field of the message. For example, given the address "someuser@foo.com", $FROMADDRDOMAIN$ would equal "foo.com".

$FROMNAME$

Arguments:	`mesg_spec`
Description:	The human name of the person in the `From:` field of the message. If no human name is found, the local-part specified in the mail address is used.

$GMTDATE$

Arguments:	`time_fmt_str`
Description:	Current GMT date. Default format of date set by the GMTDATEFMT resource.

$ICON$

Arguments:	`mesg_spec`
Description:	The context-type sensistive icon. The type of icon displayed is determined by the ICONS resource.

$ICONURL$

Arguments:	`mesg_spec`
Description:	The URL to the context-type sensistive icon. The URL value is determined by the ICONS resource.

$IDXFNAME$

Arguments:	N/A
Description:	Filename of main index page. The value is set by the IDXFNAME or IDXPREFIX and HTMLEXT resources. If the first page, IDXFNAME is used. For other pages, the filename is `IDXPREFIXpage-number.HTMLEXT`.

$IDXLABEL$

Arguments:	N/A
Description:	Label for main index page. Value set by the IDXLABEL resource.

$IDXPREFIX$

Arguments:	N/A
Description:	Prefix of filenames of main index pages. Value set by the IDXPREFIX resource.

$IDXSIZE$

Arguments:	N/A
Description:	Max number of messages that may be listed in index page. Value set by the IDXSIZE resource.

$IDXTITLE$

Arguments:	N/A
Description:	The title of the main index page. Value set by the TITLE resource.

$LINK$

Arguments:	`mesg_spec`
Description:	Link markup linking to a message. Value set by the NEXTLINK, NEXTLINKIA, PREVLINK, PREVLINKIA, TNEXTLINK, TNEXTLINKIA, TPREVLINK, and TPREVLINKIA resources.

$LOCALDATE$

Arguments:	`time_fmt_str`
Description:	Current local date. Default format of date set by the LOCALDATEFMT resource.

$MMDDYYYY$

Arguments:	`mesg_spec`
Description:	Message (local) date in mm/dd/yyyy format.

$MSG$

Arguments:	`mesg_spec`
Description:	Filename of message. Filename of the message is determined by the following resources: HTMLEXT, MSGPREFIX.

$MSGGMTDATE$

Arguments:	`mesg_spec` `mesg_spec;time_fmt_str`
Description:	GMT date of current message.

$MSGID$

Arguments:	`mesg_spec`
Description:	The message-id of the message.

$MSGLOCALDATE$

Arguments:	`mesg_spec` `mesg_spec;time_fmt_str`
Description:	Local date of current message.

$MSGNUM$

Arguments:	`mesg_spec`
Description:	The message number assigned to the message by MHonArc (includes leading zeros).

$MSGPREFIX$

Arguments:	N/A
Description:	Filename prefix for message files. Value set by the MSGPREFIX resource.

$NOTE$

Arguments:	`mesg_spec`
Description:	Message annotation. If annotation text exists for the message, the NOTE resource determines the value of $NOTE$. When no annotation text is defined, NOTEIA is used.

$NOTETEXT$

Arguments:	`mesg_spec`
Description:	Base text of message annotation. Variable should be used only within the NOTE resource.

$NUMFOLUP$

Arguments:	`mesg_spec`
Description:	Number of explicit follow-ups to the message. This number does NOT include subject-based follow-ups.

$NUMOFIDXMSG$

Arguments:	N/A
Description:	Number of message listed for the current page.

$NUMOFMSG$

Arguments:	N/A
Description:	Total number of messages in the archive.

$NUMOFPAGES$

Arguments:	N/A
Description:	Total number of index pages for a given index type.

$ORDNUM$

Arguments:	`mesg_spec`
Description:	The current listing number of the message.

$OUTDIR$

Arguments:	N/A
Description:	Pathname of archive. Value set by the OUTDIR resource.

$PAGENUM$

Arguments:	N/A
Description:	Current index page number.

$PG$

Arguments:	`idx_page_spec`
Description:	Filename of an index page. Value determined by the HTMLEXT, IDXFNAME, IDXPREFIX, TIDXFNAME, and TIDXPREFIX resources. Which resources are in effect depends on the current context.

$PGLINK$

Arguments:	`idx_page_spec`
Description:	Markup linking to a main index page. Value determined by the NEXTPGLINK, NEXTPGLINKIA, PREVPGLINK, PREVPGLINKIA, TNEXTPGLINK, TNEXTPGLINKIA, TPREVPGLINK, and TPREVPGLINKIA, resources. The resource used depends on idx_page_spec and context.

$PGLINKLIST$

Arguments: num;num

Description:

Markup linking to a list of index pages. $PGLINKLIST$ takes two arguments: the first is the number of pages before the current page to create links to; the second is the number of pages after the current page to create links to. If either number argument is prefixed with a 'T', then the list of links apply to the thread index. Examples: $PGLINKLIST(3;3)$ , $PGLINKLIST(T2;T3)$ . The link text for to a give page is the page number.

$PROG$

Arguments:	N/A
Description:	Program name

$SUBJECT$

Arguments:	`mesg_spec`
Description:	The subject text of the message wrapped in an anchor element that hyperlinks to the message.

$SUBJECTNA$

Arguments:	`mesg_spec`
Description:	The subject text of the message without the anchor element.

$TIDXFNAME$

Arguments:	N/A
Description:	Filename of thread index page. The value is set by the TIDXFNAME or TIDXPREFIX and HTMLEXT resources. If the first page, TIDXFNAME is used. For other pages, the filename is `TIDXPREFIXpage-number.HTMLEXT`.

$TIDXLABEL$

Arguments:	N/A
Description:	Label for thread index page. Value set by the TIDXLABEL resource.

$TIDXPREFIX$

Arguments:	N/A
Description:	Prefix of filenames of thread index pages. Value set by the TIDXPREFIX resource.

$TIDXTITLE$

Arguments:	N/A
Description:	The title of the thread index page. Value set by the TTITLE resource.

$TO$

Arguments:	N/A
Description:	The mail address. This variable is only applicable for use in the MAILTOURL.

$TOADDRNAME$

Arguments:	N/A
Description:	The username/local-part of the e-mail address. For example, given the address "someuser@foo.com", $TOADDRNAME$ would equal "someuser". This variable is only applicable for use in the MAILTOURL.

$TOADDRDOMAIN$

Arguments:	N/A
Description:	The domain part of the e-mail address. For example, given the address "someuser@foo.com", $TOADDRDOMAIN$ would equal "foo.com". This variable is only applicable for use in the MAILTOURL.

$TSLICE$

Arguments:	N/A
Description:	A slice of the thread listing relative to the current message. Size of slice determined by the TSLICE resource. Layout appearance of $TSLICE$ determined by TSLICEBEG, TSLICEEND, TTOPBEGIN, TLITXT, TLIEND, TSINGLETXT, TSUBJECTBEG, and TTOPEND resources.

$VERSION$

Arguments:	N/A
Description:	Program version.

$YYYYMMDD$

Arguments:	N/A
Description:	Message (local) date in yyyy/mm/dd format.

00/04/24 00:09:35