Function element

Function elements let you execute javascript functions at a given point during the trial.

Creation:

newFunction("myFunction", () => console.log("hello world") )

Example:

Note: no pre-comma linebreaks in code below

newFunction("setKeyTime", function(){ this.keyTime = Date.now(); }),
newFunction("keyTimerDelay", function(){ return Date.now() - this.keyTime > 10; }),
newButton("Start", "Start")
    .print()
    .wait(),
newText("instrutions", "Quick, you have one second to press the T key!")
    .print(),
newTimer("quick", 1010)
    .start(),
newKey("t", "T")
    .wait(),
getFunction("setKeyTime")
    .call(),
getTimer("quick")
    .wait("first"),
getFunction("keyTimerDelay")
    .test.is(true)
    .success(
        newText("success", "Good job!")
            .print()
    )
    .failure(
        newText("failure", "Too slow...")
            .print()
    )

The code above adds a button to the page; after it is clicked, instructions to press T in less than 1 second appears on the screen, and a 1010ms timer starts running. The script waits for the timer to elapse after the T key is pressed: if this takes more than 10ms, it means the there was more than 10ms left to the timer after the key was pressed, and Good job! appears on the screen.

The code above manipulates two function elements, named setKeyTime and keyTimerDelay. Both elements are created at the beginning of the trial. The function of setKeyTime is executed only after the T key was pressed: it sets an trial-internal variable (this.keyTime) to the current timestamp. The function of keyTimerDelay is executed after the timer has elapsed (and the key was pressed): its return value is tested, and if it is true (i.e. the delay between the current time and the time when the key was pressed is greater than 10ms) then the success command is executed, otherwise the failure command is executed.

Actions

function.call

getFunction(id).call()

Executes the function.

Example:

newFunction("setKeyTime", function(){ this.keyTime = Date.now(); }),
newFunction("keyTimerDelay", function(){ return Date.now() - this.keyTime > 10; }),
newButton("Start", "Start")
    .print()
    .wait(),
newText("instrutions", "Quick, you have one second to press the T key!")
    .print(),
newTimer("quick", 1010)
    .start(),
newKey("t", "T")
    .wait(),
getFunction("setKeyTime")
    .call(),
getTimer("quick")
    .wait("first"),
getFunction("keyTimerDelay")
    .test.is(true)
    .success(
        newText("success", "Good job!")
            .print()
    )
    .failure(
        newText("failure", "Too slow...")
            .print()
    ),
getButton("Start")
    .wait()

standard.setVar

getElement(id).setVar( varName ) (since beta 0.3)

Stores the current value of the element in the Var element named varName (if it exists).

What the current value corresponds to is specific to each element type:

  • For Audio elements, it corresponds to the timestamp of the end of the last playback so far (0 if never played back or playback never eneded).
  • For Button elements, it corresponds to the timestamp of the last click so far (0 if never clicked).
  • For Canvas elements, it corresponds to the number of elements it currently contains.
  • For Function elements, it corresponds to the value returned by the function.
  • For Html elements, it corresponds to whether the element is completely filled.
  • For Image elements, it corresponds to whether the image is currently being displayed.
  • For Key elements, it corresponds to the last key that was pressed so far (empty string if no key has been pressed so far).
  • For Scale elements, it corresponds to the value of the last option that was selected (NaN if no option has been selected so far).
  • For Selector elements, it corresponds to the last element that was selected (null if no element has been selected so far).
  • For Text elements, it corresponds to the current text.
  • For TextInput elements, it corresponds to the text that is currently in the input box.
  • For Timer elements, it corresponds to whether the timer has elapsed.
  • For Tooltip elements, it corresponds to whether the tooltip has been validated.
  • For Var elements, it corresponds to the element’s value.
  • For Video elements, it corresponds to the timestamp of the end of the last playback so far (0 if never played back or playback never eneded).
  • For VoiceRecorder elements, it corresponds to the last recording (undefined if no recording so far).
  • For Youtube elements, it corresponds to whether the video has been played.

Example:

newVar("name")
,
newTextInput("nameInput", "What is your name?")
    .settings.once()
    .print()
    .wait()
    .setVar("name")
,
newText("helloname")
    .settings.before( newText("hello", "Hello ") )
    .settings.text( getVar("name") )
    .print()

Creates a Var element named name and adds a text box in which to enter a name. When the return/enter key is pressed while editing the input box, it disables the box and stores its value in the Var element named name. Then it prints a text reading Hello name, where name corresponds to the value of the Var element.

Settings

standard.settings.log

getElement(id).settings.log()

Will add lines to the results file reporting element-specific events. See each Element page to see what gets recorded, and which parameter you can pass to log.

For Canvas elements, Image elements and Text elements the results lines will report the timestamp corresponding to when print was called (if it was called).

Example

newButton("go", "Go!")
    .print()
    .wait()
,
newText("sentence", "Hello world!")
    .settings.log()
    .print()
,
newButton("done", "Done!")
    .print()
    .wait()

Tests

function.test.is

getFunction(id).test.is()

or getFunction(id).test.is( value )

Executes the function and tests the value it returns. If you specify no value, it yields success if the return value is 0, null, undefined or false.

NOTE: remember that the expression you pass as the test value is executed at the very beginning of the experiment. So calling getFunction(“myFunction”).test.is( Date.now() ) will test that the function returns the timestamp corresponding to the beginning of the experiment. In this case, you may consider rewriting your function so it takes care of testing Date.now() and returns true or false in consequence.

Example:

newFunction("timestampMultipleOfThree", () => Date.now() % 3 )
,
newText("missed", "Bad luck, try again!")
    .settings.color("red")
    .settings.bold()
,
newButton("myButton", "Click me")
    .print()
    .wait(
        getFunction("timestampMultipleOfThree")
            .testNot.is()
            .success( getText("missed").remove() )
            .failure( getText("missed").print() )
    )

Adds a button to the screen whose clicks are validated only if happening at a time when the timestamp is not a multiple of 3 (i.e., the modulo value returned by the function is different from 0).