Utility helpers exposed to Velocity templates and server-side JavaScript as the formatter variable. Provides null tolerant type conversion, date and time arithmetic and formatting, number and currency formatting, string and HTML helpers, collection factories and a handful of small services such as random identifiers and translation lookups. A single instance is held in the Milton root context and injected into every template and script data model under the name formatter, so it carries no per request state. Most methods are annotated for GraalJS host access and are therefore callable from .mjs code as well as from Velocity and MVEL.

Group: Managers

---

Properties

---

Methods

debug(Object obs) · newNarrative() · toString(Object o) · toBool(Object o) · toBool(Object o, boolean defaultVal) · toDecimal(Object o, Object places) · toDecimal(Object o, int places, String roundMode) · toDoubleSafe(Object o) · toDouble(Object o) · toDouble(Object o, boolean withNulls) · toInteger(Object o) · toInteger(Object o, boolean withNulls) · toLong(Object o) · toLongSafe(Object o) · toLong(Object oVal, boolean withNulls) · toPath(String s) · getFileName(String s) · getYear(Object o) · getMonth(Object o) · getDayOfMonth(Object o) · getHour(Object o) · getHour(Object o, String timezone) · getMinute(Object o) · getDayOfWeek(Object o) · getDayOfWeekName(Object o) · formatDate(Object o) · formatDateWithLocale(Object o, String localeId) · formatDate(Object o, String timezone) · formatTime(Object o) · formatTime(Object o, String timezone) · formatTimeLong(Object o, String timezone) · formatDateLong(Object o) · formatDateLong(Object o, String timezone) · formatDateTime(Object o) · formatDateWithPattern(Object o, String pattern) · getFirstOfMonth(Object month) · getFirstOfMonth(Object month, String timeZone) · newDate(Object year, Object month, Object day) · calcNextBirthday(Object date) · formatDateTime(Object o, String timezone) · formatDateISO8601(Object o) · formatDateISO8601(Object o, String timezone) · formatAge(Object o) · formatAge(Object o, boolean withTrans) · formatMinsAsDuration(Object o) · formatMinsAsDuration(Object o, boolean numeric) · pad2(long l) · pad(long l, int length) · padWith(String padChar, Object rawVal, int length) · getDateTime(Object o) · getDateTime(Object o, String timezoneId) · toPercent(Object num, Object div) · toPercent(Object num, Object div, int decimalPlaces) · toPercent(Object num, Object div, boolean appendSymbol, boolean withBlanks) · toPercent(Object num, Object div, boolean appendSymbol, boolean withBlanks, int decimalPlaces) · format(Object o) · stripExt(String s) · fileExt(String fileName) · gt(Object val1, Object val2) · gte(Object val1, Object val2) · lte(Object val1, Object val2) · lt(Object val1, Object val2) · eq(Object val1, Object val2) · not(Object o) · htmlEncode(Object ob) · htmlAttEncode(String s2) · htmlAttDecode(String s2) · percentDecode(String s) · percentDecodeSafe(String s) · percentEncode(String s) · between(Object oVal, Object oStart, Object oFinish) · toDate(Object oVal) · toSqlDate(Object oVal) · toSqlTimestamp(Object oVal) · toJodaDate(Object oVal) · parseDateWithPattern(String dateS, String pattern) · parseDateWithPattern(String dateS, String pattern, String timezone) · toHtmlInputValue(String value) · toPlain(String html) · toPlain(String html, boolean includeNewLines) · generateTextFromHtml(String html) · getNow() · getYearStart() · yearStart(Date dt) · monthStart(Date dt, int month) · monthStart(Date dt) · yearEnd() · yearEnd(Date dt) · monthEnd(Date dt, int month) · monthEnd(Date dt) · durationSecs(Object start, Object finish) · durationHours(Object start, Object finish) · durationMins(Object start, Object finish) · durationDays(Object start, Object finish) · durationYears(Object start, Object finish) · getMonthName(Object o) · getMonthName(int i) · getCurrentDateService() · ifEqual(String ifEqual, String ifNotEqual, Object o1, Object o2) · isEqual(Object o1, Object o2) · isNotEqual(Object o1, Object o2) · ifNull(Object val, Object defaultVal) · ifEmpty(Object val, Object defaultVal) · ifTrue(Object bb, Object o1, Object o2) · ifFalse(Object bb, Object o1, Object o2) · newList() · getList() · parseDate(String s) · parseTime(Object o) · sdf(boolean hasTime) · toFloat(Object val) · toBigDecimalSafe(Object val) · toBigDecimal(Object val) · toBigDecimal(Object o, Integer decimals) · calc(ResourceList list) · where(String mvelExpr, ResourceList list) · checked(Object o) · selected(Object o) · checkbox(String name, Object oChecked) · checkbox(String id, String name, Object oChecked) · checkbox(Object oId, String name, Object oChecked, Object oValue) · call(Object o) · bsswitch(Object oId, String name, Object oChecked, Object oValue) · radioEq(String id, String name, String currentValue, String value) · radioEq(String id, String name, String currentValue, String value, String className) · radio(String id, String name, Object oChecked, String value) · radio(String id, String name, Object oChecked, String value, String className) · option(Relational value, Object currentValue) · option(Object value, Object oText, Object currentValue) · option(Object value, Object oText, Object currentValue, Object dataIdValue) · select(String name, Map<Object,Object> data) · select(String name, Object currentVal, Map<Object,Object> data) · select(String id, String name, String htmlClass, Object currentVal, Map<Object,Object> data) · getPort() · isSecure() · getPortString() · profilePicHref(Profile p) · toCsvArgs(String s) · toCsv(Iterable list) · toLineOfVals(Iterable list, String seperator) · toProperties(Map<Object,Object> map) · toCsv(String[] list) · toCsv(Object list) · fromCsv(Object o) · toJson(Object val) · toJson(Object val, int indent) · parseJson(String jsonStr) · parseJson(String jsonStr, boolean throwException) · addDays(Date now, Integer days) · addMilliseconds(Date now, Integer milliseconds) · addYears(Date now, Integer years) · addMonths(Date now, Integer months) · addDays(Object now, Object days) · getDaysBetween(Object from, Object to) · addSeconds(Date now, int seconds) · addMinutes(Date now, int mins) · addHours(Date now, int hours) · getBaseWebsiteUrl() · getBaseWebsiteUrl(Website w) · getCleanedRootDomain(String domainName) · getDomainName(Website w) · getDomainName(Website w, boolean useVersion) · getDomainName(Website w, boolean useVersion, boolean includePort) · getKademiDomainName(Website w, boolean useVersion, boolean includePort) · isNotNull(Object o) · isNull(Object o) · getVersionId(WebsiteBranchResource rf) · daysBetween(Date from, Date to) · endofDay(Date dt) · endOfDay(Date dt) · endofDay(Date dt, String timezone) · endOfDay(Date dt, String timezone) · startOfDay(Date dt) · startOfDay(Date dt, String timezone) · truncate(String s, int max) · truncateToEnd(String s, int max) · newReadonlyList(List list) · newStack() · newArrayList() · newCommonList() · newCommonList(Collection from) · newArrayList(Object[] arr) · newMap() · newSet() · newMapBuilder() · formatBytes(Object o) · formatSecsAsDuration(Object o) · formatCurrency(Object o) · formatCurrency(Object o, String unitSymbol, String unitPosition, Integer numberOfDecimal) · formatCurrency(Object o, Boolean leadingZeros) · formatDecimal(Object o, Integer numberDecimals) · formatMaxDecimals(Object o, Integer numberDecimals) · getStartOfWeek(Date dt) · capitalizeString(Object o) · getCountryCodes() · getCountryCodeOfOrg() · sortByProperty(List list, String propertyName) · sortReverse(List list) · sort(List list) · toggleParamVal(String paramName, String val) · toggleParamVal(String paramName, String val, boolean uniqueParam) · paramSelected(String paramName, String value, String active) · addQueryParam(String href, String paramName, Object paramVal) · getQueryString() · addNum(Object from, Object addAmount) · split(String s, String sep) · split(String s) · splitByAnything(String s) · toList(Object arr) · formatNumeric(Object o, String format) · formatNumeric(Object o) · formatNumericNoDecimal(Object o) · isNumeric(Object o) · isType(Object source, String className) · getSimpleType(Object source) · toBase64String(Object o) · toBase64UrlString(Object o) · fromBase64AsString(String base64) · fromBase64AsByteArray(String base64) · toBigInteger(String val, int radix) · joinByteArray(byte[] b1, byte[] b2) · copyFromArray(byte[] arr, int from, int to) · copyFromArray(char[] arr, int from, int to) · byteArrayToHexString(byte[] bytes) · getCrypto() · getGeoIPService() · parseHtml(String html) · formatJodaDate(Object date, String pattern) · formatJodaDate(Object date, String pattern, String timeZone) · formatAsCleanId(String title) · cleanUserId(String userId) · formatPhoneNumber(Object obj, Object phone) · formatPhoneNumber(Object obj, Object phone, String format) · textFromHtml(String htmlContents) · propertyOfObject(Object o1, Object o2) · newTextOptionType(Object placeholder) · newListOptionBuilder() · toPlainEmail(Object o) · textToHtml(String text) · getRandomGuid() · formatUnits(Object o) · encodeAsHtmlEntities(String s) · firstNotNull(Object vals) · firstNotNull2(Object vals) · safeGet(List list, int pos) · safeGet(Object[] array, int pos) · cleanString(Object o) · cleanString(Object o, boolean makePlain) · containsDangerous(String dirtyComment) · paginator() · paginator(int defaultPageSize) · translate(String sourceType, String sourceId, String field, String langCode) · translate(String sourceType, String sourceId, String field) · translate(String sourceType, String sourceId) · translate(Translatable source, String field) · translate(String sourceText) · asUser(Object oUser) · asGroup(Object oGroup) · asWebsite(Object oWebsite) · formatDateWithHyphens(Date dt) · deCamelise(String camelCase) · findDayOnOrBefore(int dayIndex, Date dt) · isEmpty(Object o) · isNotEmpty(Object o) · foreach(Object iterable, BiConsumer consumer) · foreach(Object iterable, ScriptObjectMirror r) · _foreach(Object[] arr, BiConsumer r) · _foreach(Iterable it, BiConsumer r) · breakForeach() · stringJoin(List<String> list, String separator) · parseDateISO8601(String s) · dateTimePattern(String context) · datePattern(String context) · andClause(Object a, Object b) · orClause(Object a, Object b) · parseExtraFieldDef(String name, String fieldDef) · formatToCleanHtml(String original) · parseSearch(String q) · newExtraField(String name, boolean required) · getCurrentRootFolder() · randomInt(Object oRange) · randomHex(int numDigits) · randomAlpha(int numChars) · randomAlpha(int numChars, String excludedCharacters) · normalizeString(String s) · toRanges(Collection originalList, int partitionSize) · splitList(Collection src, int partitionSize) · newTable(String id) · newFormContext() · newFormContext(Map<String,String> params) · newSearchProperties(Integer startPos, Integer pageSize) · newSearchProperties(Integer startPos, Integer pageSize, String orderBy, String orderDir) · newStringBuilder() · newMembershipList() · isImage(String newName, String contentType) · lowest(Object vals) · highest(Object vals) · obfuscateEmail(String email) · convertMapToParamString(Map<String,String> params) · parseParamStringToMap(String params) · link(Object o) · link(Object o, String cls) · link(String href, String text, String cls) · calcGaussianDecay(double elapsedDurationActual, double standardDev, double multiplier) · docsHtml(Object target) · docsText(Object target) · supplyInStopWatch(String name, Supplier r) · runInStopWatch(String name, Runnable r) · lapStopWatch(String name) · replaceText(String source, String findText, String replaceWith) · replaceAllText(String source, String findText, String replaceWith) · checkPathTraversal(String inputString) · toMap(Object source) · toMap(List list, String keyPropName) · standardiseTimezoneId(String timezoneId)

