FAQ

Selectors

Operator	Description	Example
.	Selects the value of the current control	. > 10
$control-name	Shorthand for selecting a particular control	$surname
$control-name/@attributeName	Access an attribute of a control. Note: by default forms4health adds a displayName attribute to all select controls	$administrativeGender/@displayName
instance('building-block-id')/$control-name	Shorthand for selecting a particular control in another building block	instance('personal-details')/$firstname
instance('form-context')/path/to/item	Allows you to reference values configured in the form context which can be viewed by pressing F2 within a form

Operators

Operator	Description	Example
+	Addition	3 + 2
-	Subtraction	3 - 2
*	Multiplication	3 * 2
div	Division	6 div 2
=	Equal	value = 3.50
!=	Not equal	value != 3.50
<	Less than	value < 3.50
<=	Less than or equal to	value <= 3.50
>	Greater than	value > 3.50
>=	Greater than or equal to	value >= 3.50
or	or	value = 3.50 or value = 3.70
and	and	value > 3.00 and value < 3.90
mod	Modulus (division remainder)	7 mod 3

Functions

function	Description	Example
true()	Returns the boolean value true	$yes-no = true()
false()	Returns the boolean value false	$yes-no = false()
concat(string,string,...)	Returns the concatenation of the strings	concat($first-name, ' ', $last-name)
string-length(string)	Returns the length of the specified string	string-length(.) > 10
local-dateTime()	Returns the local-dateTime with timezone information	Result: 2019-04-26T11:19:801-01:00
local-date()	Returns the local date with timezone information	Result: 2019-04-26-01:00
days-from-date(date)	Returns the number of days since 01-01-1970 to the date specfied	days-from-date(xs:date('2002-01-01)) Result: 11688
xf:seconds-from-dateTime(dateTime)	Returns the number of seconds since 01-01-1970 to the dateTime specified Note: This needs to be prefixed with xf: so it doesn't clash with the xpath 3.1 function	xf:seconds-from-dateTime(xs:dateTime('1971-01-01T00:00:00Z')) Result: 31536000
nf:date-add(<iso-date>, <unit>, <amount-to-add>)	Adds (or subtracts) a certain amount from a given input date. Valid units are: years, months, days, minutes, hours or seconds	nf:date-add('2020-12-31', 'days', 2) returns a date two days after 31st December 2020 - i.e. 2021-01-02T00:00:00.000Z
nf:isValidNHSNumber(<node | value>)	Validates the string literal or string evaluated from an XPath conforms to NHS Number validation rules - see https://en.wikipedia.org/wiki/NHS_number. This includes validating the check-digit and gracefully handling whitespace. Note: you can use http://danielbayley.uk/nhs-number/ for testing purposes.	nf:isValidNHSNumber('8211041200') returns true, nf:isValidNHSNumber('2786342324') returns false. Typical usage nf:isValidNHSNumber($NHSNumberControl)

CUI Functions

function	Description	Example
nf:CUIFormatDate(date)	Returns the date in CUI format	nf:CUIFormatDate('2019-05-01') Result: 01-May-2019
nf:CUIFormatAge(dateOfBirth)	Returns the current age in CUI format	nf:CUIFormatAge('2015-10-25')
nf:CUIFormatAge(dateOfBirth, comparisonDate)	Returns age in CUI format on the date of the second date parameter	nf:CUIFormatAge('2015-10-25', '2015-11-12') Result: 18d
nf:AgeInYears(dateOfBirth, comparisonDate?)	Returns age in years (as an integer) as of today, or at the time of the optional comparisonDate	nf:AgeInYears('2000-01-01', '2015-11-12') Result: 15
nf:CUIFormatName(given, family, title)	Returns a person's name in CUI format	nf:CUIFormatName('Bob', 'Smith', 'Master') Result: SMITH, Bob (Master)

Cheat Sheet

function	Description	Example
nf:multi-select-values(<multi-select-control>) = '<some-value>'	Safe way to find if a specific option has been chosen in a multi-select control (checkboxes, multi-select dropdowns etc). Should be used in preference to contains(<multi-select-control>, '<some-value>')	nf:multi-select-values($pets) = 'cat' returns true if the multi-select options for $pets has the cat option selected (others can be selected in addition), false otherwise. Note: if your options also included large cats (lions etc.) with a corresponding value of cat-large then the above method would be safe, wheras contains($pets, 'cat') would return true if either cat or cat-large was selected.
substring(<iso-date>,1,10)	Returns the date portion of an iso-date / iso-date-time value	substring(local-date(),1,10) returns today's date - useful as an initial value for date felds that capture an event date
substring(<iso-date-time>,12,5)	Returns the time portion of an iso-date-time value	substring(local-dateTime(),12,5) returns the local time - useful as an initial value for time felds that capture when an event took place
string-length(.) <operator> <character count limit>	Logic to add a constraint on character count	string-length(.) <= 100 adds a constraint that the user input must contain 100 or less characters (includes leading, trailing and multiple adjacent whitespace characters)
string-length(normalize-space(.)) <operator> <character count limit>	Logic to add a constraint on character count ignoring superfulous spaces	string-length(normalize-space(.)) <= 100 adds a constraint that the user input must contain 100 or less characters (excludes leading, trailing whitespace. Multiple adjacent whitespace characters are counted as one)
count(tokenize(normalize-space(.), ' ')) <operator> <word count limit>	Logic to add a word count constraint	count(tokenize(normalize-space(.), ' ')) = 3 adds a constraint that the user input must contain exactly three words (no more no less). For futher understanding, the normalise-space() function trims and reduces double spaces to one single one, the tokenize() function breaks the text - in this case words delimited by a single space (␣). The count() function counts the number of nodes (i.e. words in this case)
round($raw-decimal * 10##) div 10##	Display a raw decimal value to a certain number of decimal places. When multiplied/divided by 10 this will give one decimal place, 100 will give two decimal places and so on. Note - this is not just formatting it affects the data.	round(($weight div ($height*$height))*100) div 100 returns a BMI in this case with two decimal place precision
nf:other-value()	From 7.4.0 - When a control is marked "with-other" we use a special value in the control. This function returns that special value. This can then be used to see if a select has the option selected.	$single-select = nf:other-value() or nf:multi-select-values($multi-select) = nf:other-value()