GetStatisticsForIndividuals

Util.FormatString Method

The FormatString method builds a string from a format template and data arguments. This method uses a similar syntax as String.Format in ASP.NET. The FormatString method uses braces {} to indicate the presence of an item to format.

General Syntax:

strFormatted = Util.FormatString "Format Template {0} {1} {2}", argument0, argument1, argument2, ...

Format Item Syntax:
Each format item must be enclosed within braces. You may specify empty braces if you just want to insert the item, or specify a number to specify which specific the item to insert. Additionally, you may specify the encoding to transform the text before inserting it to the formatted string.

{[iIndexArgument[&chEncoding]]}

Index Argument

The index component, also called the argument index, is a number starting from 0 that identifies a corresponding item from the data arguments. That is, the format item whose argument index is 0 formats the first value from the data argument list, the format item whose argument index is 1 formats the second value in the list, and so on.

Multiple format items can refer to the same element in the list of values by specifying the same argument index. For example, you can format (encode) the same argument in HTML and URL by specifying a format template like this:

strArgument = "(x+y) < z"
strFormatted = Util.FormatString("String={0}, Text={0&t}, URL(href)={0&u}, URL={0&U}", strArgument)
' strFormatted = "String=(x+y) < z, Text=(x+y) &lt; z, URL(href)=(x+y)+%3C+z, URL=%28x%2By%29+%3C+z"

Each format item can refer to any argument index. For example, if there are three values, you can format the second, first, and third value by specifying a format template like this: "{1} {0} {2}". A value that is not referenced by a format item is ignored. An error message is displayed if an argument index is outside the bounds of the list of values.

Finally, the argument index is optional. If you specify no argument index, the routine will assume the next argument index. For example, the format template "{0} {1} {2}" is the same as "{} {} {}" or "{} {1} {}".

Encoding

The encoding is handy for transforming a string into a different format. For instance, if you are formatting an URL, you may want to specify the encoding {&u} to transform the text into a valid URL. The FormatString method supports eight different encoding:

Encoding	Description
`{&t}`	Encode the text for HTML output. Any special character reserved by HTML are encoded so the browser displays them as text. Internally, this encoding uses `HtmlEncode`.
`{&u}`	Encode the string to make sure the URL does not contain illegal characters. Internally, this encoding uses `HrefEncode`.
`{&U}`	Encode any non-alphanumeric to produce a valid URL. This is often not necessary, as the `{&u}` encoding does the work and makes the encoded string much easier to read. Internally, this encoding uses `UrlEncode`.
`{&x}`	Encode the string for XML output. XML Encoding is similar to HTML encoding with minor differences such as encoding the new line character into ` ` rather than `<br />`.
`{&X}`	Same as `{&x}` with safe encoding. Again, this encoding is rarely used because XML has built-in Unicode support. You may use this encoding to create an XML file for legacy tools not supporting UTF-8.
`{&j}`	Encode the text for a JavaScript string. Internally, this encoding uses `JavaScriptEncode`.
`{&J}`	Encode the text for a JavaScript string with safe encoding for Unicode characters. For details about JavaScript encoding, please read this.

In the example above, we introduced the encoding with the index argument. For instance, the encoding of "(x+y) < z" produces the following.

Encoding	Encoded result for `"(x+y) < z"`
`{&t} Text`	`"(x+y) < z"`
`{&T} Text`	`"(x+y) < z"`
`{&u} Url`	`"(x+y)+%3C+z"`
`{&U} Url`	`"%28x%2By%29+%3C+z"`
`{&x} Xml`	`"(x+y) < z"`
`{&X} Xml`	`"(x+y) < z"`
`{&j} JavaScript`	`"(x+y) \x3C z"`
`{&J} JavaScript`	`"(x+y) \x3C z"`

Usage:

The benefit of using the FormatString method is to make the code more readable by avoiding mixing text and data arguments. For instance, instead of having:

strName = "Daniel"
str = "Hello " & Util.HtmlEncode(strName) & ", how are you?"

You could have:

strName = "Daniel"
str = "Hello {&t}, how are you?", strName

At first, the benefit may not appear significant, however you will find using a template very handy if you have several data arguments . Another benefit is for translating a report to a foreign language. For instance, you can store the format template in the language dictionary and use FormatString to insert the data argument within the translated text. Here is an example of storing an error message in the dictionary. The error message has two parameters, the file name and the error code. As a coding style, the name starts with fmt for "format template" and the number 2 represents the number of arguments.

<!-- File Dictionary.xml -->
<Dictionary>
	<ReportGenerator>
		<fmt2ErrorFileOpen T="Unable to open file {0} (error code: {1})" />
	</ReportGenerator>
</Dictionary>

In your HTML template, you can use the following:

strFileName = "MyFamilyTree.txt"
nErrorCode = 5
strError = Util.FormatString(LanguageDictionary("fmt2ErrorFileOpen"), strFileName, nErrorCode)
' strError = "Unable to open file MyFamilyTree.txt (error code: 5)"

Later, you can change to the following: <fmt2ErrorFileOpen T="Error {1}: Unable to open file {0}" /> without having to modify the HTML template. If you translate in a foreign language, say French, you may use the following: <fmt2ErrorFileOpen T="L'erreur {1} s'est produite en ouvrant le fichier {0}" />.

No {&h} Encoding?
You may have noticed there is no {&h} encoding. Originally, GenoPro was using {&h} for HTML encoding, however this notation was ambiguous with the HrefEncode. While building the first report templates, GenoPro frequently made the mistake of using the {&h} notation for encoding the href attribute. After all, writing Util.FormatString("<a href='{&h}'>Click Me</a>", strURL) was intuitive, but erroneous because the href attribute must be URL-encoded. As a result, the {&h} notation has been completely removed to eliminate potential mistakes.

strURL = "http://www.mywebsite.com/My Family"
strHyperlink = Util.FormatString("<a href='{&u}'>Click to view my family tree</a>", strURL)
' strHyperlink = "<a href='http://www.mywebsite.com/My+Family'>Click to view my family tree</a>"

Error Handling:
When the FormatString method encounters an error such as an invalid encoding or index argument out of range, an error is displayed to the message log. The returned formatted string is truncated at the error, so you can trace the exact position of the error.

See Also:
Report.WriteFormatted