debug(Object obs)

Returns: void

Writes the given values to the server log at info level, prefixed with 'debug:'. Intended as a quick trace aid while developing a template or script; it produces no output in the rendered page.

newNarrative()

Returns: Narrative

Creates a new empty Narrative, the collector object that several services use to report a step by step explanation of a complex operation back to the caller.

toString(Object o)

Returns: String

Null safe conversion to a trimmed string. Returns an empty string for null and for any value that isEmpty considers empty, decodes a byte array using the platform default charset, and otherwise returns the value's own toString with surrounding whitespace removed.

toBool(Object o)

Returns: Boolean

Converts almost anything truthy to a Boolean, or returns null when the value is null or blank. Booleans pass through, an Integer is true when it is not zero, a collection is true when it is not empty, and a string is true when it is 'true', 'yes' or '1' ignoring case and surrounding whitespace. Any other type raises a runtime exception.

toBool(Object o, boolean defaultVal)

Returns: boolean

Converts almost anything truthy to a boolean using the same rules as the single argument toBool, falling back to the given default when the value is null or blank.

toDecimal(Object o, Object places)

Returns: BigDecimal

Converts almost any numeric value to a BigDecimal scaled to the given number of decimal places, rounding half up when rounding is needed.

toDecimal(Object o, int places, String roundMode)

Returns: BigDecimal

Converts almost any numeric value to a BigDecimal at the given number of decimal places, applying the named java.math.RoundingMode when rounding is needed. Accepts BigDecimal, Double, Float, Integer, Long, a numeric string and the search aggregation types KSingleValue and KBucket. Null and an empty string convert to zero, a non-numeric string raises a runtime exception, and an unrecognised rounding mode logs a warning and returns null.

toDoubleSafe(Object o)

Returns: Double

Converts a value to a Double in the same way as toDouble, but returns null instead of throwing when the value cannot be converted.

toDouble(Object o)

Returns: Double

Converts almost any numeric value to a Double. Empty and null inputs become zero rather than null, a boolean becomes one or zero, a NaN Double becomes zero, and a non-numeric string raises a runtime exception.

toDouble(Object o, boolean withNulls)

Returns: Double

Converts almost any numeric value to a Double, choosing whether empty or unconvertible input comes back as null or as zero. With withNulls set, an empty value, a non-numeric string and an unsupported type all return null instead of returning zero or throwing.

toInteger(Object o)

Returns: Integer

Converts almost anything to an Integer by delegating to toLong and narrowing the result, so null and empty values become zero rather than null. Beware that values outside the int range wrap.

toInteger(Object o, boolean withNulls)

Returns: Integer

Converts almost anything to an Integer by delegating to toLong and narrowing the result, choosing whether empty input comes back as null or as zero.

toLong(Object o)

Returns: Long

Converts almost anything to a Long, treating null and empty values as zero so the result is never null. A Date converts to its epoch milliseconds, a boolean to one or zero, and an unsupported type raises a runtime exception.

toLongSafe(Object o)

Returns: Long

Converts almost anything to a Long without throwing, returning null when the value is empty or cannot be converted.

toLong(Object oVal, boolean withNulls)

Returns: Long

Converts almost anything to a Long, choosing whether empty values come back as null or as zero. Handles Long, Integer, Number, BigDecimal, Double and Float including NaN and infinity, Date as epoch milliseconds, Boolean as one or zero, the search types KSingleValue, KBucket and KSearchHitField, a POI RichTextString, the first element of an object array, and strings including 'true', 'false', 'null' and decimal forms.

toPath(String s)

Returns: Path

Parses a slash separated path string such as /a/b/c into a Milton Path object, returning the root path for a null input.

getFileName(String s)

Returns: String

Returns the last segment of a slash separated path, which for a file path is the file name including its extension.

getYear(Object o)

Returns: int

Returns the four digit year of the given Date, read in the server's default timezone. Returns zero for null or for a value that is not a java.util.Date.

getMonth(Object o)

Returns: int

Returns the one indexed month of the given value, so January is 1 and December is 12. A string is matched on its first three letters ignoring case, so 'jan', 'January' and 'JANUARY' all give 1. Returns -1 for null and zero for a value that is neither a recognised month name nor a Date.

getDayOfMonth(Object o)

Returns: int

Returns the one indexed day of the month of the given Date, read in the server's default timezone. Returns zero for null or for a value that is not a java.util.Date.

getHour(Object o)

Returns: int

Returns the hour of the day on a 24 hour clock for the given Date, read in the server's default timezone. Returns zero for null or for a value that is not a java.util.Date.

getHour(Object o, String timezone)

Returns: int

Returns the hour of the day on a 24 hour clock for the given Date, read in the named timezone. Returns zero for null or for a value that is not a java.util.Date.

getMinute(Object o)

Returns: int

Returns the minute within the hour of the given Date, read in the server's default timezone. Returns zero for null or for a value that is not a java.util.Date.

getDayOfWeek(Object o)

Returns: int

Returns the day of the week of the given date like value using the java.util.Calendar numbering, where Sunday is 1 and Saturday is 7. The value is first coerced with toDate.

getDayOfWeekName(Object o)

Returns: String

Returns the English name of the day of the week, such as Monday. Accepts either a date like value, which is resolved with getDayOfWeek, or an Integer already using the Calendar numbering where Sunday is 1 and Saturday is 7.

formatDate(Object o)

Returns: String

Formats the date part only of a date like value, using the short date style of the current organisation's locale and falling back to dd/MM/yyyy when the organisation has no locale set. The time part is discarded.

