Help Center>Foundation Help

Applies to:

  • Winshuttle Foundation

Global helper functions

JavaScript reference guides

Global helper functions are discreet functions generally used to manipulate data in fields, and perform tasks such as converting text from upper case to lower case, averaging a set of values, returning the number of values in a repeating group, etc. These are functions you would be more likely to use if you were writing your own JavaScript code to achieve a specific function that is outside the capabilities of functions constructed through the Winshuttle Composer graphical user interface.

Click a function below to view a description, parameters, and a basic code sample.

addDays(date, days, ignoreWeekends)

Back to top

Returns a new Date object containing a specified Date value with a specified number of days added.

Parameters
  • dateValue – Date object containing original date
  • days – Number of days to add to the original date
  • ignoreWeekends–whether or not to ignore weekends (Sat/Sun). Set to True or False.
Example

var date = addDays(today(), 10, false);
jQuery.alert('10 days from now is: ' + date);

addSeconds(dateValue, seconds)

Back to top

Returns a new Date object containing a specified Date value with a specified number of seconds added.

Parameters
  • dateValue – Date object containing original time
  • seconds – Number of seconds to add to original time
Example

var rightNow = new Date();
var later = addSeconds(rightNow, 60);
jQuery.alert('60 seconds from now it will be: '+ later);

avg(field)

Back to top

Returns the average (sum/count) of numeric values in a repeating group bound to the specified field.

Parameters
  • field – XPath of a numeric field in a repeating group
Example

var avgCost = avg('/my:myFields/my:Repeating_Table_2/my:Repeating_Content/my:Cost');
jQuery.alert('Average cost is: ' + avgCost);

ceiling(value)

Back to top

Returns the smallest integer greater than or equal to the given number value (see the JavaScript Math.ceil() function).

Parameters
  • value – Numeric value to perform ceiling operation on
Example

var decVal = $form.getValue('/my:myFields/my:decimalField');
var intCeil = ceiling(decVal);
jQuery.alert('Ceiling of ' + decVal + ' is: ' + intCeil);

concat()

Back to top

Returns a new string of all arguments concatenated together. If the argument specified an XPath value the value of the field referenced will be used. If the XPath references a repeating group, it will return a concatenation of all values in the repeating group.

Parameters

Variable number of arguments to concatenate together. If an argument contains an XPath, its form value will be substituted. If the XPath refers to a repeating section, it will concatenate all values of the field within the repeating section.

Example

var lStr = concat('/my:myFields/my:Repeating_Table_2/my:Repeating_Content/my:Text');
jQuery.alert('Concatenated value: ' + lStr);

contains(text,find_text)

Back to top

Returns true if the string value specified by find_text is found within the string value specified by text.

Parameters
  • text – String to test contents of
  • find_text – String to search for within text
Example

