# Formatting Functions

### General

This article will cover the use of functions to format merged values in your templates inside LoanPro. Formatting functions can be used in the following things:

Note that formatting functions can’t be used in SMS message templates because they are stored with Solutions By Text. They also can’t be used in functions that include writing rules, since these only allow Clojure, or in computation fields.

The available formatting functions are:

• formatZipcode()
• formatPhoneNumber()
• formatNumber()
• formatNumberAsText()
• formatNumberAsCheck()
• formatDateTime()
• companyFormatDateTime()
• formatCountry()
• collectionItem()

There are two basic parts to using a function to format merged values: function name and parameters. The function name tells LoanPro which function you want to use to format a merged value. The parameters are data that you are supplying to the function to let it know what to do.

For example, the formatNumber function lets you choose how to format number values. So if we have the number value of 1000 and we want it formatted like 1,000.00, we can do that using the formatNumber function. Like this:

formatNumber(‘1000’, ‘2’, ‘.’, ‘,’)

You can see that first we listed the name of the function “formatNumber”. Next, we enter our parameters inside of parentheses. The parameters are separated by commas. The first parameter is the number we are formatting, in this case 1000. When you really use this function, this will not be a number value like 1000, but will be the name of a variable. The second parameter is the number of decimal places that should be included in the final number. We have chosen 2. The next parameter is the character to use between the ones place and the tenths place. We have entered a decimal point (.). Finally, we have specified the character to use to separate the number at each factor of 1,000. We chose a comma (,).

It’s important to note that parameters must be entered in a specific order. This article will specify the parameters available for each function. It is also important to note that only the first parameter, the number to be formatted, is required for each function. Lets take a look at the different functions and some examples for how to use them.

#### ZIP Code

By default, all ZIP code values are merged into your templates in the format in which they are saved in the database, which saves numeric values ONLY. When nine-digit ZIP codes are merged into your template, they are less readable because they aren’t formatted with a dash.  You can tell LoanPro to format ZIP codes by using the formatZipcode() function.

##### Function Name: formatZipcode()
• Parameter 1: Variable Name (required)
• Parameter 2: Length – This should be either 5 or 9. If you don’t enter a value, the function will use the default of 9.

Example #1

[[formatZipcode(‘tenant-zipcode’)]]

This usage will format the ZIP code with the default length of 9, unless the saved ZIP code is only 5 digits. Assuming our saved ZIP code is 844140123, this example would return a result of 84414-0123. If the saved ZIP code is 84414, then the formatted result would be 84414.

Example #2

[[formatZipcode(‘tenant-zipcode’,5)]]

This usage will force format the ZIP code to 5 digits, regardless of the saved value. Assuming our saved ZIP code is 844140123, this example would return a result of 84414.

#### Phone Number

By default, when phone numbers are merged into your templates, they are merged in as a numeric value with no formatting.  To format the merged value you can use the formatPhoneNumber function.

##### Function Name: formatPhoneNumber()
• Parameter 1: Variable Name (required)

Example

[[formatPhoneNumber(‘company-phone-primary’)]]

When you use this function, phone numbers will be formatted differently depending on their length. If the saved phone number is 7 digits with a value of 7827199 then it will be formatted 782-7199. If the saved phone number is a 10-digit US number with a value of 8017827199, then the resulting format will be (801) 782-7199. If the saved phone number is an international number, longer than 10 digits, with a value of 445568721234 then the resulting format will be “44 (556) 872-1234.

#### Numbers

By default, numeric values are merged into your templates with no formatting, meaning a value of 1,101.99 would be merged as 1101.99.  You can format the merged value using the formatNumber function.

##### Function Name: formatNumber()
• Parameter 1: Variable Name or property name (required). Property name is used for array variables.
• Parameter 2: Number of places after the ones place. This should be an integer value, surrounded by either single or double quotes (e.g. ‘2’). If no value is entered, the default value of 2 will be used.
• Parameter 3: Delimiter character separating the ones and tenths place, surrounded by either single or double quotes (e.g. ‘.’). If no value is entered, the default value of . will be used.
• Parameter 4: Delimiter character separating each 1000x order of magnitude, surrounded by either single or double quotes (e.g. ‘,’). If no value is entered, the default value of , will be used.
• Parameter 5: Iteration number variable $_num. This is only needed for array variables. • Parameter 6: Variable name. This is only needed for array variables. This function does basic formatting of numeric values. Example #1 $[[formatNumber(‘setup-loan-amount’, ‘2’, ‘.’, ‘,’)]]