formatDateWithLocale(Object o, String localeId)

Returns: String

Formats the date part only of a date like value using the short date style of the given locale, falling back to dd/MM/yyyy when no locale is supplied.

formatDate(Object o, String timezone)

Returns: String

Formats the date part only of a date like value as dd/MM/yyyy, after shifting it into the named timezone.

formatTime(Object o)

Returns: String

Formats the time part only of a date like value in the short style of the current tenant organisation's timezone.

formatTime(Object o, String timezone)

Returns: String

Formats the time part only of a date like value in the short style, after shifting it into the named timezone.

formatTimeLong(Object o, String timezone)

Returns: String

Formats the time part only of a date like value in the long style, which includes seconds and the timezone name, after shifting it into the named timezone.

formatDateLong(Object o)

Returns: String

Formats a date like value as a long date and time, such as 4 March 2026 10:15:30 NZDT, in the server's default timezone.

formatDateLong(Object o, String timezone)

Returns: String

Formats a date like value as a long date and time, after shifting it into the named timezone. Falls back to the server's default timezone when no timezone is given.

formatDateTime(Object o)

Returns: String

Formats a date like value compactly as both date and time, in the current organisation's timezone and short locale style, falling back to dd/MM/yyyy HH:mm when the organisation has no locale set.

formatDateWithPattern(Object o, String pattern)

Returns: String

Formats a date like value with an arbitrary Joda date pattern, in the current organisation's timezone. An empty pattern falls back to dd/MM/yyyy.

getFirstOfMonth(Object month)

Returns: Date

Returns midnight on the first day of the given month within the current year, in the server's default timezone.

getFirstOfMonth(Object month, String timeZone)

Returns: Date

Returns midnight on the first day of the given month within the current year, calculated in the named timezone. Note that the month is zero indexed, so January is 0 and December is 11, and that the milliseconds field is not cleared.

newDate(Object year, Object month, Object day)

Returns: Date

Builds a Date at midnight on the given year, month and day, calculated in the current root folder organisation's timezone where one is set. Note that the month is zero indexed, so January is 0 and December is 11.

calcNextBirthday(Object date)

Returns: Date

Works out the next occurrence of a birthday. Accepts a Profile, a ProfileBean or any date like value, takes the day and month from it and returns that anniversary in the current year, or in the following year if this year's has already passed.

formatDateTime(Object o, String timezone)

Returns: String

Formats a date like value as dd/MM/yyyy HH:mm after shifting it into the named timezone. Falls back to the organisation aware single argument formatDateTime when no timezone is given.

formatDateISO8601(Object o)

Returns: String

Formats a date like value as an ISO 8601 timestamp in the server's timezone. Useful for feeding client side relative time widgets such as timeago.

formatDateISO8601(Object o, String timezone)

Returns: String

Formats a date like value as an ISO 8601 timestamp after shifting it into the named timezone. Useful for feeding client side relative time widgets such as timeago.

formatAge(Object o)

Returns: String

Renders how long ago a date like value was in words, for example '4 minutes ago' or 'yesterday', without applying translation.

formatAge(Object o, boolean withTrans)

Returns: String

Renders how long ago a date like value was, or how far in the future it is, in words such as 'Just now', '4 minutes ago', 'a day ago' or 'in 3 weeks'. With withTrans set, each phrase is wrapped in a translation lookup span so the client side translator can replace it.

formatMinsAsDuration(Object o)

Returns: String

Renders a number of minutes as a numeric duration in hours and minutes, such as 1:30 for ninety minutes.

formatMinsAsDuration(Object o, boolean numeric)

Returns: String

Renders a number of minutes as a duration, either numerically as 1:30 or in words as 45mins, 1hr 30 or 3hrs 20.

pad2(long l)

Returns: String

Renders a number as at least two characters, padding with a leading zero, so 7 becomes 07. Numbers of two or more digits are left unchanged.

pad(long l, int length)

Returns: String

Renders a number padded with leading zeros to the given width, so pad(2, 3) gives 002. Numbers already at or over the width are left unchanged.

padWith(String padChar, Object rawVal, int length)

Returns: String

Renders any value as a string with the given character repeated on the left until it reaches the requested width. The value is first rendered with format. Widths above 20 raise a runtime exception.

getDateTime(Object o)

Returns: DateTime

Coerces a value into a Joda DateTime without adjusting the timezone. Accepts an existing DateTime, a Milton Resource whose modified date is used, a date string parsed with parseDate, and anything else the Joda DateTime constructor accepts such as a Date or an epoch millisecond value. Null, an empty string and similar empty values return null.

getDateTime(Object o, String timezoneId)

Returns: DateTime

Coerces a value into a Joda DateTime in the named timezone, giving a mutable friendly date object for further arithmetic. Accepts a DateTime, a Date, an epoch millisecond Long, or a dd/MM/yyyy string. The timezone id is first normalised by standardiseTimezoneId.

toPercent(Object num, Object div)

Returns: String

Divides one number by another and renders the result as a whole number percentage with a trailing percent symbol. A blank or zero divisor, or a blank numerator, gives an empty string.

toPercent(Object num, Object div, int decimalPlaces)

Returns: String

Divides one number by another and renders the result as a percentage with a trailing percent symbol, to two decimal places. Note that the decimalPlaces argument is currently ignored and two places are always used.

toPercent(Object num, Object div, boolean appendSymbol, boolean withBlanks)

Returns: String

Divides one number by another and renders the result as a whole number percentage, with control over the percent symbol and over how blank inputs are handled.

toPercent(Object num, Object div, boolean appendSymbol, boolean withBlanks, int decimalPlaces)

Returns: String

Divides one number by another and renders the result as a percentage, with control over the percent symbol, blank handling and precision. With decimalPlaces of zero the calculation is done in whole numbers, otherwise it is done in floating point and rounded to two decimal places.

format(Object o)

Returns: String

Renders any value as a display string, choosing a sensible representation for its type. Strings are trimmed, a BigDecimal is rendered in plain notation, a Date uses formatDate, byte and char arrays are decoded, a BaseEntity uses its formatted name, a list or JSON array becomes a comma separated list, and anything else is parsed as a number where possible or falls back to its own toString.

stripExt(String s)

Returns: String

Removes the file extension from a file name if there is one, so file1.swf becomes file1 and file1 is returned unchanged.

fileExt(String fileName)

Returns: String

Returns the file extension of a file name, without the dot, or an empty string when there is none.

gt(Object val1, Object val2)

Returns: boolean

Numeric greater than comparison that coerces both operands with toDouble, so numeric strings compare correctly. A null first operand is never greater, and a non-null first operand is always greater than a null second operand.

gte(Object val1, Object val2)

Returns: boolean

Numeric greater than or equal comparison that coerces both operands with toDouble, so numeric strings compare correctly.

lte(Object val1, Object val2)

Returns: boolean

Numeric less than or equal comparison that coerces both operands with toDouble, so numeric strings compare correctly.

lt(Object val1, Object val2)

Returns: boolean

Numeric less than comparison that coerces both operands with toDouble, so numeric strings compare correctly. A null first operand is never less, and a non-null first operand is always less than a null second operand.

eq(Object val1, Object val2)

Returns: boolean

Numeric equality comparison that coerces both operands with toDouble, so 1, '1' and 1.0 all compare equal. Two nulls are equal, and a null is never equal to a non-null.

not(Object o)

Returns: Boolean

Negates any truthy value, coercing it to a Boolean first. Returns null when the value cannot be interpreted as true or false.

htmlEncode(Object ob)

Returns: String

Escapes a value so it is safe to render inside HTML text, converting characters such as angle brackets and ampersands into entities. Only character sequences are escaped; any other type is returned via its own toString unchanged.

htmlAttEncode(String s2)

Returns: String

Escapes a value so it is safe to place inside a quoted HTML attribute, converting ampersands, angle brackets and both quote characters into entities. The conversion is lossy, so several different inputs can encode to the same attribute value.

htmlAttDecode(String s2)

Returns: String

Reverses htmlAttEncode, turning the ampersand, angle bracket and double quote entities back into their literal characters. Note that the single quote entity written by htmlAttEncode is not decoded.

percentDecode(String s)

Returns: String

Decodes a percent encoded URL path, so a%20b becomes 'a b'.

percentDecodeSafe(String s)

Returns: String

Decodes a percent encoded URL path in the same way as percentDecode, but returns null instead of throwing when the input is malformed.

percentEncode(String s)

Returns: String

Percent encodes a string so it is safe to use as a URL path segment, so 'a b' becomes a%20b.

between(Object oVal, Object oStart, Object oFinish)

Returns: boolean