if (contains($form.getValue('/my:myFields/my:field_1', 'Needle')) {
jQuery.alert('Found Needle in the field');
}

count(fieldname, [regex])

Back to top

Returns the number of values in a repeating group.

Parameters
  • field – XPath of a field in the repeating group
  • regex (optional) – A regular expression to return the number of matching instances.
Example

var rCount = count('/my:myFields/my:Repeating_Table_2/my:Repeating_Content/my:Cost');
jQuery.alert('Number of items in table is: '+rCount);

diffDays (date1, date2, weekdaysOnly)

Back to top

Returns the number of days between two dates with an option to only include weekdays (No weekends)

Parameters
  • date1 – Date object containing start date
  • date2 – Date object containing end date
  • weekendsOnly – whether or not to ignore weekends (Sat/Sun). Set to True or False.
Example

var date1 = $form.getValue('/my:myFields/my:dateField_1');

var date2 = $form.getValue('/my:myFields/my:dateField_2');

var days = diffDays(date1, date2, false);

The variable "days" will contain the number of days between the two dates (including weekends).

first(field)

Back to top

Returns the first value of specified XPath in a repeating group.

Parameters
  • field – XPath of a field in the repeating group
Example

var fItem = first('/my:myFields/my:Repeating_Table_2/my:Repeating_Content/my:Title');
jQuery.alert('First item in table has the Title: '+fItem);

floor(value)

Back to top

Returns the largest integer less than or equal to the given number value (see the JavaScript Math.floor() function).

Parameters
  • value – Decimal value to perform floor operation on
Example

var decVal = $form.getValue('/my:myFields/my:decimalField');
var intFloor = floor(decVal);
jQuery.alert('Floor of ' + decVal + ' is: ' + intFloor);

formatDate(dateString, pattern)

Back to top

This will allow re-formatting a date string using the provided pattern.

Parameters
  • dateString – A string in the form yyyy-mm-dd or a string representing an RFC2822 or ISO 8601 date (other formats may be used, but results may be unexpected).
  • pattern - The patterns to formatting are based on java.text.SimpleDateFormat. See below:
Example

To set a new field to a different date format:

$form.setValue(‘/my:myFields/my:field_1’, formatDate($form.getValue(‘/my:myfields:my:date_field2’), “dd-mm-yyyy”));

Mask

Description

d

Day of the month as digits; no leading zero for single-digit days.

dd

Day of the month as digits; leading zero for single-digit days.

ddd

Day of the week as a three-letter abbreviation.

dddd

Day of the week as its full name.

m

Month as digits; no leading zero for single-digit months.

mm

Month as digits; leading zero for single-digit months.

mmm

Month as a three-letter abbreviation.

mmmm

Month as its full name.

yy

Year as last two digits; leading zero for years less than 10.

yyyy

Year represented by four digits.

h

Hours; no leading zero for single-digit hours (12-hour clock).

hh

Hours; leading zero for single-digit hours (12-hour clock).

H

Hours; no leading zero for single-digit hours (24-hour clock).

HH

Hours; leading zero for single-digit hours (24-hour clock).

M

Minutes; no leading zero for single-digit minutes.
Uppercase M unlike CF timeFormat's m to avoid conflict with months.

MM

Minutes; leading zero for single-digit minutes.
Uppercase MM unlike CF timeFormat's mm to avoid conflict with months.

s

Seconds; no leading zero for single-digit seconds.

ss

Seconds; leading zero for single-digit seconds.

l or L

Milliseconds. l gives 3 digits. L gives 2 digits.

t

Lowercase, single-character time marker string: a or p.
No equivalent in CF.

tt

Lowercase, two-character time marker string: am or pm.
No equivalent in CF.

T

Uppercase, single-character time marker string: A or P.
Uppercase T unlike CF's t to allow for user-specified casing.

TT

Uppercase, two-character time marker string: AM or PM.
Uppercase TT unlike CF's tt to allow for user-specified casing.

Z

US timezone abbreviation, e.g., EST or MDT. With non-US timezones or in the Opera browser, the GMT/UTC offset is returned, e.g. GMT-0500
No equivalent in CF.

o

GMT/UTC timezone offset, e.g. -0500 or +0230.
No equivalent in CF.

S

The date's ordinal suffix (st, nd, rd, or th). Works well with d.
No equivalent in CF.

'…'or"…"

Literal character sequence. Surrounding quotes are removed.
No equivalent in CF.

UTC:

Must be the first four characters of the mask. Converts the date from local time to UTC/GMT/Zulu time before applying the mask. The "UTC:" prefix is removed.
No equivalent in CF.

Named masks

Name

Mask

Example

default

ddd mmm dd yyyy HH:MM:ss

Sat Jun 09 2007 17:46:21

shortDate

m/d/yy

6/9/07

mediumDate

mmm d, yyyy

Jun 9, 2007

longDate

mmmm d, yyyy

June 9, 2007

fullDate

dddd, mmmm d, yyyy

Saturday, June 9, 2007

shortTime

h:MM TT

5:46 PM

mediumTime

h:MM:ss TT

5:46:21 PM

longTime

h:MM:ss TT Z

5:46:21 PM EST

isoDate

yyyy-mm-dd

2007-06-09

isoTime

HH:MM:ss

17:46:21

isoDateTime

yyyy-mm-dd'T'HH:MM:ss

2007-06-09T17:46:21

isoUtcDateTime

UTC:yyyy-mm-dd'T'HH:MM:ss'Z'

2007-06-09T22:46:21Z

getRepeatingValues(field)

Back to top

Returns a JavaScript Array containing all of the values in a repeating group bound to the specified field.

Parameters
  • field – XPath of a field in a repeating group
Example

var vals = getRepeatingValues('/my:myFields/my:Repeating_Table_2/my:Repeating_Content/my:Values');

last(field)

Back to top

Returns the last value of specified XPath in a repeating group.

Parameters
  • field – XPath of a field in the repeating group
Example

var lItem = first('/my:myFields/my:Repeating_Table_2/my:Repeating_Content/my:Title');
jQuery.alert('Last item in table has the Title: '+lItem);

max(field)

Back to top

Returns the largest numeric value in a set of values within a repeating group.

Parameters
  • field – XPath of a numeric field in a repeating group
Example

var high = max('/my:myFields/my:Repeating_Table_2/my:Repeating_Content/my:Cost');
jQuery.alert('Highest cost item is: '+high);

min(field)

Back to top

Returns the smallest numeric value in a set of values within a repeating group.

Parameters
  • field – XPath of a numeric field in a repeating group
Example

var low = min('/my:myFields/my:Repeating_Table_2/my:Repeating_Content/my:Cost');
jQuery.alert('Lowest cost item is: '+low);

normalize_space(text)

Back to top

This will remove all spaces from the “text”.

Parameters
  • text - String to remove spaces from
Example

To automatically remove spaces from an input field:

$form.setValue('/my:myFields/my:field_1',normalize_space($form.getValue('/my:myFields/my:field_1')));

now()

Back to top

Returns a new Date object containing the current day and time.

Parameters

None

Example

var currentTime = now();
jQuery.alert('The time is now: '+currentTime);

number(text)

Back to top

Converts a string to a number value.

Parameters
  • text – string containing a numeric value. If the string does not contain a numeric value, this function will return Number.NaN
Example

var stringVal = $form.getValue('/my:myFields/my:field_1');
var numberVal = number(stringVal);
jQuery.alert('The number value is: ' + numberVal);

nz(value)

Back to top

Returns numeric value of text or 0 if not a number.

Parameters
  • value – string value to convert to number or 0
Example

var nzVal = nz($form.getValue('/my:myFields/my:field_1'));
jQuery.alert('nz() returned: ' + nzVal);

pad(s,length,padChar,side)

Back to top

Returns a new string with length defined by the length parameter. Padding is added to either the left or right (or distributed evenly across both) sides of the string.

Parameters
  • s – string to add padding against
  • length – length of string to be returned
  • padChar – the character to use for padding
  • side – which side of the string to pad (may be: left, right or both)
Example

var paddedStr = pad($form.getValue('/my:myFields/my:field_1'), 20, ' ', 'left');

renderMap(mapname, desc, address, city, state, zip, country)

Back to top

Renders the Map Helper Element by specifying an address. If any argument specified is an XPath, the value of the field referenced will be used.

Parameters
  • mapname – Name of the Map Element (use the same name if the map is used in multiple views)
  • desc – Description of the location that will be displayed when the location marker on the map is selected
  • address – Address of map location
  • city – City of map location (optional)
  • state – State of map location (optional)
  • zip – ZIP Code of map location (optional)
  • country – Country of map location (optional)
Example

This example uses all arguments to specify the map location. These can be any fields defined in the solution (or hard-coded values).

$form.getValue('/my:myFields/my:city',$form.getValue('/my:myFields/my:state', form.getValue('/my:myFields/my:zip’, $form.getValue('/my:myFields/my:country')

This example uses a single field that contains the entire location:

(field winshuttlecorp = "20021 120th Ave. NE, Ste 101, Bothell, WA 98011") renderMap("BothellCorporate", "Corporate Office", $form.getValue('/my:myFields/my:winshuttlecorp', "", "", "", "")

round(value)

Back to top

Returns the value of a number rounded to the nearest integer (see the JavaScript Math.round() function).

Parameters
  • value – Decimal value to perform round operation on
Example

var decVal = $form.getValue('/my:myFields/my:decimalField');
var intRound = round(decVal);
jQuery.alert('Nearest integer of ' + decVal + ' is: ' + intRound);

starts_with(text,find_text)

Back to top

Returns true if the specified string with text begins with the string specified in the find_text parameter. Otherwise it returns false.

Parameters
  • text – String to perform search against
  • find_text – String to check for at the beginning of the 'text' parameter
Example

if (starts_with($form.getValue('/my:myFields/my:field_1', 'Prefix')) {
jQuery.alert('The field does begin with the string Prefix');
}

string(value)

Back to top

Returns a value as a string.

Parameters
  • value – Any JavaScript object to be converted to a string
Example

var currentTime = now();
var stringVal = string(currentTime);
jQuery.alert('string value of currentTime is: '+stringVal);

string_length(value)

Back to top

Returns an integer containing the character length of a string specified by a value.

Parameters
  • value – JavaScript string to obtain the length of
Example

var slen = string_length($form.getValue('/my:myFields/my:field_1');
jQuery.alert('Length of field_1 is: '+slen);

substring(text,pos,count)

Back to top

Returns the characters in a string beginning at the specified location (pos) through the specified number of characters (count) (see the JavaScript String.prototype.substr() function).

Parameters
  • text – String to retrieve a substring of
  • pos – Start position of the substring (Note: The first character of a string is at position 0)
  • count (optional) – Length of substring (if not specified returns all characters after pos)
Example

var substr = substring($form.getValue('/my:myFields/my:field_1', 5);
jQuery.alert('substring of field_1,5 is: '+substr);

substring_after(text,find_text)

Back to top

Returns all characters in a string after the string find_text. If find_text is not found within the string, this function returns the full string specified by text.

Parameters
  • text – String to obtain substring from
  • find_text – String to search for within 'text' parameter
Example

var substrAfter = substring_after($form.getValue('/my:myFields/my:field_1', 'Needle');
jQuery.alert('substring after Needle of field_1 is: '+substrAfter);

substring_before(text,find_text)

Back to top

Returns all characters in a string before the string find_text. If find_text is not found within the string, this function returns the full string specified by text.

Parameters
  • text – String to obtain substring from
  • find_text – String to search for within 'text' parameter
Example

var substr = substring_before($form.getValue('/my:myFields/my:field_1', 'Needle');
jQuery.alert('substring before Needle of field_1 is: '+substr);

sum(field)

Back to top

Returns the sum of numeric values in a repeating group bound to the specified field.

Parameters
  • field – XPath of a numeric field in a repeating group
Example

var total = sum('/my:myFields/my:Repeating_Table_2/my:Repeating_Content/my:SubTotal');
jQuery.alert('Total is: '+total);

today()

Back to top

Returns a Date object containing the current day with the time set to 00:00:00.000

Parameters

None

Example

var todaysDate = today();
jQuery.alert('Today is: ' + date);

toLowerCase(text)

Back to top

This will convert the "text" to all lowercase characters.

Parameters:
  • text – String to be converted to lowercase
Example:

To automatically convert an input field to lowercase:

$form.setValue('/my:myFields/my:field_1',toLowerCase($form.getValue('/my:myFields/my:field_1')));

toUpperCase(text)

Back to top

This will convert the "text" to all uppercase characters.

Parameters
  • text – String to be converted to uppercase
Example

To automatically convert an input field to uppercase:

$form.setValue('/my:myFields/my:field_1',toUpperCase($form.getValue('/my:myFields/my:field_1')));

translate(text,find_text,replace_text)

Back to top

Returns a new string after replacing all occurrences of find_text with replace_text in the string text.

Parameters
  • text – Original string value
  • find_text – Substring to search for within original string
  • replace_text – Substring to replace occurrences of find_text with
Example

var modified = translate($form.getValue('/my:myFields/my:field_1'), 'this', 'that');
$form.setValue('/my:myFields/my:field_2', modified);