MHonArc v2.3 -- Resource Variables

# Resource Variables

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.
  `PARENT` | - Parent message by thread.
  `PREV` | - Previous message by main sort order.
  `TFIRST` | - First message listed thread index.
  `TLAST` | - Last message listed thread index.
  `TNEXT` | - Next message by 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 links the messages 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.

`$DATE$`

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

`$DDMMYYYY$`

  Arguments: | `mesg_spec`
  Description: | Message date in dd/mm/yyyy format.

`$DOCURL$`

  Arguments: | N/A
  Description: | URL to documentation.

`$FIRSTPG$`

  Arguments: | N/A
  Description: | Filename of first page of main index.

`$FROM$`

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

`$FROMADDR$`

  Arguments: | `mesg_spec`
  Description: | The e-mail address in the `From:` field of the message.

`$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 username specified in the e-mail address is used.

`$GMTDATE$`

  Arguments: | N/A
  Description: | Current GMT date.

`$ICON$`

  Arguments: | `mesg_spec`
  Description: | The context-type sensistive icon.

`$ICONURL$`

  Arguments: | `mesg_spec`
  Description: | The URL to the context-type sensistive icon.

`$IDXFNAME$`

  Arguments: | N/A
  Description: | Filename of main index page.

`$IDXLABEL$`

  Arguments: | N/A
  Description: | Label for main index page.

`$IDXPREFIX$`

  Arguments: | N/A
  Description: | Prefix of filenames of main index pages.

`$IDXSIZE$`

  Arguments: | N/A
  Description: | Max number of messages that may be listed in index page.

`$IDXTITLE$`

  Arguments: | N/A
  Description: | The title of the main index page.

`$LASTPG$`

  Arguments: | N/A
  Description: | Filename of last page in of main index.

`$LINK$`

  Arguments: | `mesg_spec`
  Description: | Link markup linking to a message.

`$LOCALDATE$`

  Arguments: | N/A
  Description: | Current local date.

`$MMDDYYYY$`

  Arguments: | `mesg_spec`
  Description: | Message date in mm/dd/yyyy format.

`$MSG$`

  Arguments: | `mesg_spec`
  Description: | Filename of message.

`$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.

`$NUMFOLUP$`

  Arguments: | `mesg_spec`
  Description: | Number of explicit follow-ups to the message.

`$NUMOFIDXMSG$`

  Arguments: | N/A
  Description: | Number of message listed.

`$NUMOFMSG$`

  Arguments: | N/A
  Description: | Number of messages in the archive.

`$NUMOFPAGES$`

  Arguments: | N/A
  Description: | Number of index pages.

`$ORDNUM$`

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

`$OUTDIR$`

  Arguments: | N/A
  Description: | Pathname of archive.

`$PAGENUM$`

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

`$PG$`

  Arguments: | `mesg_spec`
  Description: | Filename of an index page.

`$PGLINK$`

  Arguments: | `mesg_spec`
  Description: | Markup linking to a main index page.

`$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.

`$TIDXLABEL$`

  Arguments: | N/A
  Description: | Label for thread index page.

`$TIDXPREFIX$`

  Arguments: | N/A
  Description: | Prefix of filenames of thread index pages.

`$TIDXTITLE$`

  Arguments: | N/A
  Description: | Title of thread index.

`$TSLICE$`

  Arguments: | N/A
  Description: | A slice of the thread listing relative to the current message. Size of slice determined by the TSLICE resource.

`$VERSION$`

  Arguments: | N/A
  Description: | Program version.

`$YYYYMMDD$`

  Arguments: | N/A
  Description: | Message date in yyyy/mm/dd format.