Tests whether a date like value falls within a date range, where either bound may be omitted. A null start means 'no lower bound' and a null finish means 'no upper bound', so passing only a finish checks that the value is not after it. All three values are coerced with getDateTime, and a value that cannot be read as a date returns false.

toDate(Object oVal)

Returns: Date

Coerces a value into a java.util.Date. Accepts an existing Date, a Joda DateTime, a ZonedDateTime, a Long or Integer of epoch milliseconds, and a date string which is parsed with parseDate. Any other type returns null.

toSqlDate(Object oVal)

Returns: Date

Coerces a value into a java.sql.Date, for passing as a parameter to a native SQL query.

toSqlTimestamp(Object oVal)

Returns: Timestamp

Coerces a value into a java.sql.Timestamp, keeping the time of day, for passing as a parameter to a native SQL query.

toJodaDate(Object oVal)

Returns: DateTime

Coerces a value into a Joda DateTime in the server's default timezone, by way of toDate.

parseDateWithPattern(String dateS, String pattern)

Returns: Date

Parses a date string against an explicit Joda pattern, interpreting it in the current organisation's timezone.

parseDateWithPattern(String dateS, String pattern, String timezone)

Returns: Date

Parses a date string against an explicit Joda pattern, interpreting it in the named timezone. The text is first tidied with cleanString. A blank pattern falls back to the general purpose parseDate, and a parse failure raises a runtime exception.

toHtmlInputValue(String value)

Returns: String

Escapes a value so it can be placed in the value attribute of an HTML input for editing, by converting double quotes to an entity.

toPlain(String html)

Returns: String

Strips HTML markup to leave plain text, turning block and line break tags into newlines. The conversion is deliberately crude: it replaces a fixed set of tags rather than parsing the document.

toPlain(String html, boolean includeNewLines)

Returns: String

Strips HTML markup to leave plain text, with control over whether block and line break tags become newlines or are simply removed. Handles br, hr, p, div, b, strong, i, h1, h2 and h3, and replaces the non-breaking space and ampersand entities.

generateTextFromHtml(String html)

Returns: String

Extracts the readable text from an HTML document by removing its tags, then trims the result. Unlike toPlain this parses the markup rather than replacing a fixed set of tags.

getNow()

Returns: Date

Current date and time as seen by the server, taken from the platform's current date service rather than the system clock so that tests can control it.

getYearStart()

Returns: Date

Midnight on the first day of January of the current year, in the server's default timezone.

yearStart(Date dt)

Returns: Date

Midnight on 1 January of the year that the given date falls in, calculated in the current organisation's timezone.

monthStart(Date dt, int month)

Returns: Date

The first instant of the given month within the year that the given date falls in, calculated in the current organisation's timezone where one is set. The month is zero indexed, so 0 is January and 11 is December.

monthStart(Date dt)

Returns: Date

The first instant of the month that the given date falls in, calculated in the current organisation's timezone where one is set.

yearEnd()

Returns: Date

The last instant of the current year, that is 31 December at 23:59:59.999, in the current organisation's timezone.

yearEnd(Date dt)

Returns: Date

The last instant of the year that the given date falls in, that is 31 December at 23:59:59.999, in the current organisation's timezone.

monthEnd(Date dt, int month)

Returns: Date

The last instant of the given month within the year that the given date falls in, that is the final day at 23:59:59.999, calculated in the current organisation's timezone where one is set. The month is zero indexed, so 0 is January and 11 is December.

monthEnd(Date dt)

Returns: Date

The last instant of the month that the given date falls in, that is the final day at 23:59:59.999, in the current organisation's timezone where one is set.

durationSecs(Object start, Object finish)

Returns: long

Number of whole seconds between two date like values. A finish that is before the start gives a negative result.

durationHours(Object start, Object finish)

Returns: long

Number of whole hours between two date like values, truncated rather than rounded.

durationMins(Object start, Object finish)

Returns: long

Number of whole minutes between two date like values, truncated rather than rounded.

durationDays(Object start, Object finish)

Returns: long

Number of whole 24 hour days between two date like values, truncated rather than rounded. This is elapsed time, not a count of calendar day boundaries crossed.

durationYears(Object start, Object finish)

Returns: long

Number of whole years between two date like values, calculated as elapsed days divided by 365 and so ignoring leap years.

getMonthName(Object o)

Returns: String

Returns the English month name, such as January, for a date like value or a month name fragment, resolved with getMonth.

getMonthName(int i)

Returns: String

Returns the full English month name for a zero indexed month number, where 0 is January and 11 is December.

getCurrentDateService()

Returns: CurrentDateService

The platform's current date service, the single source of 'now' for the server, which tests can override to freeze or shift time.

ifEqual(String ifEqual, String ifNotEqual, Object o1, Object o2)

Returns: String

Null safe conditional that returns one of two strings depending on whether the two values are equal. Values of the same class are compared with equals, otherwise their string forms are compared, and two nulls count as equal.

isEqual(Object o1, Object o2)

Returns: boolean

Null safe equality test using the Java equals method, useful from JavaScript where the double equals operator does not compare host objects reliably. Two nulls count as equal.

isNotEqual(Object o1, Object o2)

Returns: boolean

Null safe inequality test, the negation of isEqual.

ifNull(Object val, Object defaultVal)

Returns: Object

Returns the given value, or a fallback when the value is null or an all whitespace string. Other empty values such as an empty collection are returned as they are; use ifEmpty if those should also fall back.

ifEmpty(Object val, Object defaultVal)

Returns: Object

Returns the given value, or a fallback when the value is empty by the rules of isEmpty, which covers null, undefined, a blank string and an empty collection or map.

ifTrue(Object bb, Object o1, Object o2)

Returns: Object

Ternary conditional for template syntax that has none: returns the second argument when the first is truthy and the third when it is not. The condition is coerced with toBool, and a null or unparseable condition counts as false.

ifFalse(Object bb, Object o1, Object o2)

Returns: Object

Inverted ternary conditional: returns the second argument when the condition is falsy and the third when it is truthy. The condition is coerced with toBool, and a null or unparseable condition counts as false.

newList()

Returns: ResourceList

Creates a new empty ResourceList, the mutable list type used throughout templates, which adds sorting, filtering and aggregation helpers on top of a plain list.

getList()

Returns: ResourceList

Creates a new empty ResourceList. Identical to newList, and provided so templates can use property syntax.

parseDate(String s)

Returns: Date

Parses a date from a string, trying several formats in turn: a string of epoch milliseconds, an ISO style timestamp containing a T, dd/MM/yyyy HH:mm when the text contains a colon, yyyy-MM-dd when it contains a hyphen, and otherwise dd/MM/yyyy. Text containing a time is interpreted in the current organisation's timezone.

parseTime(Object o)

Returns: Date

Parses a time of day in the 12 hour hh:mm am or pm form, returning it as a Date on the epoch day.

sdf(boolean hasTime)

Returns: DateFormat

Returns the shared thread local SimpleDateFormat for the platform's standard date patterns, either dd/MM/yyyy HH:mm or dd/MM/yyyy. The returned formatter belongs to the calling thread, so do not hold on to it or share it between threads.

toFloat(Object val)

Returns: Float

Converts almost any numeric value to a Float, returning null rather than zero when the value is empty or cannot be converted.

toBigDecimalSafe(Object val)

Returns: BigDecimal

Converts a value to a BigDecimal in the same way as toBigDecimal, but returns null instead of throwing when the value cannot be converted.

toBigDecimal(Object val)

Returns: BigDecimal

Converts a value to a BigDecimal without changing its scale. A non-numeric string raises a runtime exception, and null or a blank string returns null.

toBigDecimal(Object o, Integer decimals)

Returns: BigDecimal

Converts a value to a BigDecimal, optionally rounding it half up to a fixed number of decimal places. Accepts BigDecimal, Integer, Long, Float, Double and a string in the grouped '#,##0.0#' form. A non-numeric string raises a runtime exception, and null, a blank string or an unhandled type returns null.

calc(ResourceList list)

Returns: Calc

Creates a Calc over the given list, the calculator object that provides filtering, grouping, summing and other aggregation over a ResourceList.

where(String mvelExpr, ResourceList list)

Returns: ResourceList

Filters a list with an MVEL boolean expression, keeping only the items for which the expression is true. The expression is evaluated once per item, so this is proportional to the size of the list.

checked(Object o)

Returns: String

Returns the HTML attribute word 'checked' when the given value is truthy, and an empty string otherwise, for use inside an input tag.

selected(Object o)

Returns: String

Returns the HTML attribute word 'selected' when the given value is truthy, and an empty string otherwise, for use inside an option tag.

checkbox(String name, Object oChecked)

Returns: String

Renders a checkbox input with the value 'true', together with the hidden companion field that lets the server tell an unticked box apart from a missing one. The companion field is named after the checkbox with a _checkbox suffix.