This usage will format the number as currency. Assuming our loan amount is 95999.11, this example would return a result of 95,999.11.

Example #2

[[formatNumber(‘setup-loan-amount’,’0′,’.’,”)]]

This usage will strip the decimal places from the number (rounding to the whole number) and will strip all thousands-separation characters. Assuming our loan amount is 1,500.91, this example would return a result of 1501.

Example #3

[[BEGIN til-scheduled-payments]][[formatNumber(‘amount’,’0′,’.', ',', \$_num, 'til-scheduled-payments')]][[END]]

This is the proper way to use this function for an array variable. This usage will occur inside a loop.

##### Function Name: formatNumberAsText()
• Parameter 1: Variable Name (required)

This function will format the entire currency value as words including the decimal/cent values.

Example

[[formatNumberAsText(‘setup-loan-amount’)]]

Assuming our loan amount is 95999.11, this example would return a result of “Ninety-five thousand nine hundred ninety-nine dollars and 11 cents“.

##### Function Name: formatNumberAsCheck()
• Parameter 1: Variable Name (required)

This function will format the dollar amount as words, and will format the decimal/cents as a fraction in check format (i.e. 51/100).

Example

[[formatNumberAsCheck(‘setup-loan-amount’)]]

Assuming our loan amount is 95999.11, this example would return a result of “Ninety-five thousand nine hundred ninety-nine dollars and 11/100“.

#### Date & Time

You have the ability to format date and/or time fields in a number of different ways. You can do this by using the formatDateTime() function or the companyFormatDateTime() function.

##### Function Name: formatDateTime()
• Parameter 1: Variable Name (required)
• Parameter 2: Format String – A string that represents the date format you want to use. If you don’t enter a value, the default of ‘Y-m-d’ is used. See examples 1-4 below.
• Parameter 3: Interval -This parameter lets you add or subtract from dates. This parameter is a text string that indicates an amount and unit of time that will be either added or subtracted from variableName parameter. You can use the following units of time: seconds, minutes, hours, days, weeks, months, and years. See examples 5 & 6 below.

This function lets you choose how to format your date and subtract date intervals.

First, lets look at creating a date string. The tables below will show you the values you can use to create a format string. It includes values for Day, Month, Year, and Time.

#### Day

 Character Description Example Results d Day of the month, 2 digits with leading zeros 01 to 31 D A textual representation of a day, three letters Mon through Sun j Day of the month without leading zeros 1 to 31 l (lowercase 'L') A full textual representation of the day of the week Sunday through Saturday S English ordinal suffix for the day of the month, 2 characters st, nd, rd or th. Works well with j

#### Month

 Character Description Example Results F A full textual representation of a month, such as January or March January through December m Numeric representation of a month, with leading zeros 01 through 12 M A short textual representation of a month, three letters Jan through Dec n Numeric representation of a month, without leading zeros 1 through 12 t Number of days in the given month 28 through 31

#### Year

 Character Description Example Results Y A full numeric representation of a year, 4 digits Examples: 1999 or 2011 y A two digit representation of a year Examples: 99 or 11

#### Time

 Character Description Example Results a Lowercase Ante meridiem and Post meridiem am or pm A Uppercase Ante meridiem and Post meridiem AM or PM g 12-hour format of an hour without leading zeros 1 through 12 G 24-hour format of an hour without leading zeros 0 through 23 h 12-hour format of an hour with leading zeros 01 through 12 H 24-hour format of an hour with leading zeros 00 through 23 i Minutes with leading zeros 00 to 59 s Seconds, with leading zeros 00 through 59

Let’s build an example format string. For our example, we will choose to format a date and time like this: September 9, 1999 99:99:99. The first thing to do is find the correct character for month. We will choose ‘F’ because this will give use the full month as text. Next, we will choose the option that will give us a simple numeric day. The correct option is ‘d’. We will choose ‘Y’ for year because it will give a full, four-digit year. For time we will choose ‘h’ for the hour. This is the 12-hour option and not the 24-hour option. For minutes, we will choose ‘i’. Finally, we will choose ‘s’ for seconds.

Now we will need to put our choices together in the correct format. We need to make sure there is a single space between month and day, a comma and a space between day and year, a space between year and hour, and that hour, minute, and second are separated by colons. Our final string will be: ‘F d, Y h:i:s’. You can use a number of characters between the different date/time components (e.g. /, *, -, etc.).

Now let’s look at adding and subtracting with dates. In order to do this, you can use a numeric value and a word that represents an amount of time in order to add or subtract time from a date. The following can be used:

• year
• month
• week
• day
• hour
• minute
• second

You can pluralize these if need be. So, if you wanted to subtract 2 weeks from a date, your interval parameter would be ‘-2 weeks’. You can also use math in your string. So, if you wanted to add a month and two days to a date, your interval parameter would be ‘1 month + 2 days’.

Example #1

[[formatDateTime(‘status-next-payment-date’)]]

This usage will format the number with the default format of YYYY-MM-DD. Assuming our next payment date is July 1st 2015, this example would return a result of 2015-07-01.

Example #2

[[formatDateTime(‘status-next-payment-date’, ‘m/d/Y’)]]

This usage will rearrange the format of the date and use dashes instead of forward slashes. Assuming our next payment date is July 1st 2015, this example would return a result of 07/01/2015.

Example #3

You acquired a loan from Acme Lending Inc on [[formatDateTime(‘setup-contract-date’, ‘l F jS \\o\\f Y’)]].

This is a more complex example used to output a more elaborate date. Assuming our loan contract date is 04/28/2015, this example would return the following result: “You acquired a loan from Acme Lending Inc on Tuesday April 28th of 2015

Note: In this example that we used characters that were not part of the date format to make the word “of”. When we do this we must add a double backslash (\\) before each individual character. This is good way to format your date without having to use the formatDateTime() function twice.

Example #4

[[formatDateTime(‘current-time’, ‘g:i A’)]]

This is an example formatting a time value. This will format the time in 12 hour format appending AM or PM. In this example, if the current time was 17:05:31, the resulting output would be “5:05 PM“.

Example #5

[[formatDateTime(‘setup-first-payment-date’, ‘m/d/Y’, ‘3 days’)]]

This example shows how to add 3 days to the first payment date the result will be formatted as 09/09/1999.

Example #6

[[formatDateTime(‘setup-first-payment-date’, ‘m/d/Y’, ‘-6 days’)]]

This example shows how to subtract 6 days from the first payment date. The result will be formatted as 09/09/1999.

##### Function Name: companyFormatDateTime()
• Parameter 1: Variable Name (required)
• Parameter 2: Interval -This parameter lets you add or subtract from dates. This parameter is a text string that indicates an amount and unit of time that will be either added or subtracted from variableName parameter. You can use the following units of time: seconds, minutes, hours, days, weeks, months, and years.

This function works like the formatDateTime() function, but dates will always be formatted according to your company date setting selection.

Example #1

[[companyFormatDateTime(‘status-next-payment-date’)]]

This usage will rearrange the format of the date to use the format select in your company date setting.

Example #2

[[formatCompanyDateTime(‘setup-first-payment-date’, ‘3 days’)]]

This example shows how to add 3 days to the first payment date the result will be formatted based on your company date setting.

Example #3

[[companyFormatDateTime(‘setup-first-payment-date’, ‘-6 days’)]]

This example shows how to subtract 6 days from the first payment date. The result will be formatted based on your company date setting.

You can also format dates that are used inside array variable loops. For more information, see the article on working with variables.

#### Country

##### Function Name: formatCountry()
• Parameter 1: Variable Name (required)

This function formats the country value to a human-readable format.

Example

When using this function in a form, it should be formatted like this: [[formatCountry(‘customer.primary.primary-country’)]]. The double square brackets let the form know you are entering something that shouldn’t be treated like plain text. The output of this function will be either USA or Canada depending on the variable value.

##### Function Name: collectionItem()
• Parameter 1: Variable Name (required)

There are lots of variables that pull a value from one of our collections. These values are typically formatted like this: ‘loan.frequency.monthly’. This doesn’t look good in your forms, so this function will find the human-readable version of the values for these variables and merge them into your forms.

Example

[[collectionItem(‘setup-payment-frequency’)]] will merge in “Monthly” instead of the default value of “loan.frequency.monthly”.

#### Nested Functions

It is possible to nest one function inside another. This works in HTML with the evalFormula() function. For example, if you want to enter a formula into the form and then have the result formatted, you could do something like this: [[formatDateTime([[evalFormula('(u/date-+ status-next-payment-date 5)')]], 'dS', '')]]. This will evaluate the formula which will output a date string that is 5 days after the next payment due date on the loan. The formatDateTime() function will then format it as the numeric day of the month followed by an ordinal suffix (e.g. st, nd).