|
|
Surgemail template functions
The following functions are available when customizing SurgeMail web page template files. SeeCustomizing 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 | 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 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_string | 1 | Makes sure value is valid for json syntax: ie 'A string' or '' (empty value) 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 < or > |
| 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 " 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 |
| if_not | 1 | If the given parameter us not set to true (ie if false or unset etc), continues like an ifdef had returned false |
| 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 / css_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) |