checkbox(String id, String name, Object oChecked)

Returns: String

Renders a checkbox input with the value 'true' and the given HTML id, together with the hidden companion field named after the checkbox with a _checkbox suffix.

checkbox(Object oId, String name, Object oChecked, Object oValue)

Returns: String

Renders a checkbox input with an explicit submitted value and HTML id, together with the hidden companion field. The hidden field is named after the checkbox with a _checkbox suffix and submits 'false', so the server sees a value whether or not the box is ticked.

call(Object o)

Returns: String

Swallows the result of an expression so it produces no output, for Velocity templates where you want the side effect of a call such as adding to a list without printing its return value.

bsswitch(Object oId, String name, Object oChecked, Object oValue)

Returns: String

Renders a checkbox styled as a Bootstrap on and off switch, with the green and red colour attributes the switch plugin looks for, together with the hidden companion field named after the checkbox with a _checkbox suffix.

radioEq(String id, String name, String currentValue, String value)

Returns: String

Renders a radio button that is ticked when the property's current value equals the value this button represents, saving the caller from doing the comparison.

radioEq(String id, String name, String currentValue, String value, String className)

Returns: String

Renders a radio button with a CSS class, ticked when the property's current value equals the value this button represents.

radio(String id, String name, Object oChecked, String value)

Returns: String

Renders a radio button, taking the ticked state directly as a truthy value rather than comparing values.

radio(String id, String name, Object oChecked, String value, String className)

Returns: String

Renders a radio button with a CSS class, taking the ticked state directly as a truthy value rather than comparing values.

option(Relational value, Object currentValue)

Returns: String

Renders a select option for a database entity, using its row id as the option value. A Website is labelled with its title and domain name; any other entity is labelled with its title property.

option(Object value, Object oText, Object currentValue)

Returns: String

Renders a select option with an explicit value and label, marked selected when the value matches the current value. The label is wrapped with a translation lookup class so it can be translated on the client.

option(Object value, Object oText, Object currentValue, Object dataIdValue)

Returns: String

Renders a select option with an explicit value, label and data-id attribute, marked selected when the value matches the current value. The label is wrapped with a translation lookup class so it can be translated on the client.

select(String name, Map<Object,Object> data)

Returns: String

Renders a select element whose options come from a map, with the map keys as option values and the map values as labels. No option is preselected.

select(String name, Object currentVal, Map<Object,Object> data)

Returns: String

Renders a select element whose options come from a map, marking the option that matches the current value as selected.

select(String id, String name, String htmlClass, Object currentVal, Map<Object,Object> data)

Returns: String

Renders a select element with an HTML id and CSS class, whose options come from a map, marking the option that matches the current value as selected.

getPort()

Returns: int

Port that the current HTTP request arrived on, taken from the Host header, defaulting to 80 when there is no request or no header.

isSecure()

Returns: boolean

True when the current request should be treated as HTTPS, either because it arrived on port 443 or 8443, because the request itself reports HTTPS, or because the current tenant organisation has force HTTPS switched on.

getPortString()

Returns: String

Port suffix to append when building an absolute URL, such as :8080. Empty for the default ports 80 and 443 so that ordinary URLs do not carry a redundant port.

profilePicHref(Profile p)

Returns: String

Returns the URL of a profile's photo, falling back to the default avatar image when the profile has no photo. Superseded by the profile templating helpers.

toCsvArgs(String s)

Returns: String

Joins the given strings into a single comma separated line, for callers that have loose arguments rather than a list.

toCsv(Iterable list)

Returns: String

Joins the items of any iterable into a single comma separated line, skipping nulls. Values are not quoted or escaped, so this is not safe for values that contain commas.

toLineOfVals(Iterable list, String seperator)

Returns: String

Joins the items of any iterable into a single line with the given separator between them, skipping nulls. Values are not quoted or escaped.

toProperties(Map<Object,Object> map)

Returns: String

Renders a map as a properties style block, one key equals value pair per line. Keys and values are rendered with format, and neither is escaped.

toCsv(String[] list)

Returns: String

Joins an array of strings into a single comma separated line, skipping nulls. Values are not quoted or escaped.

toCsv(Object list)

Returns: String

Joins a value into a comma separated line when it is a list, and otherwise falls back to the value's own toString.

fromCsv(Object o)

Returns: List<String>

Splits a comma separated string into a list, trimming each item and dropping the blanks. The input is first tidied with cleanString.

toJson(Object val)

Returns: String

Serialises any value to compact JSON using the platform's JSON writer, which understands the platform entities and honours the IgnoreJsonProperty annotation.

toJson(Object val, int indent)

Returns: String

Serialises any value to indented, human readable JSON using the platform's JSON writer.

parseJson(String jsonStr)

Returns: Object

Parses JSON text into a JSONObject or JSONArray that templates and scripts can read. Malformed JSON raises a runtime exception; use the two argument form to get null instead.

parseJson(String jsonStr, boolean throwException)

Returns: Object

Parses JSON text into a JSONObject or JSONArray, with control over whether malformed input throws or simply yields null.

addDays(Date now, Integer days)

Returns: Date

Returns a new date the given number of days after the one supplied, or before it when the number is negative. The original date is not modified.

addMilliseconds(Date now, Integer milliseconds)

Returns: Date

Returns a new date the given number of milliseconds after the one supplied, or before it when the number is negative.

addYears(Date now, Integer years)

Returns: Date

Returns a new date the given number of years after the one supplied, or before it when the number is negative. Calendar arithmetic is used, so 29 February shifts to 28 February in a non-leap year.

addMonths(Date now, Integer months)

Returns: Date

Returns a new date the given number of months after the one supplied, or before it when the number is negative. Calendar arithmetic is used, so a day of month that does not exist in the target month is clamped to the last day of that month.

addDays(Object now, Object days)

Returns: Date

Returns a new date the given number of days after the one supplied, coercing both arguments first so a date string and a numeric string can be passed straight from a template.

getDaysBetween(Object from, Object to)

Returns: List<Date>

Builds the list of days from one date up to but not including another, each at the start of its day. Both bounds are coerced with toDate. The list grows with the size of the range, so avoid it for very wide ranges.

addSeconds(Date now, int seconds)

Returns: Date

Returns a new date the given number of seconds after the one supplied, or before it when the number is negative.

addMinutes(Date now, int mins)

Returns: Date

Returns a new date the given number of minutes after the one supplied, or before it when the number is negative.

addHours(Date now, int hours)

Returns: Date

Returns a new date the given number of hours after the one supplied, or before it when the number is negative.

getBaseWebsiteUrl()

Returns: String

Scheme and domain of the website being served by the current request, such as https://www.example.com, with no trailing slash. Null when the request is not being served from a website root folder.

getBaseWebsiteUrl(Website w)

Returns: String

Builds the scheme and domain for the given website, such as https://www.example.com, with no trailing slash. The scheme follows the force HTTPS setting on the website's live branch.

getCleanedRootDomain(String domainName)

Returns: String

Reduces a host name to its registrable root domain, so shop.example.co.nz becomes example.co.nz. Any trailing dot is removed first, and the public suffix list is used to decide where the root begins.

getDomainName(Website w)

Returns: String

Primary domain name of the given website, including the port suffix when the server is not on a default port.

getDomainName(Website w, boolean useVersion)

Returns: String

Domain name of the given website, including the port suffix, optionally resolved against the website's live branch so that a version specific host name is returned.

getDomainName(Website w, boolean useVersion, boolean includePort)

Returns: String

Domain name of the given website, with control over branch resolution and whether the port suffix is appended.

getKademiDomainName(Website w, boolean useVersion, boolean includePort)

Returns: String

Kademi hosted domain name of the given website, that is the platform's own host name for it rather than any custom domain the customer has attached.

isNotNull(Object o)

Returns: boolean

True when the given value is present, that is anything isNull does not treat as missing. As well as a Java null this rejects a JavaScript undefined and a JSON null.

isNull(Object o)

Returns: boolean

True when the given value counts as missing, which covers a Java null, an empty string, a JSON null and the JavaScript undefined and null values that reach the server from a script engine.

getVersionId(WebsiteBranchResource rf)

Returns: String

Builds the cache busting version token to embed in theme asset URLs. It combines the running server version with the content hash of the website's theme directory, so a theme change invalidates browser caches without a server release.

daysBetween(Date from, Date to)

Returns: List<LocalDate>

Lists the days from one date up to but not including another as Joda LocalDate values. When the two dates fall on the same day the result still holds that one day. The list grows with the size of the range.

endofDay(Date dt)

Returns: Date

Returns the last instant of the day the given date falls in, that is 23:59:59.999, in the current organisation's timezone. Null safe.

endOfDay(Date dt)

Returns: Date

