Appendices cfx_kmSuite
Programming Reference

Appendix A: Universal Attributes and Functions 
Appendix B: Date Format Strings 
Appendix C: Numeric Format Strings 
Appendix D: The List DELIMITERS Attribute 

Appendix A: Universal Attributes and Functions

Universal attributes supported by ALL functions in ALL modules.
Attribute   Description         Required?
F=  The name of the specific FUNCTION being called. For example, <cfx_kmSystem F=GetTempDir> calls the GetTempDir function in the cfx_kmSystem module. This is the only attribute that is ALWAYS REQUIRED.  YES
V=  The name of a caller VARIABLE. If a name is supplied, the function will store it's output in the named variable. This is an optional attribute because you may not need to save the function output.

If you do NOT specify a variable name, the function output is automatically displayed in the web page. This is a handy simplification. If you only want to display the output, just call the function--no need for variables or any other programming. 		 no
SHOW  As mentioned above, the V= attribute controls whether the function output is displayed immediately or stored in a variable. What if you want to display the output AND save it in a variable? Use V= to specify a variable name and include the SHOW attribute to force the automatic output display. Remember, you only need to use SHOW if you want to display AND save the function output.  no

F=Help

Description
The Help function returns a quick-reference document unique to the specific cfx_kmSuite module, documenting the functions contained in the module.
Returns
HTML help text.
Syntax
  <cfx_kmModule  F=Help  V=variable  SHOW>
Examples
<cfx_kmLocale F=Help>
Result:  <cfx_kmLocale>
Version 2001.06.01
Copyright (c) 2001 by Keith R. Meade
All Rights Reserved
Product of kmWeb.com 

<cfx_kmLocale F=function  V=variable-name  SHOW  ...other arguments>

    F= The REQUIRED function NAME.
    V= Optional name of the variable to hold the function result.
    If SHOW is specified or V= is NOT specified, the function result is
        displayed in the HTML page.
... balance of text omitted ...

F=Version

Description
The Version function returns the version of the given cfx_kmSuite tag. The version is specified as a date string, in the format yyyy.mm.dd, e.g."2000.09.18". Special versions and updates may contain an additional designation following the day number.
Returns
Version as a string.
Syntax
  <cfx_kmModule  F=Version  V=variable  SHOW>
Examples
<cfx_kmLocale F=Version>
Result:  2001.06.01

Appendix B: Date Format Strings.

Many cfx_kmCalendar functions build dates using special formatting information. The format string contains character codes specifying how the year, month, day and/or full date will be output. Here are the format codes:

d   Outputs the day as a number without a leading zero (1-31).
dd   Outputs the day as a number with a leading zero (01-31).
ddd   Outputs the day as an abbreviation (Sun-Sat). The names are determined by the web server settings for the LOCALE_SABBREVDAYNAME locale entries.
dddd   Outputs the day as a full name (Sunday-Saturday). The names are determined by the web server settings for the LOCALE_SDAYNAME locale entries.
ddddd   Outputs the date using the system short-date format. The format is determined by the web server settings for the LOCALE_SSHORTDATE locale entries.
dddddd   Outputs the date using the system long-date format. The format is determined by the web server settings for the LOCALE_SLONGDATE locale entries.
m   Outputs the month as a number without a leading zero (1-12).
mm   Outputs the month as a number with a leading zero (01-12).
mmm   Outputs the month as an abbreviation (Jan-Dec). The names are determined by the web server settings for the LOCALE_SABBREVMONTHNAME locale entries.
mmmm   Outputs the month as a full name (January-December). The names are determined by the web server settings for the LOCALE_SMONTHNAME locale entries.
yy   Outputs the year as a two-digit number (00-99).
yyyy   Outputs the year as a four-digit number (0000-9999).

Some functions accept an output FORMAT string specified as an explicit value. In that case, simply include the above codes in the format string, as desired. An example would be the FORMAT attribute for the LastDateOfMonth function.

<cfx_kmCalendar F=LastDateOfMonth DATE="02/15/2004" FORMAT="yyyy-mm-dd">

Other functions accept FORMAT strings embedded within other attributes, for example, the HTML attributes of the BasicMonth function. In those cases, the embedded format string must be enclosed within caret symbols (^). For example, consider the TD= attribute of the BasicMonth function. TD="<td>Today is: ^dddd^, ^mmm^ ^d^, ^yyyy^" is an HTML attribute with embedded date format strings. Note that the attributes could have been written in simpler form as: TD="<td>Today is: ^dddd, mmm d, yyyy^", with all format specifiers within one string.)

