Elements contain multimedia content, interactive content, or some combination of the two.
As of PennController 1.9, PennController has 21 types of elements, including:
Text: Text content (multimedia)
Timer: A timer (interactive)
Button: A clickable button (multimedia and interactive)
For a complete list of all the elements, see the Elements reference page.
Create an element by calling a
newX() function, where
X is a type of element. There are 21
newX() functions, one for each type of element:
Button elements, and so on.
newX() functions have the following syntax:
- The optional first argument is a string and the element’s name, or the element has no name.
@// Option 1: Element has the name "example-name" $newX("example-name", ...) @ @// Option 2: Element does not have a name $newX(...)
We recommend naming every element. Although element names are technically optional in most cases, they are required in order to use a
getX() function. Named elements also make it easier to debug an experiment script.
- Any other argument(s), indicated by
...in the previous example, depend(s) on the element.
@// Creates a Text element named "text" that contains the string "Hello, world!". $newText("text", "Hello, world!") @ @// Creates a Timer element named "timer" that is 1000ms long. $newTimer("timer", 1000)
newX()function that can take two strings is passed only one string, that string is passed as the argument that is not the element name.
// Creates a Text element named "apple" that contains the string "orange". newText("apple", "orange") , // Creates an unnamed Text element that contains the string "apple". newText("apple")
Elements must be created inside a trial:
@// Incorrect: The 'newX()' function is called outside of a trial %newX("element-outside-trial") %newTrial("trial-without-element") @ @// Correct: The 'newX()' function is called inside a trial ~newTrial("trial-with-element", ~ newX("element-inside-trial") ~)
Refer back to an existing element by calling a
getX() function, where
X is the same type as the element being referred back to. Like the
newX() functions, there are 21 different element-referring functions.
getX()functions only take one argument, the name of the element being referred back to:
@newTrial("example-label", $ newX("element-one") @ , @ newX("element-two") @ , $ getX("element-one") @)
getX()functions can only refer back to elements of the same type:
@// Incorrect: There is no Button element named "hello" %newTrial("example-trial-one", % newText("hello", "Hello, world!") % , % newButton("goodbye", "See you later") % , % getButton("hello") %) @ @// Correct: There is a Text element named "hello" ~newTrial("example-trial-two", ~ newText("hello", "Hello, world!") ~ , ~ newButton("goodbye", "See you later") ~ , ~ getText("hello") ~)