Returns the last instant of the day the given date falls in, that is 23:59:59.999, in the current organisation's timezone. An alias for endofDay. Null safe.

endofDay(Date dt, String timezone)

Returns: Date

Returns the last instant of the day the given date falls in, that is 23:59:59.999, calculated in the named timezone. Null safe.

endOfDay(Date dt, String timezone)

Returns: Date

Returns the last instant of the day the given date falls in, that is 23:59:59.999, calculated in the named timezone. An alias for endofDay. Null safe.

startOfDay(Date dt)

Returns: Date

Returns the first instant of the day the given date falls in, that is midnight, in the current organisation's timezone. Null safe.

startOfDay(Date dt, String timezone)

Returns: Date

Returns the first instant of the day the given date falls in, that is midnight, calculated in the named timezone. Null safe.

truncate(String s, int max)

Returns: String

Shortens a string to at most the given number of characters, appending three full stops when anything was cut off. Strings already within the limit are returned unchanged.

truncateToEnd(String s, int max)

Returns: String

Shortens a string to at most the given number of characters by trimming from the front, so the end of the text is what survives.

newReadonlyList(List list)

Returns: List

Wraps a list so it cannot be modified, copying it into the platform's killable list type first so that its contents are released when the request ends. A null input gives an empty read only list.

newStack()

Returns: Stack

Creates a new empty Stack, a small last in first out collection that only allows pushing and popping at the head.

newArrayList()

Returns: ArrayList

Creates a new empty list that a template or script can add any type of object to. The list is a killable list, so its contents are released when the request ends.

newCommonList()

Returns: CommonList

Creates a new empty CommonList, which behaves like an ArrayList but adds sorting, filtering and aggregation helpers. It is the base class of ResourceList.

newCommonList(Collection from)

Returns: CommonList

Creates a CommonList holding a copy of the given collection. A CommonList behaves like an ArrayList but adds sorting, filtering and aggregation helpers.

newArrayList(Object[] arr)

Returns: ArrayList

Creates a new list holding the elements of the given array. The list is a killable list, so its contents are released when the request ends.

newMap()

Returns: LinkedHashMap

Creates a new empty map that a template or script can put entries into. Insertion order is preserved, and the contents are released when the request ends.

newSet()

Returns: LinkedHashSet

Creates a new empty set that a template or script can add to. Insertion order is preserved, and the contents are released when the request ends.

newMapBuilder()

Returns: MapBuilder

Creates a new MapBuilder, which builds a map with chained put calls so a whole map can be written as a single expression in a template.

formatBytes(Object o)

Returns: String

Renders a byte count in human readable units, such as 300 B, 5 kB or 3 MB, using powers of 1000. A Milton resource is rendered from its content length.

formatSecsAsDuration(Object o)

Returns: String

Renders a number of seconds as a rough duration, showing seconds under five minutes, minutes under three hours, and whole hours beyond that.

formatCurrency(Object o)

Returns: String

Formats an amount for display as money, using the current locale's grouping and decimal separators and two decimal places, without a currency symbol.

formatCurrency(Object o, String unitSymbol, String unitPosition, Integer numberOfDecimal)

Returns: String

Formats an amount to a fixed number of decimal places and attaches a unit symbol on the chosen side, for currencies or for made up units such as points.

formatCurrency(Object o, Boolean leadingZeros)

Returns: String

Formats an amount for display as money with grouped thousands and two decimal places, optionally dropping the decimal part altogether.

formatDecimal(Object o, Integer numberDecimals)

Returns: String

Formats a number with grouped thousands and exactly the given number of decimal places, padding with zeros where needed.

formatMaxDecimals(Object o, Integer numberDecimals)

Returns: String

Formats a number with at most the given number of decimal places, rounding half up and then stripping any trailing zeros, so a whole number prints without a decimal point.

getStartOfWeek(Date dt)

Returns: Date

Returns midnight on the Monday of the week that the given date falls in. Weeks are taken to start on Monday, so for a Sunday start call addDays with minus one on the result. Note that seconds and milliseconds are not cleared.

capitalizeString(Object o)

Returns: String

Upper cases the first character of a value's string form and leaves the rest as it is, so 'hello world' becomes 'Hello world'.

getCountryCodes()

Returns: CountryCodes

The platform's country code lookup table, which maps between two letter and three letter ISO codes, country names and dialling codes.

getCountryCodeOfOrg()

Returns: CountryCode

Country code record for the current root folder organisation's country, resolved from its two letter ISO code. Null when there is no current root folder or the organisation has no country set.

sortByProperty(List list, String propertyName)

Returns: List

Returns a copy of the list sorted by a bean property, reading the property by name from each item and comparing null safely. The original list is not modified. Any error is logged and the original list is returned unsorted.

sortReverse(List list)

Returns: List

Returns a copy of the list with the items in the opposite order. The original list is not modified.

sort(List list)

Returns: List

Returns a copy of the list sorted by the items' own natural ordering. The original list is not modified, and every item must be comparable.

toggleParamVal(String paramName, String val)

Returns: String

Rebuilds the current request's query string with one value added to or removed from a named parameter, for building faceted filter links. Multi-valued parameters are held as comma separated lists, so toggling C out of tags=C,D on a request with categories=A,B gives categories=A,B and tags=D.

toggleParamVal(String paramName, String val, boolean uniqueParam)

Returns: String

Rebuilds the current request's query string with one value toggled in a named parameter, or with the parameter replaced outright. Parameter names and values that fail the platform's parameter cleaning check are dropped from the result.

paramSelected(String paramName, String value, String active)

Returns: String

Returns the given active text when a value is present in a comma separated request parameter, and an empty string otherwise. Pairs with toggleParamVal to mark the currently chosen facets, usually by emitting a CSS class.

addQueryParam(String href, String paramName, Object paramVal)

Returns: String

Appends a name and value pair to a URL, choosing a question mark or an ampersand depending on whether the URL already has a query string. Neither the name nor the value is encoded, so percent encode them yourself if they may contain reserved characters.

getQueryString()

Returns: String

Query string of the current request, rebuilt from its parameters and including the leading question mark. Empty when there is no request or the request has no parameters. Values are not re-encoded.

addNum(Object from, Object addAmount)

Returns: Integer

Adds two values as integers, coercing each with toInteger so numeric strings can be passed straight from a template.

split(String s, String sep)

Returns: String[]

Splits a string on the given separator into an array, trimming each part and dropping the blanks. A null or the literal text 'undefined' gives an empty array.

split(String s)

Returns: String[]

Splits a comma separated string into an array, trimming each part and dropping the blanks.

splitByAnything(String s)

Returns: String[]

Splits a string on any run of semicolons, commas, spaces or newlines, which suits free text lists such as a pasted set of email addresses.

toList(Object arr)

Returns: List

Converts almost any sequence into a Java List that templates and scripts can iterate. Handles Java arrays and collections, a Nashorn script array, a GraalJS array, iterator or callable that yields one, and returns an existing list unchanged. A value that is not a sequence raises a runtime exception. Iterating a script value yields to the Governor on each element so long conversions stay interruptible.

formatNumeric(Object o, String format)

Returns: String

Formats a number with an arbitrary DecimalFormat pattern, such as #,###.00 for grouped thousands and two decimal places. Take care in Velocity templates, where the hash character starts a directive and must be escaped.

formatNumeric(Object o)

Returns: String

Formats a number with grouped thousands and two decimal places, using the pattern #,###,###.00.

formatNumericNoDecimal(Object o)

Returns: String

Formats a number with grouped thousands and no decimal places, using the pattern #,###,###.

isNumeric(Object o)

Returns: boolean

True when the given value can be converted to a number by toLong, which is the platform's test for 'is this numeric'. Note that null and an empty string convert to zero and so count as numeric.

isType(Object source, String className)

Returns: boolean

True when the given object's Java class has the given simple name, for example isType(lead, 'Lead'). Hibernate proxies are unwrapped first so a lazily loaded entity is matched on its real class.

getSimpleType(Object source)

Returns: String

Returns the simple Java class name of the given object, without its package, which is handy for logging or for branching on the type of a value from a script.

toBase64String(Object o)

Returns: String

Encodes a byte array or a string as standard Base64. A string is encoded using the platform default charset.

toBase64UrlString(Object o)

Returns: String

Encodes a byte array or a string as URL safe Base64, which uses minus and underscore in place of plus and slash and omits the padding, so the result can be dropped straight into a URL.

fromBase64AsString(String base64)

Returns: String

Decodes standard Base64 text back to a string, using the platform default charset.

fromBase64AsByteArray(String base64)

Returns: byte[]

Decodes standard Base64 text back to the raw bytes, for binary content that is not text.

toBigInteger(String val, int radix)

Returns: BigInteger

