PX Script API

Selector expression PX

Foorm API finds items and containers by either their enumerated name or it’s systemName

Enumerated name (“EnumCode”)

Every item in a foorm is enumerated by their type from top-down.  

The format is [typeCharacter][Index]

 TypeCharacter o A single character describing what type of item it is.  

 Q = Questions/Inputs

 S = Static items (headers, text)

 G = Groups/Containers

 V = Video player

 P = Page (not used)

 T = Tablequestion container

 NOTE: Only the table containing the questions

 The actual questions within have typechar “Q”

 Index o A Number starting from 1 enumerating the items per type. o Counts all the different types individually, so the first question vill have EnumCode “Q1” even if there is a header above it with EnumCode “S1”

NOTE:  

Since questions are enumerated from top down, their EnumCode will change if there is an item of the same type inserted above it in the foorm when edited in the designer. Remember to test and/or update your script when you edit a foorm with scripts applied.

SystemName  

Every question that have a label set is automatically given a systemName using the label text.

The system name has the format of “camelCase” :

 Every word (except the first one) has it’s starting character Capitalized.

 All spaces are removed

 Any non ASCII character is either converted or removed

o Accented characters are converted to its non-accented equivalent

 Å = A, Ö = O, é = e

NOTE:

If two questions have the same label – their systemName will be the same and not unique. Therefore it’s usually best to use EnumCode instead of systemName when possible.

$PX( selector )

Description:

This is the API function that is used to receive a special result object. The Result object is then used to do modifications, retrieve values, add event handlers etc.  

 Selector (String)

o A string containing a selector expression

 Returns:  

o QueryResultObject  

Example selectors:

Code QueryResultObject contains

$PX('Q1') The first question

$PX('S3') The third static item

$PX('Q*') All the questions on the foorm

$PX('SQ*') All the static items and the questions on a foorm

$PX('Q1-4') Questions 1 to 4

$PX('Q2,Q3') Questions 2 and question 3

$PX('>Q*') All questions NOT in a group/container

$PX('G1 Q*') All the questions in the first group/container (includes also questions in subcontainers if such exists)

$PX('G1>Q*') All the questions directly under the first group/container (excludes questions in subcontainers)

$PX('*1') The first of every single type (questions, static items, containers etc)  

 

QueryResultObject

The object returned emulates an array but extended with the following functions:  

.value()

.value()

Description

Get the current value of the questions in the QueryResultObject

Returns:

A string if only one value is returned An array of strings if multiple values are returned

.value( newValue )

Description Sets the value of every questions in the QueryResultObject

Parameters

newValue

 string or array (for multichoice questions)

 Cannot be null

Returns:

The initial QueryResultObject ( for chaining )

.value( newValue, getRawValue )

Description Returns the raw ("hidden") value of the questions

Parameters newValue  Must be null! getRawValue  Must be true!

Returns A string if only one value is returned An array of strings if multiple values are returned  

.label()

.label()

Description  Returns the label of the questions in the query result set

Returns  A string if only one value is returned  An Array if multiple values are returned (if multiple questions are in the queryResultObject)

.children()

.children()

Description  Returns the child items in matched containers/groups

Returns  A new QueryResultObject with the childitems

.is()

.is( selector )

Descroption  Used to verify that the QueryResultSet matches the selector

Parameters  Selector o A selector string to match against the items in the queryResultObject

Returns  A Boolean value that is true if the selector is matched against the items  

.equals()

.equals(value, contains)

Descroption  Used to check if the questions value equals the value provided

Parameters  value o String or Array o The value to validate against  contains o Boolean o If set to true – any occurrences of the value provided will return true o If set to false – the value must be exactly the value provided

Returns  A Boolean value

.each()

.each(callback)

Description  Used to iterate through all the items in the QueryResultObject

Parameters  callback o function(index, valueObject) o Will be called once per item. The this variable in the function scope will be a new QueryResultObject containing only the iterated item

Returns  The original QueryResultObject (for chaining)

.find()

.find( selector )

Descroption  Used to find children (in a group/container for instance) that matches the specified selector.

Parameters  selector o selector string

Returns  A new QueryResultObject with the matched childitems

.on()

.on(event, callback)

Description  Adds an eventhandler to the items in the QueryResultObject

Parameters  Event o String o The name of the event ( click, change, mousedown, et.c )  callback o function(event) o The function that will be called when the event is triggered

Returns  The original QueryResultObject (for chaining)

.off()

.off()

Description  Removes all the event listeners from  the items in the QueryResultObject

Returns  The original QueryResultObject (for chaining)

.off( event )

Description   Removes event listeners of the specified eventName from the items in the QueryResultObject

Parameters  event o String o The name of the event to remove (click, change, mousedown et.c.)

Returns  The original QueryResultObject (for chaining)