Products Downloads Prices Support Company

Functions available in SurgeMail template files

The following functions are available when customizing SurgeMail web page template files. See
Customizing the SurgeMail web template files.
Using functions in SurgeMail web page template files

Function NameParametersDescription
Common general purpose functions
comma 1 Inserts commas between every 3 digits in the given integer. e.g. ||comma(1234567)||=1,234,567
bytes 1 Displays a given integer representing a number of bytes in a nice string using "B" as a suffix for values in bytes. .e.g ||bytes(14500)||=14 KB ||bytes(500)||=500 B
bytes2 1 Displays a given integer representing a number of bytes in a nice string using "B" as a suffix for values in bytes. .e.g ||bytes2(14500)||=14 KB ||bytes2(500)||=500 bytes
kbytes 1 Displays a given integer representing a number of kbytes in a nice string using "B" as a suffix for values in bytes. .e.g ||kbytes(12500)||=12 MB ||kbytes(7500)||=7,500 KB (values less than 10 use the next lower units for improved accuracy)
define 2 Defines a new variable for the duration of this page. You will probably want to enclose each parameter in brackets to prevent variable lookups being done on then. e.g. ||define((test),(hello))|| gives the variable test a value of hello.
append 2 Appends a value/string to an existing variable
define_if 3 If the first parameter is defined (not empty), then the second parameter is assigned a value equal to the third parameter.
display_if 2 This function returns the second parameter or returns empty if the first parameter is not defined.
checked 1 If the given parameter is defined and is not equal to false or 0, then this function returns a value of checked. Useful for specifying the default value of a form checkbox field.
checked_if_equal 2 If the 2 given parameters are equal, then this function returns a value of checked. Useful for specifying the default value of a form checkbox field.
selected 1 If the given parameter is defined and is not equal to false or 0, then this function returns a value of selected. Useful for specifying the default value of a form select field.
selected_if_equal 2 If the 2 given parameters are equal, then this function returns a value of selected. Useful for specifying the default value of a form select field.
longer 2 Returns "true" if the variable is longer than the second paramter characters long. e.g. ||longer(variable_name,5)||
shorter 2 Returns "true" if the variable is shorter than the second paramter characters long. e.g. ||shorter(variable_name,5)||
trim 2 Truncates the first parameter to be no more than the second paramter characters long. e.g. ||trim(variable_name,5)||
trimline 2 Truncates the first parameter to be no more than the second paramter characters long. Additionally truncates the first parameter at the point of any end of line characters.
trim... 2 Truncates the first parameter to be no more than the second paramter characters long. If the first parameter is greater than the given length, it is trimmed to 3 less than the given length and three dots (...) are appended. e.g. ||trim...(variable_name,5)||
trimline... 2 Truncates the first parameter at the first end of line character then applies the trim... function.
first_defined_of variable Returns the first parameter that is defiend (non-empty) out of the given parameters
first_non_zero_of variable Returns the first parameter that is defined and not equal to 0 out of the given parameters
make_not_blank 1 If the given input parameter is defined or not empty, this function returns that value. Otherwise it returns &nbsp; Useful in some tables where if no text is specified between the <td> and </td> values then the border is not drawn.
Time based functions
datetime_format 1 Formats the given time (first parameter in seconds since 1970) according to the formatting string specified in the second parameter.
See http://developer.futuresource.com/xml/strf.htm for a list of formatting strings
e.g. ||datetime_format(1092094440,(%x %I:%M %p))||=10/08/2004 11:34 a.m.
Note - the exact format can differ depending on your current locale settings.
set_locale 1 Sets the current locale to the given parameter. Used for formatting date/time strings with the datetime_format function
time_now 0 The current time in seconds since 1970. Useful for passing to datetime_format function
time_interval_text 1 Converts the given integer into a text description of a time interval. e.g. ||time_interval_text(600)||=5 minutes or ||time_interval_text(601)||=601 seconds
time_interval_text_approx 1 Converts the given integer into an approximate text description of a time interval. e.g. ||time_interval_text(601)||=5 minutes
datetime_long 1 Converts a time in seconds since 1970 into a nice date-time format. e.g Thursday, 21 Janurary 1998 at 5:33 am
date_long 1 Converts a time in seconds since 1970 into a nice date format. e.g Thursday, 21 Janurary 1998
time_long 1 Converts a time in seconds since 1970 into a nice time format. e.g 5:33 am
datetime_short_day_first 1 Converts a time in seconds since 1970 into a nice date-time format e.g 21/1/1998 5:33 am
datetime_short_month_first 1 Converts a time in seconds since 1970 into a nice date-time format e.g 1/21/1998 5:33 am
weekday_name 1 Converts the given integer (in the range 0 to 6, 0=Sunday) into some text representing the day of the week. e.g. ||weekday_name(1)||=Monday
month_name 1 Converts the given integer (in the range 0 to 11) into a month name. e.g. ||month_name(2)||=March
hour_text 1 Converts the given integer (in the range 0 to 24) into some text representing the hour. e.g. ||hour_text(15)||=3 pm
minute_text 1 Converts the given integer (in the range 0 to 59) into some text representing the minutes. e.g. ||minute_text(5)||=:05
month_number_of 1 Converts a time in seconds since 1970 into a month number betwee 0 and 11. e.g. ||month_name(month_number_of(1092093504))||=August
month_date_of 1 Converts a time in seconds since 1970 into a day of month number from 1 to 31
hour_of 1 Converts a time in seconds since 1970 into an hour from 0 to 23
minute_of 1 Converts a time in seconds since 1970 into a minute form 0 to 59
year_of 1 Converts a time in seconds since 1970 into a 4 digit year number
weekday_of 1 Converts a time in seconds since 1970 into a number between 0 and 6 representing the day of the week (0=Sunday)
short_time_of 1 Converts a time in seconds since 1970 into a short time description. e.g. 11am or 1:15pm
Encoding functions
url_encode 1 Encodes the given string for using as a URL. Non alpha-numeric characters are encoded as %XX where XX is their ascii code in hex.
url_encode_new 1 Encodes the given string for using as a URL. Non alpha-numeric and non dot and non underscore characters are encoded as %XX where XX is their ascii code in hex.
web_encode 1 Encodes the given string for displaying on a web page. Characters such as < or > are converted to strings such as &lt; or &gt;
web_encode_multi_line 1 Like web_encode but also converts end of line characters into <br>
string_encode 1 Encodes the given string for use in a javascript string. e.g. " is converted to &#34; and \ is converted to \\
Mathematical functions
mul 2 Returns parameter 1 * parameter 2. e,.g. ||mul(5,6)||=30
div 2 Returns parameter 1 / parameter 2
mod 2 Returns parameter 1 modulo parameter 2 . e,.g. ||mod(50,6)||=2
minus 2 Returns parameter 1 - parameter 2
plus 2 Returns parameter 1 + parameter 2
percentage 2 Displays the first parameter as a percentage of the second parameter e.g. ||percentage(50,200)||=25
Logic control functions
if 1 If the given parameter is defined, continues like an ifdef had returned true
ifnot 1 If the given parameter is not defined, continues like an ifdef had returned true
ifany variable If any of the given parameters are defined, continues like an ifdef had returned true
or variable Returns a value of "true" if any of the given parameters are defined.
and variable Returns a value of "true" if all of the given parameters are defined.
not 1 Returns a value of "true" if the given parameter is not defined
equal 2 Returns a value of "true" if the 2 parameters are equal
less_than 2 Returns a value of "true" if parameter one is less than parameter two.
greater_than 2 Returns a value of "true" if parameter one is greater than parameter two.
equalnc 2 Returns a value of "true" if the 2 parameters are equal doing a case insensitive comparison.
Uncommon general purpose functions
system_slash 1 Converts all slashes (/ or \) in the given parameter into \ on Windows or / on unix machines.
host_name 0 Returns string like http://your.domain.name:7080 . Exact value depends on what URL the user used to access this page.
concatenate variable Concatenates the given parameters into a single string. Useful for concatenating the results of other functions together before parsing the result to another function
form_input 1 Returns the specified form input variable. Note: You must use double brackets to stop name-value replacement of the parameter to this function before the function gets called. e.g. ||form_input((variable_name))||
input_or_output 1 If the specified input variable is not empty, uses that. Otherwise uses output variable of the given name. Note: You must use double brackets to stop name-value replacement of the parameter to this function before the function gets called. e.g. ||input_or_output((variable_name))||
select_options 2 or 3 Generates a list of select options where the first parameter is the default selected value, the second is a list of all possible values, and the third optional parameter specifies the name of a function to convert the numbers into text.
Usage ||select_options(default_index,(index_list),[num-to-text-function])||
Example 1: ||select_options(1,(0,..,3),(month_name)|| generates <option value="0">January</option> <option value="1" selected>February</option> <option value="2">March</option> <option value="3">April</option>
Example 2: ||select_duration_options(15,(5,10,15,30,60,90,120))|| generates <option value="5">5 minutes</option> <option value="10">10 minutes</option> <option value="15" selected>15 minutes</option> ...
txt_size 1 If the users web browser is IE 5, IE 6, Opera or Mozilla 5, returns double the given parameter, otherwise returns the given parameter. Useful for fomatting text input fields with a standard width in different browsers.
repeat 2 Repeats the text of parameter 2 x times (x being parameter 1) e.g. ||repeat(3,(test))||=testtesttest
lang_get 1 Translates the value of the parameter e.g. ||lang_get(test)||
decrypt 1 Decrypts an encrypted authent field i.e. type="encrypt" (non-standard encryption) eg. ||decrypt(field)||