Parses the string form of an arbitrarily large integer written in the given number base into a BigInteger, for example base 16 for hexadecimal. A string that is not a valid number in that base raises a runtime exception.

joinByteArray(byte[] b1, byte[] b2)

Returns: byte[]

Concatenates two byte arrays into a new array, with the contents of the first followed by the contents of the second.

copyFromArray(byte[] arr, int from, int to)

Returns: byte[]

Copies a slice out of a byte array into a new array. The start index is inclusive and the end index is exclusive, and an end index beyond the array is padded with zeros.

copyFromArray(char[] arr, int from, int to)

Returns: char[]

Copies a slice out of a char array into a new array. The start index is inclusive and the end index is exclusive, and an end index beyond the array is padded with null characters.

byteArrayToHexString(byte[] bytes)

Returns: String

Renders raw bytes as lower case hexadecimal, two characters per byte, which is the usual way to show a hash or signature.

getCrypto()

Returns: CryptoImpl

The platform's cryptography helper, which provides hashing, HMAC signing and symmetric encryption to templates and scripts.

getGeoIPService()

Returns: GeoIPService

The platform's GeoIP service, which resolves an IP address to a country, region and city. Null when the server was built without one.

parseHtml(String html)

Returns: Jerry

Parses HTML into a Jerry document, a jQuery style API for walking and querying the markup with CSS selectors. Any parse error is logged and null is returned rather than thrown.

formatJodaDate(Object date, String pattern)

Returns: String

Coerces a value to a date and formats it with an arbitrary Joda pattern such as dd/MM/YYYY HH:mm:ss, in the date's own timezone.

formatJodaDate(Object date, String pattern, String timeZone)

Returns: String

Coerces a value to a date, shifts it into the named timezone and formats it with an arbitrary Joda pattern such as dd/MM/YYYY HH:mm:ss.

formatAsCleanId(String title)

Returns: String

Turns a title into a path and identifier safe token by replacing spaces and special characters with hyphens and stripping any leading hyphens. Use it to derive a stable name or anchor from human entered text.

cleanUserId(String userId)

Returns: String

Strips a user id down to letters, digits and underscores, dropping every other character. A null input raises a runtime exception.

formatPhoneNumber(Object obj, Object phone)

Returns: String

Formats a phone number into the E164 international form, such as a plus sign followed by the country code and number with no spaces. The country to interpret a local number against can be given directly or taken from an organisation.

formatPhoneNumber(Object obj, Object phone, String format)

Returns: String

Formats a phone number into a chosen standard form. The country to interpret a local number against can be given directly or taken from an organisation, and an unrecognised format name falls back to E164.

textFromHtml(String htmlContents)

Returns: String

Strips the markup from an HTML document and returns the readable text, suitable for a plain text email body or a search index.

propertyOfObject(Object o1, Object o2)

Returns: Object

Reads a named property from an object by reflection, so a template can look up a field whose name is only known at runtime. Nested paths such as 'profile.name' are supported.

newTextOptionType(Object placeholder)

Returns: TextOptionType

Creates a free text option type for a mail merge or field definition, with the given placeholder shown in the editor.

newListOptionBuilder()

Returns: ListOptionTypeBuilder

Creates a builder for a list option type, used to declare a fixed set of choices for a field. Add each choice with addOption, giving its stored value and its display title, then call build to get the option type.

toPlainEmail(Object o)

Returns: String

Extracts the bare email address from an address that may carry a display name, so a value like 'Joe Bloggs joe at bloggs.com' in angle bracket form yields just the address part.

textToHtml(String text)

Returns: String

Wraps plain text in HTML, turning each line into its own paragraph element. Text that already looks like HTML, because it contains a paragraph or anchor tag, is returned unchanged. The text is not escaped.

getRandomGuid()

Returns: String

A freshly generated random UUID in its standard hyphenated string form, for use as a unique identifier.

formatUnits(Object o)

Returns: String

Renders a number abbreviated with a metric suffix, so 3123 becomes 3.1k and 4500000 becomes 4.5m. Values under 3000 are shown in full, and the number of decimal places narrows as the magnitude grows.

encodeAsHtmlEntities(String s)

Returns: String

Escapes a string into HTML entities, converting every character that has a named entity as well as the markup characters.

firstNotNull(Object vals)

Returns: String

Returns the first of the given values that is not empty, rendered as a string. Emptiness is decided by isNotEmpty, so a blank string and an empty collection are both skipped.

firstNotNull2(Object vals)

Returns: Object

Returns the first of the given values that is not null, as the original object rather than as a string. Unlike firstNotNull this keeps the value's type and only skips values that isNull rejects.

safeGet(List list, int pos)

Returns: Object

Reads the item at the given index of a list without throwing when the index is out of range or the list is null.

safeGet(Object[] array, int pos)

Returns: Object

Reads the element at the given index of an array without throwing when the index is out of range or the array is null.

cleanString(Object o)

Returns: String

Sanitises untrusted text with the platform's AntiSamy policy, dropping scripts and dangerous attributes while letting a safe subset of HTML elements through, then trims the result. Use this on anything a user typed before storing or displaying it.

cleanString(Object o, boolean makePlain)

Returns: String

Sanitises untrusted text with the platform's AntiSamy policy, optionally flattening it to plain text first so that paragraphs, line breaks and headings are stripped as well rather than surviving the sanitiser.

containsDangerous(String dirtyComment)

Returns: boolean

True when the given text contains markup that the platform's AntiSamy policy would strip, so a caller can reject the input outright instead of silently sanitising it.

paginator()

Returns: Paginator

Creates a Paginator, the helper that reads the page and page size request parameters and renders the paging controls for a listing.

paginator(int defaultPageSize)

Returns: Paginator

Creates a Paginator with an explicit default page size, used when the request does not name one.

translate(String sourceType, String sourceId, String field, String langCode)

Returns: String

Looks up the stored translation of one field of one record, in a specific language. Translations are keyed by the source type, the record id and the field name.

translate(String sourceType, String sourceId, String field)

Returns: String

Looks up the stored translation of one field of one record, in the language of the current request.

translate(String sourceType, String sourceId)

Returns: String

Looks up the stored translation of a record's default field, in the language of the current request.

translate(Translatable source, String field)

Returns: String

Looks up the stored translation of one field of a translatable record, taking the source type and id from the record itself.

translate(String sourceText)

Returns: String

Translates a literal piece of text into the language of the current request, matching on the text itself rather than on a record and field.

asUser(Object oUser)

Returns: Profile

Coerces a value into a Profile. Accepts a Profile, a user resource or admin user page, or a username string which is looked up in the current organisation. Looking up by username hits the database.

asGroup(Object oGroup)

Returns: Group

Coerces a value into a Group. Accepts a Group, a group management folder, or a group name string which is looked up in the current organisation. Looking up by name hits the database.

asWebsite(Object oWebsite)

Returns: Website

Coerces a value into a Website. Accepts a Website, a website root folder, a website or branch management folder, or a website name string which is looked up in the current organisation. Looking up by name hits the database.

formatDateWithHyphens(Date dt)

Returns: String

Formats a date as yyyy-MM-dd, the sortable hyphenated form used in file names and data exports.

deCamelise(String camelCase)

Returns: String

Turns a camel case identifier into a human readable label, so firstName becomes 'First name'. Handy for labelling fields whose names come from the data model.

findDayOnOrBefore(int dayIndex, Date dt)

Returns: Date

Steps backwards from the given date to the most recent occurrence of a weekday, returning the date itself when it already falls on that day. The day index follows Joda numbering, where Monday is 1 and Sunday is 7, and any other value raises a runtime exception. The time of day is left as it was.

isEmpty(Object o)

Returns: boolean

True when the given value is semantically empty, which covers null, undefined, a blank string, and an empty list, map or array. A numeric zero and a false boolean are not empty.

isNotEmpty(Object o)

Returns: boolean

True when the given value has content, that is anything isEmpty does not treat as empty.

foreach(Object iterable, BiConsumer consumer)

Returns: void

Iterates over a collection, map, array or a count and calls the given function once per item. A map is iterated over its values, and an Integer or Long is treated as a count so the function is called with the numbers from zero up to it. The function receives the item and a loop context carrying the current index. Calling breakForeach from inside the function stops the loop early, and the loop yields to the Governor on each item so a long iteration stays interruptible.

foreach(Object iterable, ScriptObjectMirror r)

Returns: void

Iterates over a collection, map, array or a count and calls the given Nashorn script function once per item, with the item and a loop context carrying the current index. A function of any other type raises a runtime exception.

_foreach(Object[] arr, BiConsumer r)

Returns: void

Iterates over an array by copying it into a list and delegating to the iterable form, clearing any pending break flag first.

_foreach(Iterable it, BiConsumer r)

Returns: void

