From Lioness wiki
Jump to: navigation, search

LIONESS experiments use JavaScript to do calculations and to interact with the database. JavaScript (JS) is a widely used language for web programming. JS is executed in the browser of the participants (so, not on the server).

JavaScript code can be added to any stage of your LIONESS experiment through a JavaScript element.

Access JS variables

Values of JS variables can be accessed in other elements (e.g. a text box) by adding dollar signs on both sides of the variable name (e.g. $contribution$).

Default variables

When a participant's page loads, all variables defined in the parameters table are loaded. This is also true for the following default variables from the core table. This means that these variables are defined (i.e. have a value) in every screen and their values are accessible in JS.

Variable name Details
playerNr Number of the focal player within the session
groupNr Group number of the focal player
subjectNr Player number of the focal player within group
period Period number of the focal player within session
tStart System time in seconds upon page load

Interacting with the database

Variables specified in input elements' (numeric input, choice buttons, etc) will be automatically stored in the table 'decisions'.

JavaScript elements allow you to read from and write to the database, using the below functions. Note that each function has a 'simple' and a 'full' version. The simple versions always assume that the function pertains to the current player, the current group, and the current period. In the below examples, the simple and full versions are equivalent.

Writing to the database

You can directly write to the decisions table of the experiment's database, using the following functions. Note that, for database management reasons, it is currently not possible to create new variables in the database using 'for loops' or 'while loops'.


Function Arguments (italic = optional) Simple example
(no optional parameters)
Full example (with optional parameters)
setValue() table name, condition, variable name, value setValue('payoffThisPeriod', payoff); setValue('decisions', 'playerNr='+playerNr+' and period='+period, 'payoffThisPeriod', payoff);
record() variable name, value record('PGGshare', publicGoodShare);
setBonus() amount setBonus(payoff);

  • The function 'record()' will create a variable in the decisions table with the name of the first argument and the value of the second argument. In the example above, the decisions table would have one column with the name 'PGGshare', the value of which would equal the value of the JavaScript variable 'publicGoodShare'.
  • The function 'setBonus()' will write the value in its argument to the variable 'bonusAmount' in the 'sessions' table. It will also update the variable 'totalEarnings' in that table to the sum of bonusAmount and participationFee.
  • The value argument cannot contain any operators, such as the '+' or the '-' sign.

    Reading from the database

    Function Arguments (italic = optional) Return value Simple example
    (no optional parameters)
    Full example (with optional parameters)
    getValue() table name, condition, variable name Single element getValue('someVariable'); getValue('decisions', 'playerNr='+playerNr+' and period='+period, 'someVariable');
    getValues() table name, condition, variable name Array of elements getValues('someVariable'); getValues('decisions', 'groupNr='+groupNr+' and period='+period, 'someVariable');

    There are special functions for retrieving the values from others in your group, in the current period.

    Function Argument Return value Simple example
    (no optional parameters)
    getValuesOthers() variable name Array of elements getValuesOthers('someText');

    The obsolete functions getInt() and getFloat() are replaced by getValue(). The new getValue() function automatically returns the right type of variable (text, integer or float). The functions getInt() and getFloat() are still supported in old experiments. The same is true for the variants of getValue().

    Debugging your JavaScript code

    Needless to say, it is critical for the functioning experiments that the program code works correctly. The JS editor in LIONESS Lab provides some support in detecting syntax errors, but not all bugs in your code will be automatically detected. These bugs will only surface when you test your experiment.

    The JavaScript code of LIONESS experiments is executed in the participants' browsers. In case variables are displayed as 'NaN', or not displayed at all, chances are that your JS code has not been executed correctly. One downside of JavaScript is that the code stops being evaluated after the evaluation process has run into a mistake.

    But, don't worry. Many browsers will have built-in solutions to track the error on the page. While testing your experiment as a 'Test player', you can activate these solutions to keep track of any JavaScript errors that might occur.

    In Chrome, you can start the Developer Tools, simply by pressing F12 on your keyboard. Your screen will be split, showing the original page, and its underlying code (which you generated with LIONESS Lab) . On the top of this 'code' section you find a number of tabs (Elements, Console, Sources, ...). The execution of JavaScript can be viewed in the Console tab. In the majority of cases, bugs are easily identified here. Common bugs are spelling mistakes in variables, or mistakes in calling functions.

    When you have spotted the mistake on a participant page, you can go back to LIONESS Lab and spot the mistake in the JS code in the corresponding screen. If you make a change, you can press 'Compile and test' and then 'recompile experiment (keep tables)' to immediately see whether your change has fixed the bug.

    In Firefox, a very similar tool is available, called Firebug. This is a plugin with a functionality very similar to Chrome's Developer Tools.

    Commenting your JavaScript code

    It is always a good idea to add comments to your code. It makes your code transparent to others and can also help you understanding it when you get back to it at a later time. Now, the usual way to add comments to JS code (e.g. for adding clarifications), is by using the double slash "//". Note that not all web servers will interpret this code the same way. This has to do with line breaks surrounding this code. To prevent your code from being corrupted, use "/* ... */", where the any comments go on the placeholder dots.