Customizing SurgeMail template files

# Surgemail template functions

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 Name | Parameters | Description
--- | --- | ---
$ | 1 + formatting | Shortcut multiparameter language translation (kinda similar to lang_get) WARNING: watch for %s etc print specifiers in input string!! e.g. ||$(st_test,user,(foo))|| with $st_test="Hello %s there %s"
lang_get | 1 | Translates the value of the parameter e.g. ||lang_get(test)||
swlang_get | 1 | $$ Language lookup basedon parameter e.g. ||swlang_get(test)||
bit_enabled | 2 | test numeric parameter for bit being TRUE e.g. ||bit_enabled(test,bit)||
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
bytes_simple doesnt use COMMAS! | 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)
bytes_basic | 1 | Displays a given integer representing a number of in a simpler string than above for surgeweb
kbytes_basic | 1 | Displays a given integer representing a number of in a simpler string than above for surgeweb
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
lookup | 2 | Redirected lookup - Uses the string value of the passed variable as the name to lookup another variable
replace | 3 | Replace occurances of a string in a string with another
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.
json_validate | 1 | Makes sure value is valid for json syntax: ie 'A string' or '' (empty value) or ['array','values'] or {'object':'val','var2':'val'} note: note strings should already be escape encoded, if not they get trimmed!
json_validate_int | 1 | Returns a value of 0 if the parameter is blank
json_validate_bool | 1 | Returns a string value of true/false dependant on input if the parameter is blank
json_blank | 1 | Returns a value of "true" if the parameter is blank
utf8_validate | 1 | Makes sure value is valid utf8: note: does not do any ICONV character conversion if not valid for whatever reason - just inserts valid utf8 'unknown' characters
email_address | 2 | Returns valid email address
email_only | 1 | Returns valid email address, e.g. "joe blogs" <joe@here.com> --> joe@here.com
Time based functions
mailtime | 1 | Formats the given time (first parameter in seconds since 1970) into email date header format complete with g_timezone e.g. ||mailtime(1092094440))||=Tue, Aug 10 2004 11:34:00 +1300
datetime_format | 2 | 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
date_basic | 1 (+3 web_variables) | Display the date simplified to time / day of mon / day of mon of year
date_basic2 | 1 (+3 web_variables) | Display the date simplified to time / wkday, day of mon / wkday, day of mon of year
date_full | 1 (+3 web_variables) | Display the full date simplified to time / day of mon / day of mon of year
gmt_offset | 1 (+1 web_variables) | Convert timestamp to surgeweb user localtime
time_interval_text | 1 or 2 | 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 optionally accepts a 2nd parameter "english" to always output the values in english
time_interval_text_approx | 1 or 2 | Converts the given integer into an approximate text description of a time interval. e.g. ||time_interval_text(601)||=5 minutes optionally accepts a 2nd parameter "english" to always output the values in english
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
datetime_long_gmt | 1 | Like datetime_long but result is GMT - use with gmt_offset to offset times to user timezone. e.g Thursday, 21 January 1998 at 5:33 am
datetime_long_gmt_lang | 1 | Like datetime_long but result is GMT - use with gmt_offset to offset times to user timezone. e.g Thursday, 21 January 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
month_name | 1 | Converts the given integer (in the range 1 to 12) into a month name. e.g. ||month_name(2)||=Feb
padzero2 | 1 | Converts the given integer into it's 2 digit representation padded with 0's. e.g. ||padzero2(3)||=03
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
quoted_encode | 1 | Encodes the given string for use in quoted-printable encoded format, i.e. email.
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 \\
header_decode | 1 | decodes 'iso' encoded string to utf8... ?
string_encode_basic | 1 | Encodes the given string for use in a javascript string. e.g. " is converted to \" and \ is converted to \\
web_encode_js | 1 | Encodes the given multiline string for use in a javascript string. e.g. ' is converted to \'; " -> \" , \n -> \\\n , \ -> \\
web_encode_js2 | 1 | Like like web_encode_js but leaves '"' untouched
web_decode_js | 1 | Decodes slash encoded characters
web_encode_hyphen | 1 | Encodes hyphen characters to stop them wrapping
web_encode_dollar | 1 | Encodes dollar characters to allow string to be used in javascript .replace function
show_rcpts | 2 | Converts a text string containing multiple addresses into pretty output
show_rcpts_2 | 2 | Converts a text string containing multiple addresses into pretty output
show_rcpts_2 | 2 | Converts a text string containing multiple addresses into pretty output
show_rcpts_json | 2 | Converts a text string containing multiple addresses into pretty output
fn | 1 + 1 optional | Calls a variety on non "registered functions"
macro | 1 min, upto 3 | Use a separate template file to support a form of macros
next_item | 2 | Trims a list and outputs next item up the list ie "1,2,3,4" + "3" => "1,2,4" + "2"
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
percentage2 | 2 | Displays the first parameter as a percentage of the second parameter e.g. ||percentage(50,200)||=25 displays 0 if second param 0
number | 1 | Returns returns a string with 0 if the input string is non numeric
Logic control functions
if | 1 | If the given parameter is defined, continues like an ifdef had returned true
iftrue | 1 | If the given parameter matches variety of true strings (includes "true" / "yes" / "on" ...), 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.
istrue | 1 | Returns a value of "true" if the given parameter matches variety of true strings (includes "true" / "yes" / "on" / "1" ...)
blank | 1 | Returns a value of "true" if the parameter is blank
HTML formatting helper functions
html_button | 3 | Generates table helper for creating various html buttons eg. ||html_button('btn_id','Reply','menu')||
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_native | 1 | Converts language string to UTF8 native language string e.g. ||lang_native(test)||
decrypt | 1 | Decrypts an encrypted authent field i.e. type="encrypt" (non-standard encryption) eg. ||decrypt(field)||
section | 2 | Includes part of a file. The file parameter is optional. If not included apps.htm is used eg. ||section(section,file)||
instring | 2 | Checks
instringnc | 2 | Checks
template_exit | 0 | Outright stop template processing here
file_exists | 1 | Check for template file existence for conditional inclusion (surgeweb basic)
lib_msleep | 1 | Template based sleep for debugging pretend slow processing and tcp connections
html_begin | 0 | Embed html block (automatically stripping begin & end of line space)
html_end | 0 | End of embedded html block (automatically stripping begin & end of line space)