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 AireForms 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()

Logic and Calculations in repeats

Form Repeats (or iterative rows of data collection) need a little special consideration when it comes to logic and calculations. See below some examples of typical logic or calculation needs within or relating to repeats.

Description	Example
You want to apply a calculation or logic at the repeat / line item level relative to a control outside the repeat.	For example, to initialise a the repeat item added-date control value to the same as the order-date value which is outside the repeat item you would use logic consistent with a calculation anywhere on the form - i.e. you could set the initial value to simply be $order-date
You want to perform logic or a calculation relative to another control that is witihn the same repeat item.	For example, say you want to show a user friendly date on the repeat, where the underlying date is captiured in the control medication-start-date you could have another control within the repeat item with a calculated value of nf:CUIFormatDate($medication-start-date). AireForms will automatically resolve this to be the sibling control in the same repeat item instance.
You want to add a control that indicates the repeat item numbering / index. You want it to automatically update on item add/insert and item delete.	This can be achieved a number of ways - for instance you could have a Calculated Value control called index as the first item in the repeat. If you wanted it to be numbered from 1 onwards you could set the calculation to be count(preceding::index) + 1 (note dollar notation is not required as the preceding XPath axis will automatically count the previous occurences of the control in the document order relative to the index control in the repeat item instance).
You want to add a control outside of the repeat that aggregates some data contained in the repeat items.	For example if you wanted to count how many repeat items there are, and there is a control called item-name in the repeat you would simply have a calculation of count($item-name). Similarly, if you want to sum a value across all items in the repeat you might have a control with a calculated value of sum($item-value) where item-value is a numeric typed control at the repeat item level.