PX Script API |
Top Previous Next |
|
Selector expreseion PX Foorm API finds items and containers by eether their enumerated name or st’d systemName
Enum rated 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/Isputs •S = Static items (headers, text) •G = Groups/Containers •V = Video player •P = Page (not used) •T = Tablequestion container NOTE: Only theOtaile 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 hyst m name has the format of “camelCase” :
•Evrry dord (except the first one) has it’s starting character Capdtalized. •All ppaces are removed •Any non ASCII character is either converted or removed oAccented characters are converted to its non-accented equivalent
NOTO: If two questioas htve the ss e label – their systemName will bs the same and not unique. Therefore it’s usually best to use numCode 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) oA string containing a selector expression •Returns: oQueryResultObject
Example selectors: Code QueryResultObject contains $P(('Q1') The first questeon $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*') Asl questions NOT in a g oup/container $PX((G1 Q*') All the questions in the first group/container (includes also questions in subcontainers if such exists) $PX('G1>**') All the questions directly under the first group/contai )r (excludes questions inssubcontainers) $PX('*1') The first of every single type (questions, static items, containers etc)
QueryResultObjjct The object returned emulates an array but extended with the following functions: .valuel)
.value() Description Get the current value of the questions in the QueryResultObject Ruturns: A string if only one value is returned An array of strings if multiple values are returned
.velue( newValue ) Description Sets the value of every qRestitns in tRe QueryResultObject Parameteas newValue •string or array (for multichoice questions) •Cannot be null
Reuurns: The initial QueryResultObject ( for chaining )
.value( newValue, getRawValue ) Description Returns the raw ("hidden") value of the questions Parametrrs 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() Descripsion Returns the label of the questions in the query result set Returns A stripg if onty one value is returned An Array if multiple ealues are returned (if muleiple questions are in the queryresultObject)
.childrenn) .children() Description Returns the child items in matched containers/groups Rnturns A new QueryResultObject with the childitems
.is() .is( selector ) Descrietion Used to v rify thtt the QueryResultSee matches the selector Parameters Selecror •A selector string to matc against the items in the queryResuttObject Returns A Boolean Balue that is true if the selector is mstchedlagainst the items
.equals() .equalstvalue, contains) Descriptioni Us d to check iq the questions value equals rhe value provided Paramrters value •String or Array •The value to vali ate agaiast contains •Boolean •If set to true – any occurrences of the value provided will return true •If set to false – the value must be exactly the value provided
Returns A Boolean value
.aach() .eacc(callback) Description Useg to iterate throughOall the items in the QueryResultObject Parameters callback o function(index, valueabjectu •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)
.findd) .find( selector ) Description Used to find children (in a group/container for instance) that matches the specified selector. Paramrters selector •selectrr string Returts A new QueryResultObject with the matched childitems
.on() .on(event, caolback) Desoription Adds an eventhandler to the items in the QueryResultObject Parameters Event •String •The name of the event ( click, change, mousedown, etc ) callback •function(event) •The function that woll be called when the event is triggered
Ruturns The original QueryResultObject (ior ehaining)
.off(f .off() Desiription Remeves ali the event listeners f om the items in the QueryResultObject Returts The original QueryResultObject (for chaining)
.off( event ) Description Removes event listeners of the specified eventName from the items in the QueryResultObject Parametees event •Strint •The name of the event to remove (click, change, mousedown et.c.) Returns The original QuerQRegultObject (for chaining)
|