Iterates over anything iterable, calling the given function with each item and a loop context that carries the index and its own break flag. Yields to the Governor on each item, and always clears the thread local break flag on the way out so a break on the last item cannot leak into the next loop on the same thread.

breakForeach()

Returns: void

Stops the innermost foreach loop on this thread at the end of the current item, the equivalent of a break statement inside the loop function.

stringJoin(List<String> list, String separator)

Returns: String

Joins a list of strings with a separator, dropping the null and empty entries first so an absent address line does not leave a doubled separator. Note that the list passed in is modified in place.

parseDateISO8601(String s)

Returns: Date

Parses an ISO 8601 timestamp and returns it as a Date, presented in the current tenant organisation's timezone. Text that is not a valid ISO 8601 timestamp raises a runtime exception.

dateTimePattern(String context)

Returns: String

Returns the date and time format pattern the current organisation should use, in the syntax of the requested platform. Picks the US month first ordering or the day first ordering according to the organisation's date setting.

datePattern(String context)

Returns: String

Returns the date only format pattern the current organisation should use, in the syntax of the requested platform. Picks the US month first ordering or the day first ordering according to the organisation's date setting.

andClause(Object a, Object b)

Returns: boolean

Logical AND of two truthy values, each coerced with toBool. Note that both arguments are evaluated, and a value that toBool cannot interpret raises a runtime exception.

orClause(Object a, Object b)

Returns: boolean

Logical OR of two truthy values, each coerced with toBool. Note that both arguments are evaluated, and a value that toBool cannot interpret raises a runtime exception.

parseExtraFieldDef(String name, String fieldDef)

Returns: ExtraField

Builds an ExtraField definition from a field name and the platform's compact extra field definition syntax, which encodes the field type, whether it is required, and any option list.

formatToCleanHtml(String original)

Returns: String

Turns user entered plain text into safe display HTML. Line breaks become break tags, the rest of the text is HTML escaped, and anything that looks like a URL is wrapped in a nofollow link that opens in a new tab.

parseSearch(String q)

Returns: KSearchQuery

Parses a search expression written in the platform's query syntax into a KSearchQuery that can be run against the search index.

newExtraField(String name, boolean required)

Returns: ExtraField

Creates an ExtraField definition with the given name, deriving its display label from the name by de-camelising it.

getCurrentRootFolder()

Returns: RootFolder

Root folder the current request is being served from, which is the website, admin or organisation root that determines the tenant and the resource tree. Null outside a request.

randomInt(Object oRange)

Returns: int

Returns a random whole number from zero up to but not including the given bound. A bound of zero or less raises a runtime exception. Not suitable for security purposes.

randomHex(int numDigits)

Returns: String

Returns a random lower case hexadecimal string of the given length. Not suitable for security purposes; use the crypto helper for anything that must be unguessable.

randomAlpha(int numChars)

Returns: String

Returns a random alphanumeric string of the given length, useful for a code or a temporary name. Not suitable for security purposes.

randomAlpha(int numChars, String excludedCharacters)

Returns: String

Returns a random alphanumeric string of the given length, leaving out any character listed in the exclusions. Useful for codes people have to read aloud, where characters such as O and 0 are best avoided.

normalizeString(String s)

Returns: String

Strips accents and other combining marks from text and drops anything left that is not ASCII, so 'Muller' with an umlaut becomes plain 'Muller'. Useful for building comparison keys and identifiers.

toRanges(Collection originalList, int partitionSize)

Returns: List<Pair<Integer,Integer>>

Splits the index space of a collection into ranges of at most the given size, each returned as a pair of start and finish indexes where the finish is exclusive. Use it to process a large collection in batches. See splitList for the variant that returns the sublists themselves.

splitList(Collection src, int partitionSize)

Returns: List<List>

Breaks a collection into consecutive sublists of at most the given size, for processing a large collection in batches.

newTable(String id)

Returns: TableViewMetaBuilder

Creates a builder for a table definition, which describes the columns, sorting and paging of a listing rendered by the standardTable macro.

newFormContext()

Returns: FormContext

Creates a FormContext over the current request's parameters, giving null safe reads that are cleaned to the platform's OWASP rules. Use it instead of reading raw request parameters.

newFormContext(Map<String,String> params)

Returns: FormContext

Creates a FormContext over an explicit map of parameters rather than the current request, which suits validating values that came from somewhere other than a form post.

newSearchProperties(Integer startPos, Integer pageSize)

Returns: SearchProperties

Creates a SearchProperties holding the paging window to apply to a search or query.

newSearchProperties(Integer startPos, Integer pageSize, String orderBy, String orderDir)

Returns: SearchProperties

Creates a SearchProperties holding both the paging window and the sort order to apply to a search or query.

newStringBuilder()

Returns: StringBuilder

Creates an empty StringBuilder, a mutable string that a template or script can append to in a loop without building up garbage.

newMembershipList()

Returns: MembershipList

Creates an empty MembershipList, the collection used to gather group memberships before applying them to a profile.

isImage(String newName, String contentType)

Returns: boolean

True when a file looks like an image, judged from its file name extension and its content type.

lowest(Object vals)

Returns: Object

Returns the smallest of the given values by their natural ordering, which means every value must be comparable with the others.

highest(Object vals)

Returns: Object

Returns the largest of the given values by their natural ordering, which means every value must be comparable with the others.

obfuscateEmail(String email)

Returns: String

Masks the middle of an email address so it can be shown to a user for recognition without disclosing the whole address.

convertMapToParamString(Map<String,String> params)

Returns: String

Renders a map of string names and values as a single encoded parameter string, for storing a set of settings in one column or field. Read it back with parseParamStringToMap.

parseParamStringToMap(String params)

Returns: Map<String,String>

Parses a parameter string produced by convertMapToParamString back into a map of names and values.

link(Object o)

Returns: String

Renders an admin link to the given entity, with an icon and the entity's display name, choosing the right URL for its type.

link(Object o, String cls)

Returns: String

Renders an admin link to the given entity with an icon and its display name, choosing the URL that matches its type. Understands profiles, organisations, sales data series, rewards and points buckets, org types, groups, voucher types and vouchers, products, SKUs and categories, blogs, websites, app and funnel repositories. Profile and website links point at the public facing URL instead when the request is being served from a website.

link(String href, String text, String cls)

Returns: String

Renders an anchor with an explicit URL and label. The label is sanitised and flattened to plain text before it is written.

calcGaussianDecay(double elapsedDurationActual, double standardDev, double multiplier)

Returns: double

Calculates a Gaussian decay factor for how much a value should be discounted as time passes, which is how the platform ages engagement and recency scores. The factor is one at zero elapsed time and falls towards zero as the elapsed time grows past the standard deviation.

docsHtml(Object target)

Returns: String

Renders the developer reference for an object as HTML, listing the properties and methods it exposes to templates and scripts. Use it while developing to see what is available on a value.

docsText(Object target)

Returns: String

Renders the developer reference for an object as plain text, listing the properties and methods it exposes to templates and scripts. The plain text form suits logging and script consoles.

supplyInStopWatch(String name, Supplier r)

Returns: Object

Runs the given function inside a named stopwatch so its duration shows up in debug session performance reports, and returns whatever the function returned.

runInStopWatch(String name, Runnable r)

Returns: void

Runs the given block inside a named stopwatch so its duration shows up in debug session performance reports. Use supplyInStopWatch when the block has to return a value.

lapStopWatch(String name)

Returns: void

Records a lap against the stopwatch currently running on this thread, so a long operation can be broken into named phases in the performance report.

replaceText(String source, String findText, String replaceWith)

Returns: String

Replaces every occurrence of a literal piece of text with another, treating the search text as plain characters rather than as a regular expression.

replaceAllText(String source, String findText, String replaceWith)

Returns: String

Repeatedly replaces a literal piece of text until none remains, which also catches occurrences that only appear after an earlier replacement. Take care: if the replacement itself contains the search text this never finishes.

checkPathTraversal(String inputString)

Returns: boolean

Checks that a user supplied path fragment cannot be used for a path traversal attack. The value must start with a letter or digit and must not contain a run of dots followed by a slash, a backslash or the end of the string. A blank value passes.

toMap(Object source)

Returns: Map<String,Object>

Copies any map into a plain insertion ordered map, which gives uniform handling of the different map types that reach the server from Nashorn and GraalJS. A value that is not a map raises a runtime exception.

toMap(List list, String keyPropName)

Returns: Map<String,Object>

Indexes a list into a map by reading one property from each item and using it as the key, so a list can be looked up by id or name. Items whose key is blank are skipped, and where two items share a key the later one wins.

standardiseTimezoneId(String timezoneId)

Returns: String

Maps a timezone id onto the name the platform's date library recognises, currently rewriting Europe/Kyiv to Europe/Kiev. Any other id is returned unchanged.