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

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".

Elements must be created inside a trial:

@// Incorrect: The 'newX()' function is called outside of a trial
@// Correct: The 'newX()' function is called inside a trial
~    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:
      $    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"
      %    newText("hello", "Hello, world!")
      %    ,
      %    newButton("goodbye", "See you later")
      %    ,
      %    getButton("hello")
      @// Correct: There is a Text element named "hello"
      ~    newText("hello", "Hello, world!")
      ~    ,
      ~    newButton("goodbye", "See you later")
      ~    ,
      ~    getText("hello")