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.

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