Elements

Types of elements

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.

Creating an element

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: newText() creates Text elements, newTimer() creates Timer elements, newButton() creates Button elements, and so on.

All 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(...)
note

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)

    If a 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")
~)

Referring back to an element

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.

  • All 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")
  ~)