Phorm™ v3.5.2
Copyright © 2005 Holotech Enterprises.
Formatting Your Data:
Phorm includes a number of built-in data-formatting functions. These functions are called
from your configuration file. The functions, with examples, are described below.
ArrayToList
This function converts a PHP array to a list. This is useful for CHECKBOX and SELECT
MULTIPLE inputs which must be passed from your form as an array (see Multi-value Form Fields in Appendix A for details). The function has three parameters:
ArrayToList($Array, $Separator, $Conjunction);
Only the first parameter is required: it is the array to convert to a list. The second
parameter specifies the separator to put between the elements of the list. If it is not
set, it defaults to comma-space. The third parameter specifies a conjunction to be placed
between the last two items in the list rather than the separator. If not set it defaults
to "and". Examples:
$Colors[1] = "red";
$Colors[2] = "white";
$Colors[3] = "blue";
ArrayToList($Colors);
$Colors is converted to a string containing "red, white and
blue".
$Option[1] = "widget";
$Option[2] = "warble";
$Option[3] = "wotsit";
ArrayToList($Option, ", ", "or");
$Option is converted to a string containing "widget, warble or
wotsit".
$Country[1] = "US";
$Country[2] = "Canada";
$Country[3] = "Mexico";
ArrayToList($Country, " ", "");
$Country is converted to a string containing "US Canada Mexico";
ArrayToTable
[Requires PHP4]
This function converts a set of PHP arrays to a table. An example of a use for this is
with a multi-line order form, where the lines have been passed as arrays (see Multi-value Form Fields in Appendix A for details). This function can have any number of
parameters; each one is an array which represents one column in the table. The function
will form them into a table for inclusion in an acknowledgement page or email.
If you wish, you can specify either a delimiter or a template file for the function to
use in formatting the table. If so, it must be the last parameter passed to the function.
If you do not specify a delimiter or template, the function returns a plain text table
with tab characters between the columns and line breaks between the rows. Let's suppose
you have an order form with columns Qty, Item and Color; with 1 green Wotsit 1000, and
one blue Wotsit 1000 Turbo, and run through a few quick examples:
$OrderTable = ArrayToTable($Qty, $Item, $Color);
$OrderTable will contain the following:
1»Wotsit 1000»Green
1»Wotsit 1000 Turbo»Blue
To specify a different delimiter besides the tab character, pass it to the function as the
last parameter:
$OrderTable = ArrayToTable($Qty, $Item, $Color, "|");
Which will give you:
1|Wotsit 1000|Green
1|Wotsit 1000 Turbo|Blue
You can turn a delimiter into a "super delimiter" if you wish. What this means is that it
will be expanded where necessary to make sure the columns line up on all rows. To create
a "super delimiter", put >> before it:
$OrderTable = ArrayToTable($Qty, $Item, $Color, ">> ");
Now $OrderTable will contain the following:
1 Wotsit 1000 Green
1 Wotsit 1000 Turbo Blue
This is useful when including the table in a text message such as an email.
Rather than just specifying a delimiter, you can create your own template to represent one
row of the table. Most usually this would be a row of an HTML table, but you can do
whatever you wish. Indicate where the colums go, by placing column numbers in double
brackets; for example {{1}} for column 1. Simply create the template in a
plain text file, place it in your templates directory, and pass the file name to the
function like this:
$OrderTable = ArrayToTable($Qty, $Item, $Color, "||ordertable.txt");
(Note the || before the file name.) Assuming your template looked like this:
<TR>
<TD>{{1}}</TD>
<TD>{{2}}</TD>
<TD>{{3}}</TD>
</TR>
Then $OrderTable will contain this:
<TR>
<TD>1</TD>
<TD>Wotsit 1000</TD>
<TD>Green</TD>
</TR>
<TR>
<TD>1</TD>
<TD>Wotsit 1000 Turbo</TD>
<TD>Blue</TD>
</TR>
As mentioned above, if you pass multiple arrays to this function, it regards each
one as a column. If you pass only one array to this function, each element of that
array should be an array itself, and represent a row in the table. This is
useful, for example, in formatting results returned by the DBFetch or DBQuery
plugins. All other options and operations of the function remain as described above.
Examples of the use of this function can be found in the Wotsit Order and Hawaiian
Fountains examples in the Phorm distribution.
UpperCase
This function converts a string to all upper-case characters. Non-letter characters are
not affected. It has one parameter, the string to be converted:
UpperCase($String);
LowerCase
This function converts a string to all lower-case characters. Non-letter characters are
not affected. It has one parameter, the string to be converted:
LowerCase($String);
TitleCase
This function converts a string to title case: each word in the string is capitalized (not
true title case, but maybe I'll make it smarter some day). This function has two
parameters:
TitleCase($String, $Separators);
The first parameter is the string to be converted. The second is a list of separators to
indicate word breaks. Any group of letters coming after a character in the list of
separators is considered a word and the first letter is capitalized. If you do not set
this parameter, the default list is space, form-feed, newline, carriage return, horizontal
tab and vertical tab. If you want to add to this list of separators, put a + at the
beginning of your list. For example, to use the default separators:
TitleCase($String);
To use your own list of separators:
TitleCase($String, " -=");
In the above example, any group of letters coming after a space, hyphen or equal sign will
be considered a word. To use the default separators plus your own:
TitleCase($String, "+-=");
This example will use the default separators, plus hypen and equal sign.
TrimSpace
This function trims blank space from the beginning and end of a string. Characters
considered blank space are space, form-feed, newline, carriage return, horizontal tab and
vertical tab. It has one parameter, the string to be trimmed:
TrimSpace($String);
LineWrap
This function breaks a string at specified intervals, with recognition of word boundaries.
It has three parameters:
LineWrap($String, $Length, $Break);
The first parameter is the string to be wrapped. The second parameter is the length to
wrap at; if it is not specified, it defaults to 75. The third parameter is the character
or characters to insert. If it is not specified, it defaults to whatever the line break
character is for the system the program is running on: for *nix systems it's LF
(linefeed); for Macintosh systems it's CR (carriage return); for Windows systems it's
CRLF.
The string will be wrapped to the specified width, splitting only on a space or hyphen.
SayNumber
This function converts a number from digits to words. For example, 300 becomes "three
hundred". It has two parameters:
SayNumber($Number, $Punctuation);
The first parameter is of course the field with the number to convert. The second
parameter is optional, and specifies what punctuation to use. It can contain any
combination of hyphen (-), comma (,) and caret (^).
If it contains a hyphen, then hyphens will be used between tens and ones. If it
contains a comma, then commas will be used between groups of three digits. If it
contains a caret, the words will be capitalized. This parameter is optional; the
default is the hyphen. Examples:
$Total = 34851;
SayNumber($Total);
SayNumber($Total, "-,");
SayNumber($Total, "-,^");
SayNumber($Total, ",^");
This function only handles whole numbers — decimal points will be ignored.
The largest number it can convert is 999,999,999,999,999,999,999
ParseName
This function parses a person's name — analyzes it and breaks it into parts. It
has two parameters:
ParseName($Name, $VariablePrefix);
The first parameter is, of course, the field containing the name to be parsed.
The function is able to recognize five name parts: prefix (Mr., Ms. Dr., etc),
first name, middle name (or initial), last name, and suffix (Jr., Sr., III, etc.)
These parts are put into variables created by the function. The variables are
$Prefix, $FirstName,
$MiddleName, $LastName and
$Suffix. If any of these name parts is missing, its
corresponding variable will be empty.
The second parameter is optional, and specifies a prefix to add to the variable
names. For example, if you specify 'f2_', the first name will be in the variable
$f2_FirstName. This is useful if you are parsing more
than one name on a form.
$Name = "Mr. Brian Russell De Palma, Jr."
ParseName($Name);
ParseName($Name, "P1_");
0101000001101000011011110111001001101101010010010111001101000011011011110110111101101100