oTree Programming Tips

The Frontend (HTML, CSS, JavaScript)

1. General advice for constructing and organising webpages.
   • Adopt an existent framework to simplify the development of informative webpages, for example, Bootstrap.
   • Alternatively, if you do need to modify some webpage elements:
     • Avoid writing the styles directly inside the element tag like this:

         <element style="..."></element>
       

     • Instead, assign a class name for each style and manage the styles uniformly in CSS files under the folder ./static/. When you are going to apply the styles on certain page element, first link the style sheet in the page head:

         <link rel="stylesheet" type="text/css" href="" />
       

       Then simply specifying the class name in the element tag:

         <element class="myClass"></element>
       

2. Access HTML elements in JavaScript.
   • Access by element properties.

       getElementByID() // return element
       getElementsByName() // return list
       getElementsByTagName() // return list
       getElementsByClassName() // return list
     

   • Access by CSS selector.

       querySelector() // return element
       querySelectorAll() // return list
     

3. Useful reference.
   • HTML color codes
   • CSS selector

The Backend (Python)

1. Make sure the HTML syntax is recognised in the string passed to the frontend.
   • Install the package MarkupSafe.
   • Wrap the string with Markup():

       from markupsafe import Markup
     
       label = Markup("My string with <strong>HTML syntax.</strong>")
     

2. Understand how live pages work.
   • The communication between the frontend and the backend always follows the process below:
     • The frontend sends data to the backend (usually in an onclick event):

         liveSend(data_send)
       

     • The backend receives the data and processes it. Then it response data to the frontend to update the page:

         class myLivePage(Page):
             def live_method(player, data):
                 # codes to process the data
                 return {
                     player_id: data_response
                 }
       

     • The frontend receives the response data and processes it:

         function liveRecv(data) {
             // codes to process the data
         }
       

   • The liveSend() and liveRecv() functions are oTree built-in features, you cannot change their names or use other functions to replace it.
   • You cannot start the communication from the backend (the most common case is that you want to initialise the page by sending configuration data to it). Alternatively, you can send a special message from the frontend on page load, then process this special indicator in the backend and response with initialisation data to the frontend:

       document.addEventListener("DOMContentLoaded", (event) => {
           liveSend({ "type": "init" });
       });
     

       class myLivePage(Page):
           def live_method(player, data):
               if (data["type"] == "init"):
                   return {
                       player_id: data_init
                   }
               else:
                   return {
                       player_id: data_response
                   }
     

3. Control the randomisation level.
   • You can control the randomisation level of your app by setting different seeds with random.seed(), in case you want the randomisation result being the same within each session, each round, or each participant. This is especially useful when you do not want current randomisation features displayed on the participant screen being changed after page refresh. Here are some examples on seeds commonly used in practice:
     • session.code for session level randomisation
     • round_number for subsession/round level randomisation
     • participant.code for participant level randomisation
   • You should be careful when using group.id or player.id as controls, because there can be duplicate IDs across rounds or groups. If you do not want the same randomisation result in all rounds or in all groups, use the concatenated string round_number + group.id or round_number + group.id + player.id instead.