<cfx_kmCalendar F=BasicMonth DATE="11/22/1963" TD="<td>Today is: ^dddd, mmm d, yyyy^">

Appendix C: Numeric Format Strings.

By default, cfx_kmConvert function results are returned as numbers with 2 decimal positions. By specifying a FORMAT attribute, you can change the output to suit your needs.

The format attribute can be any string of characters. For example, you could have the following:

<cfx_kmConvert F=Length VALUE=10 FROM=ft TO=in FORMAT="Have a nice day.">

That would work great and be very friendly. The problem is that the conversion amount wouldn't show up anywhere in the output. To include the actual conversion value, you need to add a numeric formatting code. The code has the following structure:

"% [- [width]] [.prec] type"
 
%   REQUIRED percent sign.
-   Optional hyphen signifying left justification. If the hyphen is specified along with the width, the numeric output value will be left justified is the output area. Right justification is the default.
[width]   Optional value WIDTH. If the formatted value is shorter than the width, it is passed with spaces. If the value is larger, the width is increased so that no digits are left out.
[.prec]   Optional value PRECISION. This determines the number of digits to the right of the decimal. The default is two.
type   REQUIRED value TYPE. The following types are supported:

    e   Scientific notation.
    f   Fixed point decimal.
    g   General. Result is e or f, whichever is shorter.
    n   Number. Same as f, except thousand separators are included.
    m   Money. Not applicable to these conversions.

FORMAT Examples
%.2f   Value is output with two digits to the right of the decimal and no extra padding blanks. This is the default format. If you don't specify the FORMAT attribute at all, this is what you'll get.
%10.1n   Value is output with one digit to the right of the decimal. The integer part of the value will include thousand separators. If needed, the value is padded with blanks (on the left) to make it 10 characters long.
%-10.1n   Same as the previous example, except the value is left-justified within the 10 character length, i.e. padding blanks are added to the right of the value.
%.6e   Value is output using scientific notation, with no more than six digits to the right of the decimal.
FORMAT="%.2f meters"
FORMAT="%.0f degrees Celsius"
FORMAT="Have a nice day. Oh, by the way, the answer is: %.3 feet."

Appendix D: The List DELIMITERS Attribute.

In ColdFusion, the LIST functions treat delimiter sets in a simple way. Any number of delimiters in a row are treated as a single delimiter, e.g. three commas in a row are equivalent to one comma. In fact any run of consecutive delimiters are treated as a single delimiter.

The cfx_kmList functions are intended to provide an alternative to that behavior. However, the changes introduced in cfx_kmList caused the meaning of the DELIMITERS attribute to become ambiguous. Is the attribute a set of individual delimiter characters or should some characters be combined and regarded as single delimiters?

To keep it simple, cfx_kmList always treat the DELIMITERS value as a string of individual delimiter characters. If a list has a run of contiguous delimiters, the delimiters are regarded as separators for empty list items. For example, assuming comma delimiters, the list "a,b,,,e" is a five element list with the 3rd and 4th elements being empty. (ColdFusion would treat it as a three element list.) For a more complex example, assuming a delimiter set = ",;:" , the list "mary,;,had::a,little,lamb" is an eight element list with the 2nd, 3rd and 5th elements being empty.

This new behavior causes the cfx_kmList functions to lose some of the capabilities of the standard CF list functions. That's OK. The intent was not to replace the CF functions, simply to provide an alternative.

To recapture one important part of that lost functionality, an additional change in behavior has been implemented. cfx_kmList functions recognize line terminators (CR/LF) and LINE TERMINATORS ARE *ALWAYS* CONSIDERED TO BE DELIMITERS. Adding CHR(13) and/or CHR(10) to the DELIMITERS value will have no effect (because they're already *in* there). This allows the cfx_kmList functions to be used for text line processing, in similar fashion to the CF functions.

Note that, in order to allow for non-DOS line terminators, any recognizable combination of CR and LF are treated as a line terminator. CR alone, LF alone, CR/LF combined and LF/CR combined are all treated as single terminators. Contiguous runs of CR and/or LF will be interpreted as multiple terminators, in the expected way. "CR/LF/CR/LF/CR/LF" would be three terminators. "LF/LF/LF/LF" would be four terminators, etc.